Skip to main content
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.

​
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

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.

​
Personal access tokens vs. business API keys

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

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