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 ou mídia em uma conversa e baixa a mídia que o cliente mandou.

Quando um atendente assume uma conversa, ele responde por estas rotas. A resposta sai pelo número da conversa (o do seller, se houver). Só funciona dentro da janela de 24 horas aberta pela última mensagem do cliente; depois disso a Meta recusa texto livre e a rota devolve 502 (use um template, em Mensagens enviadas).

Responder com texto

Envia o texto, registra a mensagem na conversa como enviada manualmente e desliga o assistente da conversa.

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

Envia uma mensagem de texto ao cliente da conversa

Parâmetros de caminho

idstringobrigatório
UUID da conversa.

Corpo da requisição

bodystringobrigatório
Texto da mensagem. Não pode ser vazio nem só espaços.

Exemplo de requisição (Responder com texto)

Resposta (Responder com texto)

200Enviada

Campos da resposta

successboolean
true.
messageobject
A mensagem registrada. Veja Mensagens enviadas para os campos.

Erros (Responder com texto)

StatusQuandoCorpo
400Corpo inválido ou body vazio.{"error":"body required"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_orders"} ou {"error":"admin access required"}
404A conversa não existe.{"error":"thread not found"}
502A Meta recusou o envio (por exemplo, fora da janela de 24 horas).{"error":"Cloud API send failed: ..."}

Responder com mídia

Envia um arquivo que a Meta busca em uma URL pública. Primeiro envie o arquivo à loja (mídia da plataforma) e use a URL pública resultante. Diferente da resposta de texto, esta rota não desliga o assistente.

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

Envia imagem, vídeo, áudio ou documento ao cliente

Parâmetros de caminho

idstringobrigatório
UUID da conversa.

Corpo da requisição

media_urlstringobrigatório
URL pública (HTTP ou HTTPS) que a Meta consegue abrir.
media_typestringobrigatório
imagevideoaudiodocument
Tipo da mídia.
captionstring
Legenda. Vale para imagem, vídeo e documento; é ignorada em áudio.
idempotency_keystring
Reservado. Hoje é aceito mas não evita envio duplicado.

Exemplo de requisição (Responder com mídia)

Resposta (Responder com mídia)

200Enviada

Campos da resposta

successboolean
true.
messageobject
A mensagem registrada na conversa.

Erros (Responder com mídia)

StatusQuandoCorpo
400media_url ausente, media_type não suportado ou conversa sem telefone.{"error":"whatsapp media reply: media_url required","message":null}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_orders"} ou {"error":"admin access required"}
404A conversa não existe.{"error":"thread not found"}
502A Meta recusou o envio (URL inacessível, fora da janela...). A resposta traz o erro e a mensagem registrada com falha.{"error":"...","message":{}}
A URL precisa ser pública

A Meta baixa o arquivo da URL. Um ambiente atrás de NAT, uma URL com login ou localhost fazem o envio falhar com 502.

Baixar a mídia de uma mensagem

Entrega o arquivo que o cliente enviou, com o Content-Type correto. A primeira chamada busca na Meta e guarda uma cópia; as seguintes saem do cache da plataforma (Cache-Control: private, max-age=3600). Mensagens cuja mídia é um link externo respondem com redirecionamento 302.

GET/api/v1/admin/whatsapp/media/{message_id}Admin

Devolve os bytes da mídia (imagem, áudio, documento) de uma mensagem

Parâmetros de caminho

message_idintegerobrigatório
Id numérico da mensagem (campo id das mensagens da conversa).

Exemplo de requisição (Baixar a mídia de uma mensagem)

Resposta (Baixar a mídia de uma mensagem)

200Arquivo

Erros (Baixar a mídia de uma mensagem)

StatusQuandoCorpo
400message_id não numérico, mensagem sem mídia, esquema de URL não suportado ou id de mídia ausente.{"error":"message has no media"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_orders"} ou {"error":"admin access required"}
404Mensagem inexistente.{"error":"message not found"}
502Falha ao buscar a mídia na Meta (por exemplo, a mídia expirou).{"error":"media fetch failed: ..."}
503Token da API do WhatsApp não configurado.{"error":"whatsapp api token not configured"}
A Meta guarda mídia por pouco tempo

Baixe os anexos logo que chegarem. Depois de um tempo a Meta apaga o arquivo e a primeira chamada passa a dar 502; cópias já em cache continuam disponíveis.

Veja também

  • Conversas
  • Mensagens enviadas
  • Respostas prontas
Anterior
Conversas
Próxima
Carrinho montado pelo atendente
Nesta página
  • Responder com texto
  • Exemplo de requisição (Responder com texto)
  • Resposta (Responder com texto)
  • Erros (Responder com texto)
  • Responder com mídia
  • Exemplo de requisição (Responder com mídia)
  • Resposta (Responder com mídia)
  • Erros (Responder com mídia)
  • Baixar a mídia de uma mensagem
  • Exemplo de requisição (Baixar a mídia de uma mensagem)
  • Resposta (Baixar a mídia de uma mensagem)
  • Erros (Baixar a mídia de uma mensagem)
  • Veja também
bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/threads/014ff6d8-8ff0-40da-82ce-e5a349b57be6/reply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Oi! Sim, temos a camisa M. Posso enviar o link?"
  }'
bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/threads/014ff6d8-8ff0-40da-82ce-e5a349b57be6/reply-media" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "media_url": "https://minhaloja.io.venddor.com.br/uploads/catalogo.pdf",
    "media_type": "document",
    "caption": "Nosso catálogo"
  }'
bash
curl "$BASE_URL/api/v1/admin/whatsapp/media/2027" \
  -H "Authorization: Bearer $TOKEN" \
  -o anexo.bin
json
{
  "success": true,
  "message": {
    "id": 2090,
    "phone_number": "+5511999990428",
    "message_type": "text",
    "params": {
      "body": "Oi! Sim, temos a camisa M. Posso enviar o link?"
    },
    "status": "sent",
    "whatsapp_message_id": "wamid.HBgNNTUxMTk5OTk5MDQyOBUCABEYEg"
  }
}
json
{
  "success": true,
  "message": {
    "id": 2091,
    "thread_id": "014ff6d8-8ff0-40da-82ce-e5a349b57be6",
    "direction": "outbound",
    "message_type": "document",
    "media_url": "https://minhaloja.io.venddor.com.br/uploads/catalogo.pdf",
    "status": "S",
    "sent_manually": true
  }
}
http
HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Disposition: inline; filename="foto.jpg"
Cache-Control: private, max-age=3600

<bytes da imagem>