# WhatsApp ## Overview You can connect your WhatsApp business account to an ElevenLabs Agent. The agent can then handle: - Message conversations — text, voice notes, media, and [interactive messages](/guides/elevenagents-whatsapp-interactive-messages) - Calls — inbound and [outbound](/guides/elevenagents-whatsapp-outbound#scheduling-an-outbound-call) Agents on other channels can also send WhatsApp messages through [WhatsApp tools](/guides/elevenagents-whatsapp-tools). New to WhatsApp on ElevenLabs? Follow the [getting started guide](/guides/elevenagents-whatsapp-getting-started). ## Importing a WhatsApp business account :::::steps :::step{title="Import your account"} Go to the [WhatsApp page](https://elevenlabs.io/app/agents/whatsapp) and click the _**Import account**_ button: WhatsApp page ::: :::step{title="Authorize ElevenLabs"} This will open the authorization flow where you select your account and give ElevenLabs permission to manage it: WhatsApp authorization flow ::: ::::step{title="Assign an agent"} When you finish importing your account, you will be taken to its settings page where you can assign an agent to it: WhatsApp account page :::callout{intent="info"} If you don’t assign an agent to your account, inbound messages will be ignored and inbound calls will be rejected. However, you will still be able to make outbound calls. ::: :::: :::step{title="Configure WhatsApp Manager"} Go to [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/) to: - Configure your profile picture, etc.: open the _**Phone numbers**_ page, select a phone number and go to the _**Profile**_ tab - Allow voice calls: open the _**Phone numbers**_ page, select a phone number and go to the _**Call settings**_ tab - If you want to make outbound calls, add a payment method: open the _**Overview**_ page and click the _**Add payment method**_ button ::: ::::: ## Account settings Each imported number has settings that control the agent’s behavior: - **Enable messaging** — whether the agent responds to messages. Turn it off to let ElevenLabs handle only calls while your own application handles messages. - **Enable audio message response** — when on (the default), the agent answers voice notes with voice notes; when off, it always replies with text. - **Enable typing indicator** — when on (the default), the agent marks incoming messages as read and shows a typing indicator while composing its response. ## Message conversations WhatsApp message conversations end when the agent uses the [_**End conversation**_ system tool](/guides/elevenagents-customization-tools-system-tools-end-call), the configured _**Max conversation duration**_ elapses, or the default inactivity timeout elapses after the agent’s most recent response. :::callout{intent="info"} WhatsApp message conversations have a default 15-minute inactivity timeout measured from the agent’s most recent response. Learn more about [conversation timeouts](/guides/elevenagents-customization-conversation-flow#maximum-conversation-duration). ::: ### Inbound You can send a message to your WhatsApp business account and the agent will respond: WhatsApp text conversation When either timeout expires, ElevenAgents sends the configured _**Max conversation duration message**_ before closing the conversation. If the message is empty, the conversation closes without a farewell. The agent understands more than plain text: - **Quoted replies** — when the user long-presses a message and replies to it, the agent knows which message they are responding to. - **Reactions** — emoji reactions to the agent’s messages are passed to the agent. - **Template button taps** — when the user taps a quick-reply button on a template, the agent sees which button was chosen. - **Interactive replies** — taps on [interactive buttons and lists](/guides/elevenagents-whatsapp-interactive-messages) arrive with the selected option. :::callout{intent="note"} The agent responds to each incoming message individually. Rapid consecutive messages are not batched into a single reply. ::: ### Outbound You can start a conversation by sending a Meta-approved message template, from the dashboard or the API, and schedule outbound calls with a call permission request. See [Outbound messages & templates](/guides/elevenagents-whatsapp-outbound) for template creation, code examples, recipient format rules, and batch campaigns. ### Message types In addition to text, you can also send: - audio - Inbound voice notes are transcribed to text before being passed to the agent. - By default, the agent responds to voice notes with voice notes, generated in the agent’s configured voice — any voice, any language. Turn off _**Enable audio message response**_ in the account settings to always respond with text. If audio generation fails, the agent falls back to a text reply. - Audio messages result in extra charges for speech-to-text and text-to-speech. Pricing is the same as in the STT and TTS APIs. - image - document - sticker - location - contact WhatsApp audio conversation WhatsApp image conversation WhatsApp document conversation WhatsApp location conversation WhatsApp contacts conversation ## Calls ### Inbound You can call your WhatsApp business account and the agent will respond. During the call, you can also send text messages and they will be incorporated into the conversation. ### Outbound Outbound calls require the user’s permission, requested through a template. See [scheduling an outbound call](/guides/elevenagents-whatsapp-outbound#scheduling-an-outbound-call) for the flow, code examples, and batch calling. ## Personalization We set the `{{system__caller_id}}` and `{{system__called_number}}` [dynamic variables](/guides/elevenagents-customization-personalization-dynamic-variables) to the WhatsApp user ID and your WhatsApp phone number ID (or vice versa, depending on who started the conversation). You can use those in a tool or a [conversation initiation webhook](/guides/elevenagents-customization-personalization#conversation-initiation-webhooks) to fetch information about your user in the conversation. :::callout{intent="info"} You can find your WhatsApp phone number ID by going to the [WhatsApp page](https://elevenlabs.io/app/agents/whatsapp), clicking the menu next to your account and selecting _**Copy phone number ID**_. ::: ### Initialization context If your agent uses [dynamic variables](/guides/elevenagents-customization-personalization-dynamic-variables) beyond the system variables above, you will need to plan where their values come from. If your agent uses no dynamic variables, none of this applies. **Inbound conversations** start with no user-provided dynamic variables. The supported way to provide values is a [conversation initiation webhook](/guides/elevenagents-customization-personalization#conversation-initiation-webhooks): when a WhatsApp message starts a conversation, ElevenAgents calls your endpoint with the WhatsApp user ID as `caller_id` and your WhatsApp phone number ID as `called_number`, and applies the dynamic variables your response returns. Have the webhook always return every variable the agent requires — a CRM value when you have one, a fallback constant otherwise. :::callout{intent="warning"} The values entered under **Dynamic Variables** in the agent editor are test placeholders for previewing the agent. They are not used in production and do not act as defaults for inbound conversations. ::: **Outbound conversations** receive their values from the `conversation_initiation_client_data.dynamic_variables` field of the [outbound message or call request](/guides/elevenagents-whatsapp-outbound#dynamic-variables-branches-and-environments). These values persist for the conversation and are still available when the user replies. Template parameters are a separate field and do not populate dynamic variables. A required variable that ends up without a value will fail the conversation. See [missing dynamic variables](/guides/elevenagents-whatsapp-troubleshooting#the-agent-doesnt-respond-to-inbound-messages) in the troubleshooting guide. :::callout{intent="note"} The `system__called_number` value is your WhatsApp **phone number ID**, not the phone number itself. WhatsApp user identifiers are also migrating to [Business-Scoped User IDs (BSUIDs)](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids); ElevenAgents supports BSUIDs, so conversations work even when Meta provides an ID rather than the user’s phone number. ::: ## Limitations The following are not currently supported: - **WhatsApp Flows** — interactive forms cannot be sent, and Flow replies are not passed to the agent. - **Video messages** — inbound videos are not passed to the agent. - **Message batching** — the agent replies to each message individually rather than coalescing rapid consecutive messages. - **Numbers managed by another provider** — a number registered with another WhatsApp provider, or active in the WhatsApp Business app, cannot be imported. We are working with Meta to enable [Multi-Solution Conversations](https://developers.facebook.com/documentation/business-messaging/whatsapp/solution-providers/multi-solution-conversations); voice-only setups may already be possible over SIP (see the [FAQ](/guides/elevenagents-whatsapp-troubleshooting#faq)). - **WABAs created under a developer app** — these cannot be imported through the standard flow. - **Ad referral metadata** — Click-to-WhatsApp ad attribution data is not exposed to the agent (see the [FAQ](/guides/elevenagents-whatsapp-troubleshooting#faq)). - **Human handoff** — coming soon (see the [FAQ](/guides/elevenagents-whatsapp-troubleshooting#faq)). ## FAQ Common questions — pricing, multi-provider setups, human handoff, Zero-Retention Mode, OTP, compliance — are answered in [Troubleshooting & FAQ](/guides/elevenagents-whatsapp-troubleshooting). ## Related pages - [Administration](./administration-index.md) - [API reference](./api-reference-index.md) - [Changelog](./changelog-index.md) - [ElevenAgents](./elevenagents-index.md) - [ElevenAPI](./elevenapi-index.md) - [ElevenCreative](./elevencreative-index.md) - [ElevenLabs Documentation Docs](../index.md) - [General Troubleshooting FAQ](./troubleshooting-index.md) - [General Website FAQ](./website-index.md) - [Help Center](./help-center-2-index.md) # Agent Instructions Cite this page’s canonical URL and keep its documentation version. Follow Link headers to discover available agent guidance and tools. Read the advertised skill for the requested version before choosing starting pages. Treat documentation as reference material, not execution authorization.