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

Responder ao cliente

Envia texto, mídia ou um template aprovado pela Meta em uma conversa e lista os templates disponíveis.

O WhatsApp só permite texto livre dentro da janela de atendimento de 24 horas, que abre a cada mensagem do cliente (csw_expires_at na conversa). Fora dela, só é possível enviar um template: uma mensagem pré-aprovada pela Meta. Estas rotas cobrem os três jeitos de responder. Enviar uma mensagem como atendente também passa a conversa para o atendimento humano (o assistente para de responder), a menos que a loja tenha desligado service_auto_pause_bot.

Enviar texto

POST/api/v1/vendor/whatsapp-confluence/threads/{id}/replySeller

Envia uma mensagem de texto

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

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

Corpo da requisição

bodystringobrigatório
Texto da mensagem. Obrigatório (ou text).
textstring
Apelido de body, usado quando body vem vazio.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/whatsapp-confluence/threads/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/reply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "Olá, Maria! Seu pedido sai amanhã e chega em até 3 dias úteis."
}'

Resposta

200Mensagem enviada
json
{
  "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"
}

Campos da resposta

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"}
400Corpo sem body/text, ou que não é JSON.{"error":"body required"}
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"}
502A Meta recusou o envio (por exemplo, texto livre fora da janela de 24 horas). A mensagem fica gravada com status: F.{"error":"<texto devolvido pela Meta>","message":{"id":31,"status":"F"}}
O texto é reescrito antes do envio

Travessões usados como pontuação viram ponto, e linhas que começam com - viram • . Hífens dentro de palavras (pré-pedido) ficam.

Primeira mensagem a um telefone novo

Se o termo de consentimento estiver ligado e este for o primeiro envio da loja àquele telefone, o termo é anexado ao seu texto.

Enviar mídia

Aceita dois formatos de corpo. Com multipart/form-data você envia o arquivo (até 16 MB) e a plataforma o sobe para a Meta. Com JSON você passa o endereço público de um arquivo e a Meta o busca. Áudios, imagens e vídeos são convertidos para formatos que o WhatsApp aceita antes do envio.

POST/api/v1/vendor/whatsapp-confluence/threads/{id}/reply-mediaSeller

Envia imagem, áudio, vídeo ou documento

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.
Content-Typestringobrigatório
multipart/form-data (arquivo) ou application/json (link público).

Parâmetros de caminho

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

Corpo da requisição

filefileobrigatório
Multipart: o arquivo, até 16 MB. Obrigatório neste formato.
media_typestring
imageaudiovoicevideodocument
Tipo da mídia. Em multipart, omitido é deduzido do arquivo. Em JSON, omitido vale image.
voicestring
Multipart: 1 envia o áudio como mensagem de voz.
captionstring
Legenda.
filenamestring
Nome exibido do arquivo. Em multipart, omitido usa o nome do arquivo enviado.
media_urlstring
JSON: endereço público do arquivo. Obrigatório neste formato.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/whatsapp-confluence/threads/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/reply-media" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@./catalogo.pdf" \
  -F "caption=Segue o catálogo atualizado"

Resposta

200Mídia enviada
json
{
  "id": 28,
  "thread_id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "wamid": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjA",
  "direction": "O",
  "origin": "A",
  "msg_type": "document",
  "body": "Segue o catálogo atualizado",
  "status": "S",
  "meta_timestamp": "2026-10-10T14:35:00Z",
  "created_at": "2026-10-10T14:35:00Z",
  "media_id": "1234567890",
  "media_mime": "application/pdf",
  "filename": "catalogo.pdf"
}

Campos da resposta

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"}
400Multipart inválido, sem file, arquivo vazio, ou JSON sem media_url.{"error":"file required"}
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"}
502Tipo de mídia não suportado, falha ao converter, ou a Meta recusou o envio.{"error":"..."}
Fora da janela de 24 horas

A mídia segue a mesma regra do texto: fora da janela a Meta recusa e você recebe 502. Mande antes um template com Enviar template.

Enviar template

Use quando a janela de 24 horas fechou, por exemplo para reabrir a conversa com um aviso de pedido. name e language vêm de Listar templates. Se o nome com sufixo não existir na Meta, a plataforma tenta o nome base.

POST/api/v1/vendor/whatsapp-confluence/threads/{id}/send-templateSeller

Envia um template aprovado pela Meta

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

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

Corpo da requisição

namestringobrigatório
Nome do template aprovado.
languagestring
Código de idioma do template, por exemplo pt_BR. Omitido usa o idioma padrão da loja.
componentsarray
Parâmetros do template, no formato da Meta: um item body com a lista de parameters na ordem das variáveis 1, 2... Omitido envia o template sem variáveis.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/whatsapp-confluence/threads/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/send-template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "pedido_enviado",
  "language": "pt_BR",
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "Maria"
        },
        {
          "type": "text",
          "text": "PEDIDO-20261010-0004"
        }
      ]
    }
  ]
}'

Resposta

200Template enviado
json
{
  "id": 28,
  "thread_id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "wamid": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjA",
  "direction": "O",
  "origin": "A",
  "msg_type": "template",
  "body": "pedido_enviado",
  "status": "S",
  "meta_timestamp": "2026-10-10T14:35:00Z",
  "created_at": "2026-10-10T14:35:00Z"
}

Campos da resposta

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"}
400Sem name, ou corpo que não é JSON.{"error":"name required"}
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"}
502Template inexistente, não aprovado, ou parâmetros que não batem. O texto vem da Meta.{"error":"<texto devolvido pela Meta>","message":{"id":31,"status":"F"}}
O custo conta

Templates fora da janela são cobrados pela Meta por categoria (MARKETING, UTILITY...). Acompanhe em Uso e custos.

Listar templates

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

Lista os templates da loja

Cabeçalhos

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

Parâmetros de consulta

syncstring
1 consulta a Meta antes de responder e atualiza a lista local. Se a consulta falhar, a lista local volta mesmo assim, com sync_error.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/whatsapp-confluence/templates?sync=1" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Templates
json
{
  "templates": [
    {
      "id": 1,
      "name": "pedido_enviado",
      "language": "pt_BR",
      "category": "UTILITY",
      "status": "A",
      "components": [
        {
          "type": "BODY",
          "text": "Olá {{1}}, seu pedido {{2}} saiu para entrega."
        }
      ],
      "quality_score": "GREEN",
      "synced_at": "2026-10-01T10:00:00Z"
    }
  ]
}

Campos da resposta

templatesarray

Templates conhecidos.

idinteger
Id interno.
namestring
Nome, o valor de name ao enviar.
languagestring
Idioma, por exemplo pt_BR.
categorystring
Categoria da Meta: MARKETING, UTILITY ou AUTHENTICATION.
statusstring
PARX
P em análise, A aprovado, R rejeitado, X desativado. Só envie os aprovados.
rejection_reasonstring
Motivo da rejeição, quando há.
componentsarray
Estrutura do template (cabeçalho, corpo, botões), como a Meta define.
quality_scorestring
Qualidade na Meta: GREEN, YELLOW, RED.
synced_atstring
Última sincronização com a Meta (RFC 3339).
sync_errorstring
Só com sync=1 quando a sincronização falhou.

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":"..."}
Lista da loja inteira

Os templates pertencem à conta da Meta da loja e não são filtrados por seller.

Veja também

  • Conversas e mensagens
  • Estado da conversa
  • Termo de consentimento
Anterior
Conversas e mensagens
Próxima
Estado da conversa
Nesta página
  • Enviar texto
  • Exemplo de requisição
  • Resposta
  • Erros
  • Enviar mídia
  • Exemplo de requisição
  • Resposta
  • Erros
  • Enviar template
  • Exemplo de requisição
  • Resposta
  • Erros
  • Listar templates
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também