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

Responder ao cliente

Envia texto, mídia ou template, marca a conversa como lida e atribui a um usuário.

Responder com texto

Envia uma mensagem de texto ao cliente pelo número da conversa. Ao responder, a conversa passa para atendimento humano (H) e o assistente se cala, salvo se a loja desligou "Pausar bot ao atender".

POST/api/v1/admin/whatsapp-confluence/threads/{id}/replyAdmin

Responde com texto

Parâmetros de caminho

iduuidobrigatório
Id da conversa.

Corpo da requisição

bodystringobrigatório
Texto da mensagem. Obrigatório (ou use text).
textstring
Apelido aceito de body, usado se body vier vazio.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp-confluence/threads/e661b36c-fe1b-450f-b75b-49d10c1ead48/reply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body": "Oi, Maria! Já vou te ajudar."}'

Resposta

200Mensagem enviada
json
{
  "id": 42,
  "thread_id": "e661b36c-fe1b-450f-b75b-49d10c1ead48",
  "wamid": "wamid.HBgLNTUxMTk4NzY1NDMyMRUCABEYEjQ1QTE",
  "direction": "O",
  "origin": "A",
  "msg_type": "text",
  "body": "Oi, Maria! Já vou te ajudar.",
  "status": "S",
  "meta_timestamp": "2026-10-10T18:43:02Z",
  "created_at": "2026-10-10T18:43:02Z"
}

Campos da resposta

idinteger
Id numérico da mensagem. Cresce com o tempo; usado para paginar e em Baixar mídia.
thread_iduuid
Conversa a que pertence.
wamidstring
Id da mensagem na Meta. Ausente em mensagem que falhou antes de ser aceita.
directionstring
IO
Sentido.
originstring
CABEH
Quem gerou.
msg_typestring
Tipo: text, interactive, template, image, audio, video, document e outros que a Meta envia.
bodystring
Texto da mensagem (ou resumo, para tipos sem texto).
media_idstring
Id da mídia na Meta, se houver.
media_mimestring
Tipo MIME da mídia.
media_captionstring
Legenda da mídia.
filenamestring
Nome do arquivo (documentos).
media_urlstring
URL assinada do mesmo domínio para tocar ou exibir a mídia sem cabeçalho de autorização. Só em listagens de mensagens.
transcriptionstring
Transcrição de um áudio, quando existir.
interactiveobject
Conteúdo de mensagens interativas (botões, listas, link com botão).
order_payloadobject
Carga de um pedido feito pelo catálogo do WhatsApp.
statusstring
QSDRF
Situação da entrega.
errorstring
Motivo da falha, quando status é F.
meta_timestampstring
Horário informado pela Meta.
created_atstring
Quando a plataforma registrou.

Erros

StatusQuandoCorpo de exemplo
400Corpo ausente, vazio ou JSON inválido.{"error":"body required"}
404A conversa não existe.{"error":"thread not found"}
502A Meta recusou o envio (por exemplo, fora da janela de 24 horas) ou não há número pronto para enviar. A mensagem fica gravada com status F.{"error":"...","message":{"id":43,"status":"F","error":"..."}}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem papel de administrador.{"error":"insufficient permissions"}
Janela de 24 horas

A plataforma não confere a janela antes de enviar; quem recusa é a Meta. Cheque csw_expires_at antes e, se tiver passado, use Enviar template.

Responder com mídia

Envia imagem, áudio, vídeo ou documento. Aceita multipart (envio do arquivo, até 16 MB, que a plataforma converte quando preciso) ou JSON com uma media_url pública que a Meta busca sozinha. Também passa a conversa para atendimento humano.

POST/api/v1/admin/whatsapp-confluence/threads/{id}/reply-mediaAdmin

Responde com mídia

Parâmetros de caminho

iduuidobrigatório
Id da conversa.

Corpo da requisição

filefile
Multipart: o arquivo. Obrigatório nesse formato.
media_typestring
imageaudiovideodocument
Multipart ou JSON: tipo da mídia. Se faltar, é deduzido do arquivo. JSON: padrão image.
captionstring
Legenda.
filenamestring
Nome do arquivo (importa para documentos).
voicestring
Multipart: 1 envia o áudio como mensagem de voz.
media_urlstring
JSON: endereço público da mídia. Obrigatório no formato JSON.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp-confluence/threads/e661b36c-fe1b-450f-b75b-49d10c1ead48/reply-media" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@foto.jpg" \
  -F "caption=Segue a foto do produto"

Resposta

200Mídia enviada
json
{
  "id": 42,
  "thread_id": "e661b36c-fe1b-450f-b75b-49d10c1ead48",
  "wamid": "wamid.HBgLNTUxMTk4NzY1NDMyMRUCABEYEjQ1QTE",
  "direction": "O",
  "origin": "A",
  "msg_type": "image",
  "body": "Segue a foto do produto",
  "status": "S",
  "meta_timestamp": "2026-10-10T18:43:02Z",
  "created_at": "2026-10-10T18:43:02Z",
  "media_mime": "image/jpeg",
  "media_caption": "Segue a foto do produto"
}

Campos da resposta

idinteger
Id numérico da mensagem. Cresce com o tempo; usado para paginar e em Baixar mídia.
thread_iduuid
Conversa a que pertence.
wamidstring
Id da mensagem na Meta. Ausente em mensagem que falhou antes de ser aceita.
directionstring
IO
Sentido.
originstring
CABEH
Quem gerou.
msg_typestring
Tipo: text, interactive, template, image, audio, video, document e outros que a Meta envia.
bodystring
Texto da mensagem (ou resumo, para tipos sem texto).
media_idstring
Id da mídia na Meta, se houver.
media_mimestring
Tipo MIME da mídia.
media_captionstring
Legenda da mídia.
filenamestring
Nome do arquivo (documentos).
media_urlstring
URL assinada do mesmo domínio para tocar ou exibir a mídia sem cabeçalho de autorização. Só em listagens de mensagens.
transcriptionstring
Transcrição de um áudio, quando existir.
interactiveobject
Conteúdo de mensagens interativas (botões, listas, link com botão).
order_payloadobject
Carga de um pedido feito pelo catálogo do WhatsApp.
statusstring
QSDRF
Situação da entrega.
errorstring
Motivo da falha, quando status é F.
meta_timestampstring
Horário informado pela Meta.
created_atstring
Quando a plataforma registrou.

Erros

StatusQuandoCorpo de exemplo
400Multipart inválido, sem file ou arquivo vazio.{"error":"file required"}
400JSON sem media_url.{"error":"media_url required"}
404A conversa não existe.{"error":"thread not found"}
502Conversão, upload ou envio recusados.{"error":"...","message":{"status":"F"}}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem papel de administrador.{"error":"insufficient permissions"}
Dois formatos

O exemplo de corpo mostra o formato JSON; as abas de código mostram o multipart. Escolha um: o tipo do Content-Type decide.

Enviar um template

Envia um template aprovado. É o único jeito de falar com o cliente depois que a janela de 24 horas fechou. Veja os templates disponíveis em Produtos e templates.

POST/api/v1/admin/whatsapp-confluence/threads/{id}/send-templateAdmin

Envia um template

Parâmetros de caminho

iduuidobrigatório
Id da conversa.

Corpo da requisição

namestringobrigatório
Nome do template aprovado. Obrigatório.
languagestring
Código de idioma do template (por exemplo pt_BR). Se faltar, vale o idioma padrão da loja.
componentsarray
Parâmetros do template no formato da Meta (corpo, botões). Opcional para templates sem variáveis.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp-confluence/threads/e661b36c-fe1b-450f-b75b-49d10c1ead48/send-template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "pedido_confirmado", "language": "pt_BR", "components": [{"type": "body", "parameters": [{"type": "text", "text": "Maria"}]}]}'

Resposta

200Template enviado
json
{
  "id": 42,
  "thread_id": "e661b36c-fe1b-450f-b75b-49d10c1ead48",
  "wamid": "wamid.HBgLNTUxMTk4NzY1NDMyMRUCABEYEjQ1QTE",
  "direction": "O",
  "origin": "A",
  "msg_type": "template",
  "body": "pedido_confirmado",
  "status": "S",
  "meta_timestamp": "2026-10-10T18:43:02Z",
  "created_at": "2026-10-10T18:43:02Z"
}

Campos da resposta

idinteger
Id numérico da mensagem. Cresce com o tempo; usado para paginar e em Baixar mídia.
thread_iduuid
Conversa a que pertence.
wamidstring
Id da mensagem na Meta. Ausente em mensagem que falhou antes de ser aceita.
directionstring
IO
Sentido.
originstring
CABEH
Quem gerou.
msg_typestring
Tipo: text, interactive, template, image, audio, video, document e outros que a Meta envia.
bodystring
Texto da mensagem (ou resumo, para tipos sem texto).
media_idstring
Id da mídia na Meta, se houver.
media_mimestring
Tipo MIME da mídia.
media_captionstring
Legenda da mídia.
filenamestring
Nome do arquivo (documentos).
media_urlstring
URL assinada do mesmo domínio para tocar ou exibir a mídia sem cabeçalho de autorização. Só em listagens de mensagens.
transcriptionstring
Transcrição de um áudio, quando existir.
interactiveobject
Conteúdo de mensagens interativas (botões, listas, link com botão).
order_payloadobject
Carga de um pedido feito pelo catálogo do WhatsApp.
statusstring
QSDRF
Situação da entrega.
errorstring
Motivo da falha, quando status é F.
meta_timestampstring
Horário informado pela Meta.
created_atstring
Quando a plataforma registrou.

Erros

StatusQuandoCorpo de exemplo
400name ausente ou JSON inválido.{"error":"name required"}
404A conversa não existe.{"error":"thread not found"}
502A Meta recusou o envio (por exemplo, fora da janela de 24 horas) ou não há número pronto para enviar. A mensagem fica gravada com status F.{"error":"...","message":{"id":43,"status":"F","error":"..."}}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem papel de administrador.{"error":"insufficient permissions"}
Variações de nome

Se a Meta não achar o template pelo nome, a plataforma tenta uma vez com o nome-base (sem sufixo de idioma) antes de falhar.

Marcar como lida

Zera o contador unread_count da conversa. Chame quando um atendente abrir a conversa.

POST/api/v1/admin/whatsapp-confluence/threads/{id}/readAdmin

Marca a conversa como lida

Parâmetros de caminho

iduuidobrigatório
Id da conversa.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp-confluence/threads/e661b36c-fe1b-450f-b75b-49d10c1ead48/read" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Conversa lida
json
{
  "success": true
}

Campos da resposta

successboolean
Sempre true.

Erros

StatusQuandoCorpo de exemplo
500Falha ao gravar (por exemplo, id que não é UUID).{"error":"..."}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem papel de administrador.{"error":"insufficient permissions"}
Não avisa o cliente

Isto só zera o contador interno; não envia confirmação de leitura ao cliente.

Atribuir a um usuário

Define quem da equipe cuida da conversa, ou remove a atribuição. Alimenta o filtro mine da lista.

POST/api/v1/admin/whatsapp-confluence/threads/{id}/assignAdmin

Atribui a conversa

Parâmetros de caminho

iduuidobrigatório
Id da conversa.

Corpo da requisição

user_iduuid
Usuário que assume. Corpo vazio ou user_id vazio remove a atribuição.
assignee_iduuid
Apelido aceito de user_id. null remove a atribuição.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp-confluence/threads/e661b36c-fe1b-450f-b75b-49d10c1ead48/assign" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "5b0c9f3e-2d1a-4c8e-9f7a-6e5d4c3b2a10"}'

Resposta

200Conversa atribuída
json
{
  "success": true
}

Campos da resposta

successboolean
Sempre true.

Erros

StatusQuandoCorpo de exemplo
400Corpo com tipo errado (por exemplo assignee_id numérico).{"error":"invalid request body: json: cannot unmarshal number into Go struct field ..."}
500Falha ao gravar (por exemplo, user_id que não é UUID).{"error":"..."}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem papel de administrador.{"error":"insufficient permissions"}
O usuário não é verificado

A plataforma não confere se user_id pertence a um usuário da loja; só aceita um UUID bem formado.

Veja também

  • Conversas e mensagens
  • Assumir e devolver
Anterior
Assumir e devolver
Próxima
Histórico e ligações
Nesta página
  • Responder com texto
  • Exemplo de requisição
  • Resposta
  • Erros
  • Responder com mídia
  • Exemplo de requisição
  • Resposta
  • Erros
  • Enviar um template
  • Exemplo de requisição
  • Resposta
  • Erros
  • Marcar como lida
  • Exemplo de requisição
  • Resposta
  • Erros
  • Atribuir a um usuário
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também