Mensagens

Envie e receba mensagens dentro de conversas. Suporta texto, anexos, cards interativos e diferentes tipos de conteúdo.

GET/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages

Retorna as mensagens de uma conversa, ordenadas cronologicamente.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numérico da conta
`conversation_id`(path)	`integer`	Sim	ID numérico da conversa

curl -s "https://chat.seudominio.com/api/v1/accounts/1/conversations/123/messages" \
  -H "api_access_token: YOUR_TOKEN" | jq .

200Lista de mensagens

json

{
  "payload": [
    {
      "id": 1001,
      "content": "Ola, preciso de ajuda!",
      "message_type": 0,
      "content_type": "text",
      "sender": {
        "id": 456,
        "name": "Joao Silva",
        "type": "contact"
      },
      "conversation_id": 123,
      "created_at": 1708000000
    },
    {
      "id": 1002,
      "content": "Claro! Como posso ajudar?",
      "message_type": 1,
      "content_type": "text",
      "sender": {
        "id": 1,
        "name": "Agente 1",
        "type": "user"
      },
      "conversation_id": 123,
      "created_at": 1708000060
    }
  ]
}

POST/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages

Envia uma nova mensagem em uma conversa. Pode ser texto, nota interna ou mensagem com anexo.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numérico da conta
`conversation_id`(path)	`integer`	Sim	ID numérico da conversa

Header opcional

Nome	Tipo	Obrigatorio	Descricao
`Idempotency-Key`(header)	`string`	Nao	Chave opaca de 1 a 128 caracteres ASCII visíveis, sem espaços, para identificar um único envio lógico

Body

Nome	Tipo	Obrigatorio	Descricao
`content`	`string`	Nao	Texto da mensagem (opcional quando há anexo)
`message_type`	`string`	Nao	Tipo: outgoing (padrão), incoming, activity
`private`	`boolean`	Nao	true para nota interna (não visível ao contato)
`content_type`	`string`	Nao	Tipo de conteúdo: text, input_select, cards, form, article
`content_attributes`	`object`	Nao	Atributos extras para conteúdos interativos
`attachments[]`	`file`	Nao	Arquivos anexos (multipart/form-data). Aceita múltiplos.
`template_params`	`object`	Nao	Parâmetros de template (WhatsApp template messages)
`idempotency_key`	`string`	Nao	Alternativa no body JSON ou multipart ao header Idempotency-Key; segue o mesmo formato de 1 a 128 caracteres ASCII visíveis, sem espaços

Envio idempotente

Use a mesma chave ao repetir o mesmo envio lógico depois de timeout ou falha de rede. Dentro da mesma conta e conversa, a repetição retorna a mensagem criada anteriormente, não dispara outra entrega e acrescenta o header Idempotency-Replayed: true. A mesma chave pode representar outro envio em uma conversa diferente.

Se o header Idempotency-Key estiver presente, ele sempre prevalece sobre idempotency_key do body, inclusive quando estiver vazio ou for inválido; nesse caso não há fallback para o body e a resposta é 422. Sem nenhuma das duas formas, a criação continua sem deduplicação por chave.

Durante ativação, rollback ou falha de leitura do gate compartilhado, uma chave válida recebe 503 e nenhuma mensagem é criada. Chaves malformadas continuam recebendo 422. Reenvie somente depois que o administrador confirmar a ativação da idempotência.

curl -i -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/123/messages" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Idempotency-Key: atendimento-123-resposta-4567" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Sua solicitação foi registrada com o número #4567.",
    "message_type": "outgoing"
  }'

200Mensagem criada; em um replay, retorna o mesmo recurso com Idempotency-Replayed: true.

json

{
  "id": 1003,
  "content": "Sua solicitação foi registrada com o número #4567.",
  "message_type": 1,
  "content_type": "text",
  "private": false,
  "conversation_id": 123,
  "created_at": 1708000120
}

422Payload de mensagem ou chave de idempotência inválida.

json

{ "error": "Idempotency-Key must be 1-128 visible ASCII characters without spaces" }

503Envios idempotentes temporariamente indisponíveis porque a ativação do rollout não pode ser confirmada.

json

{ "error": "Idempotency-Key is temporarily unavailable" }

DELETE/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{message_id}

Marca uma mensagem como deletada. O conteúdo é substituído por um placeholder e os anexos são removidos — a mensagem em si permanece no histórico.

Soft delete

Este endpoint não remove o registro da mensagem. Ele substitui o content por um texto padrão de mensagem deletada, define content_attributes.deleted = true e remove os anexos. O conversation_id e message_id são resolvidos dentro da conta autenticada.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numérico da conta
`conversation_id`(path)	`integer`	Sim	display_id da conversa (escopado à conta)
`message_id`(path)	`integer`	Sim	ID da mensagem (escopado à conversa)

bash

curl -X DELETE "https://chat.seudominio.com/api/v1/accounts/1/conversations/123/messages/1003" \
  -H "api_access_token: YOUR_TOKEN"

200Mensagem marcada como deletada

Tipos de Conteúdo

Além de texto simples, mensagens suportam conteúdos interativos:

Tipo	Descrição
`text`	Mensagem de texto simples
`input_select`	Menu de opções para o contato selecionar
`cards`	Carrossel de cards com título, descrição e ações
`form`	Formulário interativo para coleta de dados
`article`	Artigo da central de ajuda

Enviando Anexos

Para enviar arquivos, use multipart/form-data no lugar de JSON:

bash

curl -i -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/123/messages" \
  -H "api_access_token: YOUR_TOKEN" \
  -F "content=Segue o documento solicitado" \
  -F "message_type=outgoing" \
  -F "idempotency_key=atendimento-123-anexo-1" \
  -F "attachments[]=@/path/to/documento.pdf"

Formatos suportados

Imagens (PNG, JPG, GIF, WebP), documentos (PDF, DOC, XLS), áudio e vídeo. Tamanho máximo: 40MB por arquivo.