Visão geral

A caixa de entrada (inbox) é onde a equipe da loja atende os clientes pelo WhatsApp. Cada cliente que escreve vira uma conversa; o assistente de vendas responde sozinho até uma pessoa assumir. Pela API o seller lê as conversas, responde com texto, mídia ou template, manda produtos e cobra por PIX. Há ainda a caixa do chat da mini-loja, com o mesmo desenho.

Como funciona

O fluxo típico de um atendente:

1. Liste as conversas
   Listar conversas com filter=unread ou filter=human.
2. Leia o histórico
   Pagine as mensagens e marque a conversa como lida.
3. Assuma e responda
   Se for responder, assuma (ou deixe o primeiro envio assumir) e use Responder. Passou das 24 horas? Envie um template.
4. Venda na conversa
   Envie produtos ou o link do carrinho, e cobre por PIX.
5. Devolva ao assistente
   Chame Encerrar atendimento para o assistente voltar.

Modos de atendimento (bot_mode)

Origem da mensagem (origin) e entrega (status)

Conceitos-chave

Janela de atendimento de 24 horas

Cada mensagem do cliente abre ou renova uma janela de 24 horas (csw_expires_at). Dentro dela a loja envia texto, mídia e mensagens interativas. Fora dela, a Meta só aceita templates. Tentar texto livre fora da janela devolve 502 e deixa a mensagem gravada com status: F.

Ponto de entrada gratuito

Quando o cliente chega por um anúncio que leva ao WhatsApp, abre-se uma janela de 72 horas (fep_expires_at) em que as respostas não geram cobrança de conversa pela Meta.

Quem vê o quê

Numa loja em que vários sellers têm número próprio, cada seller vê só as conversas, mídias, sessões e o uso mensal das contas dele. Quando nenhum número tem seller dono, ou há um único seller dono, o seller vê tudo. Templates, catálogo, campanhas e analytics são da loja inteira.

Contas de demonstração

Em ambientes de teste, contas de demonstração gravam as mensagens como enviadas sem chamar a Meta. Em produção, cada envio é uma chamada real e pode ser cobrado.

Dinheiro e datas

Valores em centavos inteiros (15990 = R$ 159,90). Datas em RFC 3339 (UTC).

Endpoints

Erros comuns

• Responder fora da janela de 24 horas. Resulta em 502 da Meta. Confira csw_expires_at e use um template.
• Achar que um id de conversa desconhecido sempre dá 404. Sem escopo de seller, rotas como take-over, read, bot/pause e messages respondem 200 para um id que não existe, e os envios de produto e a cobrança respondem 502.
• Chamar /bot e confiar no 200. A rota devolve mode: A até para um id sem sessão. Valide a conversa antes.
• Passar um id que não é UUID em /charges. Dá 500 com o texto cru do banco, não 404.
• Esperar que ler marque como lida. Só Marcar como lida zera unread_count.
• Paginar mensagens por número de página. A paginação é por cursor: use next_before como before.
• Mandar um produto de outro seller. O envio recusa produtos que não são do catálogo do seller com 502.
• Esperar que a resposta no chat da mini-loja saia pela Meta. Ela só aparece no chat do cliente na próxima consulta da página dele.

Próximos passos