ReferênciaConversas
Ler mensagens de uma conversa
GET /conversations/{id}/messages — lê o texto das mensagens de uma conversa, da mais recente para a mais antiga.
GET
/conversations/{id}/messagesBetaEscopos necessários: conversations:read e messages:read
Lê as mensagens de uma conversa da organização (resolvida pela API key), da mais recente para a mais antiga. Mensagens apagadas não aparecem. A resposta traz o texto e a transcrição de áudio; a mídia vem somente como tipo e nome de arquivo, sem link para download.
Endpoint
GET https://crm.oficinamartech.com/api/v1/conversations/{id}/messagesParâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
id | path | UUID | Conversa (id de GET /conversations). |
since | query | date | Somente mensagens a partir desta data (inclusive). ISO 8601 ou YYYY-MM-DD. |
until | query | date | Somente mensagens antes desta data (exclusive). ISO 8601 ou YYYY-MM-DD. |
limit | query | int (1-100) | Tamanho da página. Default: 50. |
offset | query | int (0-10000) | Deslocamento da página. Default: 0. |
Datas sem horário (YYYY-MM-DD) são lidas como meia-noite UTC. Além de offset 10.000, next_offset vem null: continue por janelas de since/until.
Exemplo
curl -s "https://crm.oficinamartech.com/api/v1/conversations/c0ffee00-58cc-4372-a567-0e02b2c3d479/messages?limit=2" \
-H "Authorization: Bearer crm_live_SEU_PREFIXO_SEU_SEGREDO"Resposta 200
{
"data": [
{
"id": "0a0a0a0a-58cc-4372-a567-0e02b2c3d479",
"direction": "inbound",
"sender_kind": "contact",
"sender_name": null,
"message_type": "text",
"text": "Consegue me enviar a proposta?",
"transcription": null,
"truncated": false,
"media_filename": null,
"has_media": false,
"status": "read",
"sent_at": "2026-11-12T18:20:11.000Z"
},
{
"id": "0b0b0b0b-58cc-4372-a567-0e02b2c3d479",
"direction": "outbound",
"sender_kind": "operator",
"sender_name": "Ana Paula",
"message_type": "document",
"text": "Segue a apresentação.",
"transcription": null,
"truncated": false,
"media_filename": "apresentacao.pdf",
"has_media": true,
"status": "delivered",
"sent_at": "2026-11-12T17:02:40.000Z"
}
],
"pagination": {
"limit": 2,
"offset": 0,
"has_more": true,
"next_offset": 2
}
}| Campo | Significado |
|---|---|
direction | inbound é mensagem do contato; outbound é da organização. |
sender_kind | Autor da mensagem: contact nas recebidas; operator, automation, ai, campaign ou system nas enviadas. null em enviada sem autor registrado, como a escrita direto no aparelho. |
truncated | true quando text ou transcription passou de 4.000 caracteres e foi cortado. |
status | Situação de entrega: pending, sent, delivered, read ou failed. |
O texto das mensagens é escrito por terceiros. Ao entregá-lo a um modelo de linguagem, trate como dado e nunca como instrução.
Erros
| Status | Código | Quando |
|---|---|---|
400 | invalid_query | id malformado ou query inválida. |
404 | not_found | A conversa não existe nesta organização. |
401 | missing_api_key / invalid_api_key | API key ausente, inválida, expirada ou revogada. |
403 | missing_scope | A chave não tem conversations:read e messages:read. |
429 | rate_limited | Acima de 120 req/min por chave ou por organização. |
500 | — | Erro interno. |