WhatsApp: caixa de entrada

A caixa de entrada é onde a equipe da loja atende clientes pelo WhatsApp. O assistente automático responde primeiro; quando o cliente pede um humano, ou quando um atendente decide assumir, a conversa passa para as pessoas. Esta seção cobre tudo que a tela de atendimento faz: listar e abrir conversas, responder com texto e mídia, montar o carrinho do cliente dentro da conversa, anotar, usar respostas prontas, ver quem está online e acompanhar métricas.

Como funciona

Quem responde

Cada conversa tem bot_enabled. Com true, o assistente responde sozinho. Quando o cliente pede um atendente, human_requested_at é preenchido, o assistente desliga e a conversa ganha urgency_state = human_requested com uma contagem regressiva. Se ninguém responder dentro do prazo, um processo automático devolve a conversa ao assistente.

Fluxo típico do atendente

1. Ver o que espera

   GET /threads?status=pending lista conversas com mensagens não lidas.

2. Abrir e ler

   GET /threads/{id} traz as últimas 50 mensagens. Para ler a mídia, GET /media/{message_id}.

3. Responder

   POST /threads/{id}/reply (texto) ou reply-media. O assistente fica desligado nesta conversa.

4. Vender

   GET /threads/{id}/quick-add, POST /threads/{id}/send-cart e, se for B2B, send-cart-pdf.

5. Encerrar

   POST /threads/bulk com close, ou toggle-bot com enabled: true para devolver ao assistente.

Conceitos-chave

Conversa e mensagem

Uma conversa é única por par número da loja + telefone do cliente. Os ids de conversa são UUID; os ids de mensagem são inteiros. O telefone vem com + e código do país.

Seller (lojista) e escopo

Lojas multi-seller têm conversas no número da loja e no número de cada seller. Se o usuário do token estiver vinculado a um seller, todas as listagens e ações são restritas a ele, mesmo que o pedido tente outro vendor_id. Um administrador sem vínculo vê tudo.

Cliente cadastrado

customer_user_id só existe quando o telefone da conversa bate com um cliente cadastrado. As rotas de carrinho exigem esse vínculo.

Dinheiro e datas

Preços vêm em centavos inteiros (30000 = R$ 300,00). Datas são RFC 3339 em UTC.

Status de mensagem

Nas mensagens da conversa o status é uma letra (P pendente, S enviada, V entregue, R lida, F falhou). No histórico de envios da plataforma ele vem por extenso.

Endpoints

Erros comuns

• Tentar responder com texto depois de 24 horas: a Meta recusa e a rota devolve 502. Envie um template.
• Esperar que status=pending filtre "humano pedido": ele filtra por mensagens não lidas.
• Esquecer que responder desliga o assistente: depois, devolva com toggle-bot.
• Usar send-cart em conversa sem cliente cadastrado: 422 thread_no_customer_user.
• Reenviar o mesmo item em send-cart achando que ele substitui: a quantidade é somada.
• Usar só manage_orders no token: toda a família exige também manage_settings.
• Abrir conversas por script só para ler: cada GET /threads/{id} marca mensagens como lidas no WhatsApp do cliente.

Próximos passos