Listar conversas
GET /conversations — lista as conversas da organização com contato, canal, situação, responsável e instantes da última atividade.
/conversationsBetaEscopo necessário: conversations:read
Lista as conversas da organização (resolvida pela API key), da atividade mais recente para a mais antiga (last_message_at decrescente). Cada linha traz o contato, o canal, a situação, o responsável e a prévia da última mensagem. Para o conteúdo completo, use GET /conversations/{id}/messages.
Endpoint
GET https://crm.oficinamartech.com/api/v1/conversationsParâmetros de query
| Parâmetro | Tipo | Descrição |
|---|---|---|
status | open | pending | impedido | resolved | lost | archived | Filtra por situação. |
channel | whatsapp | whatsapp_cloud_api | instagram | telegram | email | Filtra por canal. |
assigned_to | UUID | none | Filtra pelo responsável (user_id de GET /members); none devolve as conversas sem responsável. |
contact_id | UUID | Filtra por contato. |
is_group | true | false | false exclui grupos; true devolve só grupos. |
active_since | date | Somente conversas com última mensagem a partir desta data (inclusive). ISO 8601 ou YYYY-MM-DD. |
active_until | date | Somente conversas com última mensagem antes desta data (exclusive). ISO 8601 ou YYYY-MM-DD. |
limit | int (1-100) | Tamanho da página. Default: 50. |
offset | int (0-10000) | Deslocamento da página. Default: 0. |
Um parâmetro fora desta lista é recusado com 400.
A paginação informa has_more e next_offset, sem total: contar todas as conversas de um filtro custaria mais que a própria página. offset vai até 10.000; além disso next_offset vem null mesmo com has_more true. Para percorrer um histórico longo, avance por janelas de active_since/active_until. Datas sem horário (YYYY-MM-DD) são lidas como meia-noite UTC.
Exemplo
curl -s "https://crm.oficinamartech.com/api/v1/conversations?status=open&assigned_to=none&limit=1" \
-H "Authorization: Bearer crm_live_SEU_PREFIXO_SEU_SEGREDO"Resposta 200
{
"data": [
{
"id": "c0ffee00-58cc-4372-a567-0e02b2c3d479",
"contact_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"contact": {
"name": "Maria Souza",
"phone": "+5511999990000",
"email": "maria@example.com"
},
"channel": "whatsapp",
"status": "open",
"status_reason": null,
"is_group": false,
"chat_name": null,
"assigned_to": null,
"assigned_at": null,
"unread_count": 2,
"needs_human_agent": false,
"last_message_at": "2026-11-12T18:20:11.000Z",
"last_customer_message_at": "2026-11-12T18:20:11.000Z",
"last_operator_message_at": "2026-11-12T17:02:40.000Z",
"last_message_preview": "Consegue me enviar a proposta?",
"outcome_type": null,
"outcome_label": null,
"outcome_set_at": null,
"created_at": "2026-11-10T13:00:00.000Z",
"updated_at": "2026-11-12T18:20:11.000Z"
}
],
"pagination": {
"limit": 1,
"offset": 0,
"has_more": true,
"next_offset": 1
}
}contact é null quando a conversa não tem contato vinculado. last_customer_message_at posterior a last_operator_message_at indica conversa aguardando resposta da equipe.
Erros
| Status | Código | Quando |
|---|---|---|
400 | invalid_query | Query inválida (parâmetro desconhecido, UUID malformado, situação ou canal desconhecido, data inválida). |
401 | missing_api_key / invalid_api_key | API key ausente, inválida, expirada ou revogada. |
403 | missing_scope | A chave não tem o escopo conversations:read. |
429 | rate_limited | Acima de 120 req/min por chave ou por organização. |
500 | — | Erro interno. |