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

# Troubleshooting

> Fixes for the issues developers hit most often with the iZap REST API and MCP server.

Each entry below starts from the symptom you see. For WhatsApp connection errors
from Meta (such as `#2655093` or `#3441038`), see the help center page
[WhatsApp connection problems](https://docs.izap.ai/en/troubleshoot-whatsapp-connection).

## `GET /api/v1/chats/{business_id}` returns test conversations

The `kind` query parameter defaults to `trainer`, which returns the AI Trainer's
sandbox conversations. Pass `kind=real` for real WhatsApp conversations, or
`kind=all` for both. Any other value returns `400`.

## Polling with `since` returns messages you've already seen

`since` is an ISO-8601 timestamp, exclusive (strictly newer than), and treated
as UTC when it has no offset. It filters **which chats** are returned — not the
messages embedded in each chat. Every returned chat still embeds its
`messages_per_chat` most recent messages (default 1, up to 200), regardless of
`since`.

To sync messages reliably:

* De-duplicate on the message `id`, or
* Fetch each changed chat's thread from `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." }
```

REST API access with API tokens depends on the business's plan. The MCP server
is not subject to this check: if your plan doesn't include the REST API, you can
still connect an AI client over MCP with OAuth. See
[MCP](/en/api-reference/mcp).

## Personal access tokens vs. business API keys

|                | Personal access token             | Business API key                                                        |
| -------------- | --------------------------------- | ----------------------------------------------------------------------- |
| Prefix         | `izap_pat_`                       | `izap_sk_`                                                              |
| Acts as        | You, with your role's permissions | One business                                                            |
| Where it works | Any endpoint your login works on  | Only endpoints that accept business keys (for example, chats and menus) |

* Create personal access tokens in the dashboard: avatar → **Your settings** →
  **API Keys**. The tab only appears when the plan includes the REST API.
* The token is shown **once**, at creation. Store it right away.
* Scopes are optional. A token with no scopes has your role's full access;
  narrow it with scopes such as `chat:read`.
* The media library endpoints (`/api/v1/businesses/library/images` and
  `/api/v1/businesses/library/documents`) require a user credential — a JWT or
  a personal access token. A business API key gets `401` there.

## A message is reported as sent, but never arrives

Meta accepts a free-form message sent outside the 24-hour customer-service
window, returns a message id, and rejects it **later**, on the delivery status.
Your send call succeeds; the failure shows up afterwards.

* Check the delivery status with the MCP tool `get_whatsapp_message_status`, or
  on the message in the conversation.
* To (re)open a conversation, send an approved template: MCP
  `send_whatsapp_template_message`, or REST
  `POST /api/v1/chats/{chat_id}/messages/template`. Template sends are never
  blocked by the window.

Common Meta error codes on the delivery status:

| Code              | Meaning                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------ |
| `131047`          | The 24-hour window is closed. Send an approved template.                                   |
| `131026`          | The message couldn't be delivered, for example because the number isn't on WhatsApp.       |
| `131049`          | Meta held back a marketing message to protect the recipient's experience. Try again later. |
| `132000`–`132015` | A problem with the template itself (parameters, status, or format).                        |

## You can't read media a customer sent

`get_chat_messages` returns media metadata (file name, type, message id), but
the `media_url` field is not a public download link. Use the MCP tool
`download_media` with the message to fetch the file itself.

## Group chats don't show up

The WhatsApp Business Platform only delivers one-to-one conversations to
providers. Groups, Communities, and Channels aren't available through iZap.

## MCP sign-in fails or uses the wrong account

The OAuth sign-in page accepts your iZap email and password, or Google. If you
have more than one Google account in the browser, make sure you pick the one
that belongs to the business. If the connection still fails, remove the
connector from your AI client and add it again.