Skip to main content
Cada item abaixo começa pelo sintoma que você vê. Para erros de conexão do WhatsApp vindos da Meta (como #2655093 ou #3441038), veja a página da central de ajuda Problemas ao conectar o WhatsApp.

​
GET /api/v1/chats/{business_id} retorna conversas de teste

O parâmetro kind tem como padrão trainer, que retorna as conversas de teste do Trainer de IA. Passe kind=real para as conversas reais do WhatsApp, ou kind=all para as duas. Qualquer outro valor retorna 400.

​
A consulta com since retorna mensagens que você já viu

since é um timestamp ISO-8601, exclusivo (estritamente mais novo que), e é tratado como UTC quando não tem fuso. Ele filtra quais chats são retornados — não as mensagens embutidas em cada chat. Cada chat retornado continua trazendo as suas messages_per_chat mensagens mais recentes (padrão 1, até 200), independentemente de since. Para sincronizar mensagens com segurança:
  • Remova duplicatas pelo id da mensagem, ou
  • Busque a conversa de cada chat alterado em GET /api/v1/chats/{chat_id}/messages.

​
403 plan_limit_rest_api

O acesso à API REST com tokens de API depende do plano do negócio. O servidor MCP não passa por essa verificação: se o seu plano não inclui a API REST, você ainda pode conectar um cliente de IA pelo MCP com OAuth. Veja MCP.

​
Tokens de acesso pessoal vs. chaves de API do negócio

  • Crie tokens de acesso pessoal no painel: avatar → Suas configurações → Chaves de API. A aba só aparece quando o plano inclui a API REST.
  • O token aparece uma única vez, na criação. Guarde-o na hora.
  • Os escopos são opcionais. Um token sem escopos tem o acesso completo do seu papel; restrinja-o com escopos como chat:read.
  • Os endpoints da biblioteca de mídia (/api/v1/businesses/library/images e /api/v1/businesses/library/documents) exigem uma credencial de usuário — um JWT ou um token de acesso pessoal. Uma chave de API do negócio recebe 401 neles.

​
A mensagem aparece como enviada, mas não chega

A Meta aceita uma mensagem livre enviada fora da janela de atendimento de 24 horas, devolve um id de mensagem e a rejeita depois, no status de entrega. A sua chamada de envio dá certo; a falha aparece em seguida.
  • Confira o status de entrega com a ferramenta MCP get_whatsapp_message_status, ou na própria mensagem, na conversa.
  • Para (re)abrir uma conversa, envie um modelo aprovado: pelo MCP, send_whatsapp_template_message; pela API REST, POST /api/v1/chats/{chat_id}/messages/template. Envios de modelo nunca são bloqueados pela janela.
Códigos de erro da Meta mais comuns no status de entrega:

​
Você não consegue ler a mídia que um cliente enviou

get_chat_messages retorna os metadados da mídia (nome do arquivo, tipo, id da mensagem), mas o campo media_url não é um link público de download. Use a ferramenta MCP download_media com a mensagem para baixar o arquivo.

​
Conversas de grupo não aparecem

A plataforma WhatsApp Business só entrega conversas individuais aos provedores. Grupos, Comunidades e Canais não estão disponíveis pela iZap.

​
O login do MCP falha ou usa a conta errada

A página de login OAuth aceita o seu e-mail e senha da iZap, ou o Google. Se você tem mais de uma conta Google aberta no navegador, escolha a que pertence ao negócio. Se a conexão continuar falhando, remova o conector do seu cliente de IA e adicione de novo.