Caixa de entrada do WhatsApp
Como o seller atende, pela API, as conversas que os clientes abrem no número de WhatsApp da loja.
O módulo WhatsApp Commerce conecta a loja ao WhatsApp Business (a API oficial da Meta, chamada de Cloud API). Cada cliente que escreve para o número da loja abre uma conversa (em inglês, thread): um histórico de mensagens entre o telefone do cliente e o número do seller (lojista). Esta seção documenta as rotas que o painel do seller usa para atender essas conversas: listar, ler, responder, mandar produtos e cobrança, e deixar anotações internas.
A conversa nasce sozinha quando o cliente manda a primeira mensagem. Não existe rota para criar uma conversa por esta API.
Como funciona
O ciclo de uma conversa
- Listar as conversas
GET /inbox/threadsdevolve a fila, da mais recente para a mais antiga, com a contagem de mensagens não lidas. - Abrir uma conversa
GET /inbox/threads/{id}traz a conversa e as últimas 50 mensagens. O painel também carrega o contexto do cliente (pedidos, itens mais comprados). - Responder
Texto livre, ou foto, áudio, vídeo e documento (Responder). Para vender, mande um botão com o carrinho ou o link de pagamento (Carrinho e cobrança).
- Marcar como lida e anotar
mark-readzera o contador. Notas internas ficam só para a equipe: o cliente nunca as recebe.
Conceitos-chave
Conversa (thread)
Uma conversa é única para o par seller + telefone do cliente. O campo id é um UUID em string. Os campos mais úteis:
| Campo | Significado |
|---|---|
customer_phone | Telefone do cliente, só dígitos com DDI (por exemplo 5511999990000). |
bot_enabled | true quando o assistente automático também responde nesta conversa. |
unread_count | Mensagens do cliente que ninguém marcou como lidas. |
last_inbound_at / last_outbound_at | Última mensagem recebida e última enviada (RFC 3339, UTC). Podem ser null. |
human_requested_at | Quando o cliente pediu para falar com uma pessoa, se pediu. |
urgency_state | human_requested, waiting_client, manual_mode ou normal (calculado na hora). |
tags, assigned_to_user_id | Etiquetas e responsável. Aparecem na resposta, mas o seller não filtra por eles. |
A janela de 24 horas
A Meta só aceita mensagem de texto livre ou mídia dentro de 24 horas depois da última mensagem do cliente. Fora da janela, só mensagens de modelo aprovado (template) passam. Esta API não bloqueia antes: ela tenta enviar, a Meta recusa e você recebe 502 (veja Responder). Os modelos ficam em Canal e catálogo.
Qual número envia
A resposta sai pelo número do próprio seller, se ele conectou um (Número do seller). Sem número próprio, sai pelo número padrão da loja.
Dinheiro e datas
Valores monetários desta seção (total_cents, unit_price_cents) são inteiros em centavos (18900 = R$ 189,00). Datas são RFC 3339 em UTC.
Endpoints
Auth: Seller é um usuário do painel do seller (Authorization: Bearer $TOKEN).
| Método | Rota | O que faz | Auth | Página |
|---|---|---|---|---|
| GET | /api/v1/vendor/whatsapp/inbox/threads | Lista as conversas | Seller | Conversas |
| GET | /api/v1/vendor/whatsapp/inbox/threads/{id} | Abre uma conversa com as mensagens | Seller | Conversas |
| GET | /api/v1/vendor/whatsapp/inbox/threads/{id}/customer-context | Pedidos e itens mais comprados do cliente | Seller | Conversas |
| POST | /api/v1/vendor/whatsapp/inbox/threads/{id}/mark-read | Zera as não lidas | Seller | Conversas |
| POST | /api/v1/vendor/whatsapp/inbox/threads/{id}/reply | Responde com texto | Seller | Responder |
| POST | /api/v1/vendor/whatsapp/inbox/threads/{id}/reply-media | Responde com imagem, vídeo, áudio ou documento | Seller | Responder |
| POST | /api/v1/vendor/whatsapp/inbox/upload | Envia um arquivo para usar na resposta | Seller | Responder |
| GET | /api/v1/vendor/whatsapp/inbox/media/{message_id} | Baixa a mídia de uma mensagem | Seller | Responder |
| POST | /api/v1/vendor/whatsapp/inbox/threads/{id}/send-cart | Envia um botão "Abrir carrinho" | Seller | Carrinho e cobrança |
| POST | /api/v1/vendor/whatsapp/inbox/threads/{id}/send-payment | Envia um botão "Pagar pedido" | Seller | Carrinho e cobrança |
| GET | /api/v1/vendor/whatsapp/inbox/threads/{id}/notes | Lista as notas internas | Seller | Notas internas |
| POST | /api/v1/vendor/whatsapp/inbox/threads/{id}/notes | Cria uma nota interna | Seller | Notas internas |
| DELETE | /api/v1/vendor/whatsapp/inbox/threads/{id}/notes/{note_id} | Apaga uma nota interna | Seller | Notas internas |
Erros comuns
- Usar token de administrador. As rotas
/api/v1/vendor/...só aceitam usuário seller. O erro é403 insufficient permissions. - Esperar que
statuscombine filtros. EmGET /inbox/threads,statusaceita um só valor por vez (open,pendingouresolved). - Tratar
502em resposta como "não gravou". A mensagem fica registrada na conversa mesmo quando a Meta recusa o envio; o corpo do502traz a mensagem gravada. - Mandar
media_urlque a Meta não alcança. A Meta baixa o arquivo pelo link. URL de rede interna ou que exige login falha. - Escrever travessão e reticências na resposta. O envio troca travessões por ponto e colapsa pontos repetidos (veja Responder).
- Passar o id de uma conversa de outro seller. A resposta é
404 thread not found, igual a um id que não existe.