API e SDK
Histórico
Conversas, contatos e mensagens gravados pelo Messajo: filtros, paginação por cursor e como a retenção limita o intervalo.
O Messajo guarda o que passa pelas conexões e deixa consultar pela API com a permissão read. Tudo respeita as conexões da chave: chave presa a algumas conexões só vê o que é delas.
| Rota | Filtros | Ordem |
|---|---|---|
GET /v1/conversations |
connection_id, contact_id, window=open|closed, since, until (sobre last_message_at) |
last_message_at mais recente primeiro |
GET /v1/conversations/{id}/messages |
direction, type, since, until, order=desc|asc |
created_at |
GET /v1/messages |
connection_id, contact_id, conversation_id, direction, status, type, source, campaign_id, since, until, order |
created_at |
GET /v1/contacts |
connection_id, channel, identity, q, since |
last_seen_at mais recente primeiro |
Cada uma tem a versão por id (GET /v1/conversations/{id}, GET /v1/messages/{id}, GET /v1/contacts/{id}). Datas em ISO 8601.
identitybusca exata por telefone (só dígitos), BSUID, @usuário do Instagram, IGSID ou PSID.qbusca pelo começo do nome do contato (até 64 caracteres).sourcediz de onde veio a mensagem:customer(o contato),api,campaign,business_app(o app no celular, na coexistência) ouhistory(histórico importado);campaign_idtraz só as mensagens de uma campanha.- A mídia aparece como parte da mensagem, com
id. O arquivo sai emGET /v1/media/{id}/content.
Paginação por cursor
Seção intitulada “Paginação por cursor”Toda lista devolve { data, next_cursor }. Passe limit (até 100) e, para a próxima página, o next_cursor recebido em cursor. Acabou quando next_cursor vier null.
curl "https://api.messajo.com/v1/messages?conversation_id=cnv_...&limit=100" \ -H "Authorization: Bearer $MESSAJO_API_KEY"{ "data": [ { "id": "msg_...", "conversation_id": "cnv_...", "contact_id": "ctc_...", "direction": "inbound", "type": "text", "text": { "body": "Oi! Ainda tem o cupom?" }, "source": "customer", "status": "received", "campaign": null, "created_at": "2026-11-10T14:03:11.000Z" } ], "next_cursor": "eyJ2IjoxLCJrIjpbIjIwMjYtMTEtMTBUMTQ6MDM6MTEuMDAwWiIsIm1zZ18uLi4iXX0"}- O cursor é opaco: não monte nem altere. Cursor quebrado →
400invalid_cursor. - O cursor guarda a posição, não um retrato da lista: o que chegar depois não duplica nem pula itens já lidos.
- Use os mesmos filtros em todas as páginas.
Com o SDK, o paginate segue o cursor sozinho:
for await (const message of messajo.paginate(messajo.messages.list, { conversation_id: "cnv_...",})) { console.log(message.id);}Intervalo e retenção
Seção intitulada “Intervalo e retenção”Mensagens são guardadas por mês. Toda consulta de mensagens tem um intervalo since/until:
- sem
since, vale o início da retenção da organização (90 dias por padrão); semuntil, agora; - um
sincemais antigo que a retenção é cortado no limite, sem erro: o que passou do prazo já foi apagado; - intervalos curtos respondem mais rápido.
A retenção conta da gravação no Messajo. O histórico de 6 meses importado na coexistência é gravado no dia da importação e sai junto com o resto quando o prazo vence.