Histórico e ligações

Esta seção é a leitura do que aconteceu no número de WhatsApp da loja: a lista de conversas, as mensagens de cada uma, o arquivo de mídia de uma mensagem, a exportação em CSV e o registro das ligações de voz atendidas pelo atendente virtual. Nada aqui envia mensagem nem altera estado; responder, assumir ou cobrar são ações de outras seções.

Como funciona

1. Liste as conversas
   Listar conversas com filtros como filter=unread e busca q. Cada item traz o id que as outras rotas pedem.
2. Abra a conversa
   Mensagens e CSV devolve as mensagens paginadas e um resumo da conversa.
3. Baixe a mídia
   Mensagens com foto, áudio ou documento têm media_url (link de 12 horas) ou podem ser baixadas por Mídia da mensagem.
4. Consulte as ligações
   Ligações lista as chamadas de voz atendidas, com transcrição, nota e gravação.

Conceitos-chave

Conversa, mensagem e janela de 24 horas

Uma conversa (thread) é única por par número da loja e telefone do cliente. Depois que o cliente escreve, a loja tem 24 horas (csw_expires_at) para responder com texto livre; passado esse prazo só vale template aprovado pela Meta. Um anúncio que leva ao WhatsApp abre ainda um ponto de entrada gratuito de 72 horas (fep_expires_at).

Códigos de uma letra

Duas famílias de rotas de WhatsApp

A plataforma tem duas caixas de entrada de WhatsApp na API de administração: esta, sob /api/v1/admin/whatsapp-confluence/..., e a da seção caixa de entrada, sob /api/v1/admin/whatsapp/.... São conjuntos de rotas separados, com formatos de resposta diferentes. Use ids de conversa e de mensagem sempre na família em que os obteve.

Datas

Datas de conversa e mensagem em RFC 3339 (UTC). started_at das ligações também vem em UTC, no formato 2026-10-10T14:32:10Z.

Endpoints

Erros comuns

• Esperar um total na lista de conversas. Não existe: continue pedindo page até vir threads vazio.
• Paginar mensagens com page. Mensagens usam cursor: passe o next_before da resposta anterior como before.
• Achar que ler marca como lido. Abrir a conversa não zera unread_count.
• Tratar 200 com lista vazia como sucesso garantido. Um UUID bem formado que não existe devolve 200 com messages vazio (e CSV só com o cabeçalho); só GET /threads/{id} responde 404.
• Passar um id que não é UUID para o CSV. A exportação responde 500 com uma mensagem de erro técnica, sem tratamento; valide o UUID antes.
• Abrir o CSV direto no Excel sem cuidado. O corpo da mensagem é texto do cliente e não é protegido contra fórmulas.
• Usar Authorization em <img> e <audio>. Tags não enviam o cabeçalho; use o media_url assinado.

Próximos passos