> ## Documentation Index
> Fetch the complete documentation index at: https://devs.izap.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Solução de problemas

> Soluções para os problemas mais comuns de quem desenvolve com a API REST e o servidor MCP da iZap.

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](https://docs.izap.ai/pt/troubleshoot-whatsapp-connection).

## `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`

```json theme={null}
{ "code": "plan_limit_rest_api", "detail": "The REST API is not included in your plan. Upgrade to use API tokens." }
```

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](/pt/api-reference/mcp).

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

|               | Token de acesso pessoal                          | Chave de API do negócio                                                         |
| ------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
| Prefixo       | `izap_pat_`                                      | `izap_sk_`                                                                      |
| Age como      | Você, com as permissões do seu papel             | Um negócio                                                                      |
| Onde funciona | Em qualquer endpoint em que o seu login funciona | Só nos endpoints que aceitam chaves de negócio (por exemplo, chats e cardápios) |

* 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:

| Código            | Significado                                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| `131047`          | A janela de 24 horas está fechada. Envie um modelo aprovado.                                            |
| `131026`          | A mensagem não pôde ser entregue, por exemplo porque o número não está no WhatsApp.                     |
| `131049`          | A Meta segurou uma mensagem de marketing para proteger a experiência do destinatário. Tente mais tarde. |
| `132000`–`132015` | Um problema no próprio modelo (parâmetros, status ou formato).                                          |

## 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.