VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp: atendimento

Conversas e mensagens

Lista as conversas do WhatsApp, abre uma conversa, pagina as mensagens, exporta em CSV e baixa a mídia.

Uma conversa (thread) liga um telefone de cliente a um número da loja. Todas as mensagens trocadas entre os dois ficam nela, venham do cliente, do assistente automático, de um atendente ou do aplicativo WhatsApp Business. Estas cinco rotas leem tudo isso. O seller só enxerga as conversas das contas dele; uma conversa de outro seller responde 404 como se não existisse.

Listar conversas

GET/api/v1/vendor/whatsapp-confluence/threadsSeller

Lista as conversas, as mais recentes primeiro

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Parâmetros de consulta

filterstring
unreadhumanminevia_appunanswered
Atalho de filtro. unread com mensagens não lidas; human com atendimento humano ou assistente pausado; mine atribuídas a você; via_app cuja última mensagem veio do aplicativo WhatsApp Business; unanswered cuja última mensagem é do cliente.
unreadboolean
true equivale a filter=unread.
originstring
CABEH
Só conversas cuja última mensagem tem esta origem. via_app e unanswered sobrescrevem este parâmetro.
assigneeuuid
Só conversas atribuídas a este usuário.
qstring
Busca por parte do nome do contato ou do telefone, sem diferenciar maiúsculas.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 50
Itens por página, de 1 a 200. Fora disso vale 50.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/whatsapp-confluence/threads?filter=unread&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Conversas
json
{
  "page": 1,
  "threads": [
    {
      "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
      "account_id": "3b9d8c52-1f0a-4e7b-8a21-6d5c4b3a2f10",
      "customer_phone": "5511987654321",
      "contact_name": "Maria Souza",
      "assignee_user_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "assignee_name": "Ana Lima",
      "unread_count": 2,
      "last_message_at": "2026-10-10T14:32:10Z",
      "last_message_preview": "Quero 3 caixas, pode entregar amanhã?",
      "last_message_origin": "C",
      "csw_expires_at": "2026-10-11T14:32:10Z",
      "status": "A",
      "bot_mode": "H",
      "bot_mode_updated_at": "2026-10-10T14:20:00Z",
      "created_at": "2026-09-28T21:56:44Z",
      "updated_at": "2026-10-10T14:32:10Z"
    }
  ]
}

Campos da resposta

pageinteger
Página devolvida.
threadsarray
Conversas da página, da atividade mais recente para a mais antiga. Não há total: continue pedindo páginas até vir uma lista vazia.
iduuid
Id da conversa.
account_iduuid
Conta (número da loja) pela qual a conversa acontece.
customer_phonestring
Telefone do cliente, só dígitos, com DDI (5511987654321).
contact_namestring
Nome do contato no WhatsApp. Vazio se desconhecido.
customer_user_iduuid
Cliente da loja ligado a este telefone. Omitido quando não há.
assignee_user_iduuid
Usuário da equipe responsável. Omitido quando ninguém foi atribuído.
assignee_namestring
Nome do responsável. Omitido quando não há.
unread_countinteger
Mensagens do cliente ainda não marcadas como lidas.
last_message_atstring
Data da última mensagem (RFC 3339). Omitido se a conversa não tem mensagens.
last_message_previewstring
Prévia da última mensagem.
last_message_originstring
CABEH
Quem escreveu a última: C cliente, A API ou atendente pela caixa, B assistente, E aplicativo WhatsApp Business (eco), H histórico importado.
csw_expires_atstring
Fim da janela de atendimento de 24 horas, contada da última mensagem do cliente. Até lá é possível enviar texto livre. Omitido se nunca houve mensagem do cliente.
fep_expires_atstring
Fim do ponto de entrada gratuito de 72 horas aberto por anúncio que leva ao WhatsApp. Omitido quando não existe.
referralobject
Dados do anúncio de origem, como a Meta enviou. Omitido quando não veio de anúncio.
statusstring
Estado do registro da conversa, uma letra. Nenhuma rota desta seção o altera; o padrão é A. Não confunda com bot_mode.
bot_modestring
APH
Quem atende agora: A assistente, P assistente pausado por um tempo, H pessoa.
bot_mode_updated_atstring
Quando bot_mode mudou. Omitido se nunca mudou.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não é um seller, ou o seller ainda está em análise de cadastro.{"error":"vendor_pending_review"}
500Falha interna ao ler ou gravar.{"error":"..."}
Seller com número próprio

Numa loja em que vários sellers têm número, a lista traz só as conversas das contas do seu seller. Quando nenhum número tem seller dono, ou você é o único seller dono, a lista traz tudo.

Consultar conversa

GET/api/v1/vendor/whatsapp-confluence/threads/{id}Seller

Retorna uma conversa

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Parâmetros de caminho

iduuidobrigatório
Id da conversa (id de Listar conversas).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/whatsapp-confluence/threads/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Conversa
json
{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "account_id": "3b9d8c52-1f0a-4e7b-8a21-6d5c4b3a2f10",
  "customer_phone": "5511987654321",
  "contact_name": "Maria Souza",
  "assignee_user_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "assignee_name": "Ana Lima",
  "unread_count": 2,
  "last_message_at": "2026-10-10T14:32:10Z",
  "last_message_preview": "Quero 3 caixas, pode entregar amanhã?",
  "last_message_origin": "C",
  "csw_expires_at": "2026-10-11T14:32:10Z",
  "status": "A",
  "bot_mode": "H",
  "bot_mode_updated_at": "2026-10-10T14:20:00Z",
  "created_at": "2026-09-28T21:56:44Z",
  "updated_at": "2026-10-10T14:32:10Z"
}

Campos da resposta

iduuid
Id da conversa.
account_iduuid
Conta (número da loja) pela qual a conversa acontece.
customer_phonestring
Telefone do cliente, só dígitos, com DDI (5511987654321).
contact_namestring
Nome do contato no WhatsApp. Vazio se desconhecido.
customer_user_iduuid
Cliente da loja ligado a este telefone. Omitido quando não há.
assignee_user_iduuid
Usuário da equipe responsável. Omitido quando ninguém foi atribuído.
assignee_namestring
Nome do responsável. Omitido quando não há.
unread_countinteger
Mensagens do cliente ainda não marcadas como lidas.
last_message_atstring
Data da última mensagem (RFC 3339). Omitido se a conversa não tem mensagens.
last_message_previewstring
Prévia da última mensagem.
last_message_originstring
CABEH
Quem escreveu a última: C cliente, A API ou atendente pela caixa, B assistente, E aplicativo WhatsApp Business (eco), H histórico importado.
csw_expires_atstring
Fim da janela de atendimento de 24 horas, contada da última mensagem do cliente. Até lá é possível enviar texto livre. Omitido se nunca houve mensagem do cliente.
fep_expires_atstring
Fim do ponto de entrada gratuito de 72 horas aberto por anúncio que leva ao WhatsApp. Omitido quando não existe.
referralobject
Dados do anúncio de origem, como a Meta enviou. Omitido quando não veio de anúncio.
statusstring
Estado do registro da conversa, uma letra. Nenhuma rota desta seção o altera; o padrão é A. Não confunda com bot_mode.
bot_modestring
APH
Quem atende agora: A assistente, P assistente pausado por um tempo, H pessoa.
bot_mode_updated_atstring
Quando bot_mode mudou. Omitido se nunca mudou.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não é um seller, ou o seller ainda está em análise de cadastro.{"error":"vendor_pending_review"}
404Conversa de outro seller. Um id desconhecido também dá 404 em algumas rotas, mas 200 ou 502 em outras quando não há escopo de seller (veja a visão geral da seção).{"error":"thread not found"}

Mensagens da conversa

As mensagens vêm da mais nova para a mais antiga. Para paginar para trás, passe o next_before da resposta anterior como before.

GET/api/v1/vendor/whatsapp-confluence/threads/{id}/messagesSeller

Pagina as mensagens de uma conversa

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Parâmetros de caminho

iduuidobrigatório
Id da conversa (id de Listar conversas).

Parâmetros de consulta

beforeinteger
Devolve só mensagens com id menor que este valor. Omitido ou 0 devolve as mais recentes.
limitintegerpadrão: 50
Mensagens por página, de 1 a 200. Fora disso vale 50.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/whatsapp-confluence/threads/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/messages?limit=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Mensagens
json
{
  "messages": [
    {
      "id": 28,
      "thread_id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
      "wamid": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjA",
      "direction": "O",
      "origin": "A",
      "msg_type": "text",
      "body": "Olá, Maria! Seu pedido sai amanhã.",
      "status": "S",
      "meta_timestamp": "2026-10-10T14:35:00Z",
      "created_at": "2026-10-10T14:35:00Z"
    }
  ],
  "next_before": 28,
  "thread": {
    "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
    "account_id": "3b9d8c52-1f0a-4e7b-8a21-6d5c4b3a2f10",
    "customer_phone": "5511987654321",
    "contact_name": "Maria Souza",
    "assignee_user_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "assignee_name": "Ana Lima",
    "unread_count": 2,
    "last_message_at": "2026-10-10T14:32:10Z",
    "last_message_preview": "Quero 3 caixas, pode entregar amanhã?",
    "last_message_origin": "C",
    "csw_expires_at": "2026-10-11T14:32:10Z",
    "status": "A",
    "bot_mode": "H",
    "bot_mode_updated_at": "2026-10-10T14:20:00Z",
    "created_at": "2026-09-28T21:56:44Z",
    "updated_at": "2026-10-10T14:32:10Z"
  }
}

Campos da resposta

messagesarray
Mensagens da página, da mais nova para a mais antiga.
next_beforeinteger
id da mensagem mais antiga da página, o before da próxima. Vale 0 se a página veio vazia.
threadobject
Resumo da conversa, no formato de Consultar conversa, mais handoff_timeout (reason e at) quando a conversa voltou ao assistente por tempo: N ninguém respondeu, I o cliente não voltou. Omitido se não for possível lê-la.
idinteger
Id numérico da mensagem. Cresce com o tempo. Use como cursor.
thread_iduuid
Conversa.
wamidstring
Id da mensagem na Meta. Omitido se ainda não houve envio.
directionstring
IO
I recebida do cliente, O enviada pela loja.
originstring
CABEH
C cliente, A API ou atendente, B assistente, E eco do aplicativo WhatsApp Business, H histórico.
msg_typestring
Tipo: text, image, audio, voice, video, document, sticker, interactive, template, order e outros que a Meta enviar.
bodystring
Texto da mensagem, ou a descrição quando não é texto.
media_idstring
Id da mídia na Meta. Omitido sem mídia.
media_mimestring
Tipo MIME da mídia. Omitido sem mídia.
media_captionstring
Legenda da mídia.
filenamestring
Nome do arquivo, para documentos.
media_urlstring
Link assinado e temporário (12 horas) para exibir a mídia sem cabeçalho Authorization. Aparece em mensagens com mídia que a conversa já listou.
transcriptionstring
Texto transcrito de um áudio, quando existe.
interactiveobject
Conteúdo de botões, listas e links enviados ou recebidos, como a Meta define.
order_payloadobject
Carrinho enviado pelo cliente pelo catálogo do WhatsApp.
statusstring
QSDRF
Entrega: Q na fila, S enviada, D entregue, R lida, F falhou.
errorstring
Motivo da falha quando status é F.
meta_timestampstring
Horário na Meta (RFC 3339).
created_atstring
Quando a plataforma gravou (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não é um seller, ou o seller ainda está em análise de cadastro.{"error":"vendor_pending_review"}
404Conversa de outro seller. Um id desconhecido também dá 404 em algumas rotas, mas 200 ou 502 em outras quando não há escopo de seller (veja a visão geral da seção).{"error":"thread not found"}
500Falha interna ao ler ou gravar.{"error":"..."}
Abra a conversa e marque como lida

Ler as mensagens não zera unread_count. Depois de exibir a conversa, chame Marcar como lida.

Exportar em CSV

Gera um arquivo CSV com as mensagens em ordem cronológica. Cobre no máximo as 200 mensagens mais recentes: conversas mais longas saem cortadas no começo.

GET/api/v1/vendor/whatsapp-confluence/threads/{id}/export.csvSeller

Baixa as mensagens da conversa em CSV

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Parâmetros de caminho

iduuidobrigatório
Id da conversa (id de Listar conversas).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/whatsapp-confluence/threads/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/export.csv" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Arquivo CSV
csv
id,created_at,origin,direction,msg_type,status,body
27,2026-10-10T14:30:00Z,C,I,text,S,"Quero 3 caixas, pode entregar amanhã?"
28,2026-10-10T14:35:00Z,A,O,text,S,"Olá, Maria! Seu pedido sai amanhã."

Campos da resposta

Content-Typeheader
text/csv; charset=utf-8. O arquivo sai como anexo wa-thread-{id}.csv.
colunascsv
id, created_at (UTC, RFC 3339), origin, direction, msg_type, status, body. Aspas no texto são dobradas e quebras de linha viram espaço.

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não é um seller, ou o seller ainda está em análise de cadastro.{"error":"vendor_pending_review"}
404Conversa de outro seller. Um id desconhecido também dá 404 em algumas rotas, mas 200 ou 502 em outras quando não há escopo de seller (veja a visão geral da seção).{"error":"thread not found"}
500Falha interna ao ler ou gravar.{"error":"..."}

Baixar mídia

Entrega a imagem, o áudio, o vídeo ou o documento que veio na mensagem. O arquivo vem do cache da plataforma ou é buscado na Meta na hora (até 16 MB). Tipos que não são seguros para abrir direto no navegador, como SVG, saem como download.

GET/api/v1/vendor/whatsapp-confluence/media/{messageID}Seller

Devolve os bytes da mídia de uma mensagem

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Parâmetros de caminho

messageIDintegerobrigatório
Id numérico da mensagem (id em Mensagens da conversa). Deve ser maior que 0.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/whatsapp-confluence/media/28" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Bytes da mídia
http
HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Disposition: inline; filename="foto.jpg"
Cache-Control: private, no-store
X-Content-Type-Options: nosniff

<bytes do arquivo>

Campos da resposta

corpobinary
O arquivo. Content-Type é o tipo real; tipos fora da lista segura (imagens jpeg, png, webp, gif; áudios ogg, mpeg, mp4, aac, amr, webm; vídeos mp4, 3gpp, webm; pdf) vêm como application/octet-stream com Content-Disposition: attachment.

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não é um seller, ou o seller ainda está em análise de cadastro.{"error":"vendor_pending_review"}
400messageID não é um número, ou é 0 ou negativo.{"error":"invalid id parameter"}
404Mensagem sem mídia, inexistente, ou de uma conversa de outro seller.{"error":"media not found"}
502A Meta não devolveu a mídia, ou veio vazia.{"error":"empty media"}
Para exibir no navegador, use `media_url`

Uma tag <img> ou <audio> não manda o cabeçalho Authorization. Por isso as mensagens listadas já trazem media_url, um link assinado de 12 horas que abre sem token. Use esta rota quando você mesmo baixa o arquivo, com o token.

Veja também

  • Responder
  • Estado da conversa
  • Visão geral da seção
Anterior
Visão geral
Próxima
Responder ao cliente
Nesta página
  • Listar conversas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar conversa
  • Exemplo de requisição
  • Resposta
  • Erros
  • Mensagens da conversa
  • Exemplo de requisição
  • Resposta
  • Erros
  • Exportar em CSV
  • Exemplo de requisição
  • Resposta
  • Erros
  • Baixar mídia
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também