Troubleshooting & FAQ

Message accepted but not delivered

A 200 response from the outbound message endpoint means ElevenLabs accepted and forwarded the request — delivery is still up to Meta. If the message never arrives, check in order:

1. Template approval — the template must have status Approved in WhatsApp Manager. Pending or rejected templates are not delivered.
2. Payments — a missing payment method or unsettled payments on your WhatsApp business account block template delivery (Meta error 131042). Add or update the payment method in WhatsApp Manager.
3. Parameter shape — template_params entries must be component objects ({"type": "body", "parameters": [...]}), every placeholder in the template must be filled, and named templates need a parameter_name on each value. See template parameters.
4. Recipient format — whatsapp_user_id is digits only with country code, no +. See recipient number format.
5. Marketing limits — Meta caps how many marketing templates one user can receive in a period (error 131049). Utility templates are not subject to this cap.

Import problems

• The number can’t be imported — it is registered with another WhatsApp provider or active in the WhatsApp Business app. A number can only be registered with one provider; see Limitations.
• Your WABA doesn’t appear in the import flow — confirm you are logged into a Facebook account with admin access to the business portfolio that owns the WABA, then retry the import.
• WABAs created under a Meta developer app cannot be imported through the standard flow.

To check whether another partner already controls your number, open WhatsApp accounts in Meta Business settings, select the WhatsApp account that contains your number, and review its partners. A partner listed there with control over the number explains both a failed import and a missing WABA — remove the partner or use a different number.

The agent doesn’t respond to inbound messages

The read receipt and typing indicator narrow the cause down: they are sent the moment a message is accepted for processing, before the agent produces a reply. With Enable typing indicator on (the default), send a test message and watch whether your message is marked read and the typing indicator appears.

The typing indicator appears, but no reply arrives. The message reached ElevenLabs and the agent started working; the failure happens while producing or delivering the reply:

• The agent requires a dynamic variable that has no value. Inbound WhatsApp conversations start with no user-provided dynamic variables — only the system variables are populated. The fix is a conversation initiation webhook that returns every variable the agent requires; see initialization context. The values entered under Dynamic Variables in the agent editor are test placeholders and are not used in production.
• Meta declined the agent’s reply — for example a rate limit for this business–user pair or an account-level payment issue. See the error reference below.

The conversation fails if these required dynamic variables are not present.

No typing indicator appears. The message was dropped before reaching the agent:

• No agent is assigned to the number, or the Enable messaging switch is off — check the account settings on the WhatsApp page.
• The account’s authorization is no longer valid — the access token expired or was revoked on the Meta side. Re-import the account on the WhatsApp page.
• The agent workspace is in Zero-Retention Mode, which ignores inbound WhatsApp messages entirely.
• The inbound message is an unsupported type (for example video, or a WhatsApp Flow reply) — see Limitations.

The first reply after a template misbehaves

If your agent has the First message override enabled on its Security tab, it can conflict with outbound template conversations — the template already served as the first message. If replies to templates behave unexpectedly, remove the first-message override for agents used with WhatsApp outbound messages.

Meta error reference

Errors Meta returns during delivery are surfaced with remediation advice where possible. The most common:

For the full list, see Meta’s error code reference.

FAQ