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

Responder

Envia ao cliente uma resposta em texto ou com imagem, vídeo, áudio e documento, e baixa as mídias que ele mandou.

Quando o atendente responde pelo painel, estas rotas fazem o envio pelo número de WhatsApp do seller. Para texto basta um corpo JSON. Para mídia, primeiro envie o arquivo com upload, que devolve uma URL, e então mande essa URL em reply-media: a Meta baixa o arquivo por esse link. A quarta rota baixa uma mídia que o cliente mandou.

Toda resposta é gravada na conversa antes de você saber se a Meta aceitou. Por isso uma falha de envio devolve 502 com a mensagem gravada, e não simplesmente um erro sem corpo útil.

Responder com texto

POST/api/v1/vendor/whatsapp/inbox/threads/{id}/replySeller

Envia uma mensagem de texto ao cliente

Envia o texto pelo número do seller (ou pelo número padrão da loja, se o seller não tem o seu). Não desliga o assistente automático da conversa.

Parâmetros de caminho

iduuidobrigatório
Id da conversa.

Corpo da requisição

bodystringobrigatório
Texto da mensagem. Não pode ficar vazio nem só com espaços.
reply_tostring
Opcional. Id da mensagem a citar, no formato da Meta (wa_message_id, começa com wamid). A resposta aparece como citação no WhatsApp do cliente.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/inbox/threads/$THREAD_ID/reply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body": "Temos sim! Quer que eu separe o 42?"}'

Resposta

200Mensagem enviada
json
{
  "success": true,
  "message": {
    "id": 48213,
    "phone_number": "5511999990000",
    "message_type": "text",
    "params": { "body": "Temos sim! Quer que eu separe o 42?" },
    "status": "sent",
    "whatsapp_message_id": "wamid.HBgNNTUxMTk5OTk5MDAwMBUCABEYEjQ1",
    "sent_at": "2026-10-11T13:05:30Z",
    "created_at": "2026-10-11T13:05:30Z"
  }
}
502A Meta recusou o envio
json
{
  "error": "Cloud API send failed: whatsapp vendor inbox: send text: ...",
  "message": {
    "id": 48214,
    "phone_number": "5511999990000",
    "message_type": "text",
    "params": { "body": "Temos sim! Quer que eu separe o 42?" },
    "status": "sent",
    "created_at": "2026-10-11T13:06:10Z"
  }
}

Campos da resposta

successboolean
true quando a Meta aceitou a mensagem. Ausente no 502.
messageobject
A mensagem gravada na conversa.
message.idinteger
Id numérico da mensagem.
message.phone_numberstring
Telefone do cliente.
message.message_typestring
text nesta rota.
message.paramsobject
{"body": "..."} com o texto original que você enviou.
message.statusstring
Situação gravada. Sai sent mesmo no 502: confie no status HTTP, não nesse campo.
message.whatsapp_message_idstring
Id da Meta (wamid...). Ausente quando o envio falhou.
message.sent_atstring
RFC 3339.
message.created_atstring
RFC 3339.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid request body"}
400body vazio{"error":"body required"}
401 / 403Sem token, token que não é de seller, módulo desligado, sem privilégioveja Conversas
404Conversa de outro seller ou inexistente{"error":"thread not found"}
502A Meta recusou (fora da janela de 24 horas, número sem credencial válida, etc.){"error":"Cloud API send failed: ...","message":{...}}
500Falha ao gravar a mensagem{"error":"Failed to send reply: ..."}
O texto enviado pode diferir do texto gravado

Antes de enviar, a plataforma troca travessões (o traço longo e o traço médio) e o hífen cercado de espaços por um ponto final, transforma linhas iniciadas por - em • e colapsa espaços e pontos repetidos (... vira .). A conversa grava o texto original, mas o cliente recebe o texto limpo. Se a pontuação importa (por exemplo em um código), evite esses caracteres.

Responder com mídia

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

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

A mídia precisa estar numa URL pública que a Meta consiga baixar. O fluxo normal é enviar o arquivo com upload e usar a url devolvida.

Parâmetros de caminho

iduuidobrigatório
Id da conversa.

Corpo da requisição

media_urlstringobrigatório
URL http ou https do arquivo, alcançável pela internet.
media_typestringobrigatório
imagevideoaudiodocument
Tipo da mídia. Figurinha (sticker) não é aceita.
captionstring
Legenda. Vale para image, video e document; em audio é ignorada.
idempotency_keystring
Opcional. Aceito, mas hoje não tem efeito: a plataforma não bloqueia reenvios repetidos. Evite duplicidade no seu cliente, por exemplo não reenviando enquanto a primeira chamada está em andamento.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/inbox/threads/$THREAD_ID/reply-media" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "media_url": "https://minhaloja.io.venddor.com.br/uploads/tenis-preto.jpg",
    "media_type": "image",
    "caption": "Segue a foto do tênis preto",
    "idempotency_key": "foto-tenis-9b1f"
  }'

Resposta

200Mídia enviada
json
{
  "success": true,
  "message": {
    "id": 48215,
    "phone_number": "5511999990000",
    "message_type": "image",
    "status": "sent",
    "whatsapp_message_id": "wamid.HBgNNTUxMTk5OTk5MDAwMBUCABEYEjQ2",
    "created_at": "2026-10-11T13:07:02Z"
  }
}

Os campos de message são os mesmos da resposta de texto; aqui message_type repete o media_type enviado.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid request body"}
400media_url vazia{"error":"media_url required"}
400media_type fora dos quatro valores{"error":"invalid media_type (image|video|audio|document)"}
401 / 403Autenticação, módulo ou privilégioveja Conversas
404Conversa de outro seller ou inexistente{"error":"thread not found"}
502A Meta recusou o envio (por exemplo, não conseguiu baixar a URL){"error":"media send failed: ...","message":{...}}
500Falha antes de gravar{"error":"media send failed: ...","message":null}
Teste a URL antes

Abra a media_url numa janela anônima. Se pedir login ou apontar para localhost/rede interna, a Meta também não vai conseguir baixar e você receberá 502.

Enviar um arquivo

POST/api/v1/vendor/whatsapp/inbox/uploadSeller

Envia um arquivo e recebe a URL para usar em reply-media

Corpo multipart/form-data. É o mesmo enviador de mídia genérico da loja, aberto ao seller sem exigir o privilégio de mídia do administrador. O painel usa owner_type=whatsapp_thread e owner_id igual ao id da conversa.

Corpo da requisição

filefileobrigatório
O arquivo. Até 10 MB. Tipos aceitos: JPEG, PNG, GIF, WebP, AVIF, SVG, PDF e MP4. O tipo é detectado pelo conteúdo, não pelo nome nem pelo cabeçalho.
owner_typestringobrigatório
A que o arquivo pertence. Use whatsapp_thread. Valores product e vendor só são aceitos para produtos e cadastro do próprio seller.
owner_idstringobrigatório
Id do dono. Com whatsapp_thread, o id da conversa.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/inbox/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@tenis-preto.jpg" \
  -F "owner_type=whatsapp_thread" \
  -F "owner_id=$THREAD_ID"

Resposta

201Arquivo recebido
json
{
  "id": "5d0c1a44-8f0e-4d6b-9a4e-0b8f7c1e2a33",
  "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798",
  "owner_id": "9b1f3c52-6a0e-4d57-8a43-2f6c1d7e90ab",
  "owner_type": "whatsapp_thread",
  "filename": "tenis-preto.jpg",
  "content_type": "image/jpeg",
  "size": 84213,
  "url": "/uploads/dfe2555e/whatsapp_thread/tenis-preto.jpg",
  "position": 0,
  "created_at": "2026-10-11T13:06:40Z"
}

Campos da resposta

iduuid
Id do arquivo.
urlstring
URL do arquivo. Pode vir completa (endereço público ou CDN) ou só como caminho /uploads/.... Em media_url use sempre a URL completa: se vier só o caminho, junte com $BASE_URL.
filenamestring
Nome original.
content_typestring
Tipo detectado pelo conteúdo.
sizeinteger
Tamanho em bytes.
owner_typestring
Eco do que você enviou.
owner_idstring
Eco do que você enviou.
positioninteger
Ordem do arquivo no dono. Sem uso para conversas.
tenant_iduuid
Loja dona do arquivo.
created_atstring
RFC 3339.

Erros

StatusQuandoCorpo
400Corpo que não é multipart ou grande demais{"error":"failed to parse multipart form","detail":"..."}
400Falta file, owner_type ou owner_id{"error":"file is required"} / {"error":"owner_type is required"} / {"error":"owner_id is required"}
400Tipo não aceito (inclui áudio MP3/OGG){"error":"unsupported file type","detail":"Allowed types: JPEG, PNG, GIF, WebP, AVIF, SVG, PDF, MP4. Detected: audio/mpeg"}
403product ou vendor de outro seller{"error":"owner_not_allowed","code":"owner_not_allowed"}
500Falha ao gravar{"error":"failed to upload file","detail":"..."}
Esta rota não aceita áudio

A lista de tipos aceitos não tem formatos de áudio. Para mandar um áudio por reply-media, hospede o arquivo em outro lugar público e passe essa URL, ou confirme na sua loja o formato aceito antes de depender do upload.

Baixar a mídia de uma mensagem

GET/api/v1/vendor/whatsapp/inbox/media/{message_id}Seller

Baixa a imagem, o áudio ou o documento de uma mensagem

Devolve o arquivo da mensagem. Mídia recebida do cliente fica guardada na Meta (media_url começa com meta://); esta rota busca na Meta e guarda uma cópia para as próximas chamadas. Se a mensagem tem uma URL pública, a resposta é um redirecionamento 302 para ela.

Parâmetros de caminho

message_idintegerobrigatório
Id numérico da mensagem (messages[].id da conversa), não o id da Meta.

Exemplo de requisição

bash
curl -L "$BASE_URL/api/v1/vendor/whatsapp/inbox/media/48212" \
  -H "Authorization: Bearer $TOKEN" -o foto.jpg

Resposta

200Arquivo
http
HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Disposition: inline; filename="foto.jpg"
Cache-Control: private, max-age=3600

(bytes do arquivo)

O corpo é o arquivo em si, com o Content-Type da mídia. Em mídia com URL pública a resposta é 302 com Location apontando para ela.

Erros

StatusQuandoCorpo
400message_id não numérico ou menor que 1{"error":"invalid message_id"}
400A mensagem não tem mídia{"error":"message has no media"}
404Mensagem de outro seller ou inexistente{"error":"message not found"}
502A Meta não entregou o arquivo (o link dela expira em minutos){"error":"media fetch failed: ..."}
503A loja não tem token da Meta configurado{"error":"whatsapp api token not configured"}
Mídia sem token

Para exportar ou compartilhar, a conversa já traz media_share_url em cada mensagem com mídia: um link assinado que não exige Authorization. Use a rota autenticada só dentro de um painel.

Veja também

  • Conversas
  • Carrinho e cobrança
  • Número do seller
Anterior
Conversas
Próxima
Carrinho e cobrança
Nesta página
  • Responder com texto
  • Exemplo de requisição
  • Resposta
  • Erros
  • Responder com mídia
  • Exemplo de requisição
  • Resposta
  • Erros
  • Enviar um arquivo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Baixar a mídia de uma mensagem
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também