Mensagens

Enviar pelo número conectado e ler o histórico de uma conversa.

Enviar

POST/api/v1/messages

Manda texto ou mídia. Se o telefone ainda não é contato, o contato e a conversa nascem aqui.

Corpo (JSON)

channelIdtextocom chave de conta
Por qual número falar. Com uma chave de canal pode ser omitido — o escopo preenche. Com a chave da conta é obrigatório: faltando, a resposta é 422 Informe channelId.
phonetexto
Para quem. Informe phone ou conversationId.
conversationIdtexto
Responder numa conversa que já existe. Precisa ser do mesmo canal, senão 422.
texttexto
Até 4096 caracteres. Sem mídia, é a mensagem; com mídia, vira a legenda se não houver caption.
mediaUrlURL
Um arquivo numa URL pública, que nós baixamos e enviamos. O endereço precisa ser público de verdade: se ele aponta para rede interna (ou redireciona para lá), ou se redireciona mais de três vezes, a resposta é 422 e nada é enviado.
mediaIdtexto
Um arquivo do Drive do LinkZap — mais confiável que URL para o que você reenvia sempre.
captiontexto
Legenda da mídia, até 1024 caracteres.

Pedidocurl

curl -X POST https://linkzap.orion.moe/api/v1/messages \
  -H "Authorization: Bearer lz_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "chn_9f2a...",
    "phone": "5592999990000",
    "text": "Sua consulta está confirmada para quinta, 9h."
  }'

RespostaJSON

{
  "data": {
    "messageId": "msg_7bd0...",
    "conversationId": "cnv_5ad2...",
    "channelId": "chn_9f2a..."
  }
}

É preciso um de text, mediaUrl ou mediaId, e um de phone ou conversationId — faltando, a resposta é 422 dizendo qual.

409 é a recusa honesta

Se o número estiver desconectado, desligado ou impedido de enviar, a resposta é 409 com o motivo real em palavras, e nada foi enviado. Isso é diferente de um erro: dá para mostrar o motivo para a sua equipe e tentar de novo depois. GET /channels antecipa o mesmo motivo.

A mensagem aparece na caixa creditada como API, e não pausa a Aura — quem pausa a automação é uma pessoa respondendo pelo painel ou pelo celular. Se você está montando um chatbot próprio, leia a receita correspondente antes.

Ler o histórico

GET/api/v1/messages

As mensagens de uma conversa, da mais recente para a mais antiga.

Parâmetros da URL

conversationIdtextoobrigatório
Obrigatório. Ache o id em GET /conversations.
pageinteiro
A partir de 1.
limitinteiro
De 1 a 200. Padrão 50.
includeNotesbooleano
Por padrão as notas internas da equipe não vêm. true as inclui.

Pedidocurl

curl "https://linkzap.orion.moe/api/v1/messages?conversationId=cnv_5ad2...&limit=20" \
  -H "Authorization: Bearer lz_SUA_CHAVE"

RespostaJSON

{
  "conversationId": "cnv_5ad2...",
  "data": [
    {
      "id": "msg_7bd0...",
      "direction": "out",
      "kind": "text",
      "text": "Sua consulta está confirmada para quinta, 9h.",
      "media": null,
      "author": { "kind": "automation", "label": "Fluxo · Confirmação" },
      "status": "read",
      "receipts": {
        "sent": "2026-09-21T14:02:59.000Z",
        "delivered": "2026-09-21T14:03:04.000Z",
        "read": "2026-09-21T14:05:22.000Z"
      },
      "externalId": "3EB0...",
      "replyToId": null,
      "transcript": null,
      "createdAt": "2026-09-21T14:02:59.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 48
}

direction é in (o contato), out (saiu daqui) ou note (nota interna, só com includeNotes=true).
author diz quem escreveu: contact, team (com o nome da pessoa) ou automation (com a origem — Aura, Fluxo · X, Campanha…). Mensagens antigas, de antes de existir esse carimbo, vêm como Automação.
media.url só existe depois que o arquivo foi baixado para cá; enquanto media.pending for true, a URL é null — preferimos isso a entregar um link que não abre.
transcript traz a transcrição de uma nota de voz, quando a Aura já transcreveu.

Notas internas são internas

Elas são o que a equipe escreve para a equipe, e foram escritas com essa expectativa. Se você espelha a conversa num portal que o cliente final enxerga, não peça includeNotes=true.