Pular para o conteúdo

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.

  • identity busca exata por telefone (só dígitos), BSUID, @usuário do Instagram, IGSID ou PSID.
  • q busca pelo começo do nome do contato (até 64 caracteres).
  • source diz de onde veio a mensagem: customer (o contato), api, campaign, business_app (o app no celular, na coexistência) ou history (histórico importado); campaign_id traz só as mensagens de uma campanha.
  • A mídia aparece como parte da mensagem, com id. O arquivo sai em GET /v1/media/{id}/content.

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.

Janela do terminal
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 → 400 invalid_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);
}

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); sem until, agora;
  • um since mais 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.