> ## Documentation Index > Fetch the complete documentation index at: https://docs.irisagent.com/llms.txt > Use this file to discover all available pages before exploring further. # WhatsApp > Connect your WhatsApp Business number to IrisAgent so your AI agent answers customers on WhatsApp, grounded in your knowledge base Connect a WhatsApp Business number to IrisAgent, and your AI agent answers every customer who messages it, grounded in your knowledge base and in the customer's own language. Your team can take over any conversation from the IrisAgent inbox. ## Connect with Facebook The quickest way to connect. Meta's WhatsApp signup opens in a popup, and IrisAgent sets up everything else. **You need:** * IrisAgent admin access. * A Facebook account that manages your company's Meta Business portfolio, or can create one. * A phone number that can receive an SMS or voice call, and that isn't already on WhatsApp. See "Use a number that's already on WhatsApp" under [Other ways to connect](#other-ways-to-connect). **Steps:** 1. In IrisAgent, go to **Deploy → Text channels**. 2. On the **WhatsApp** card, click **Connect with Facebook**. 3. In the popup, choose or create your **Meta Business portfolio** and **WhatsApp Business Account**. 4. Add your phone number and display name, and verify the number with the code Meta sends. 5. Click **Confirm**. The card shows your number as **Connected**, and AI replies are on. Meta reviews your display name, which usually takes a few hours; your number can answer messages before the review finishes. Meta bills you directly for WhatsApp messages. Add a payment method in **WhatsApp Manager → Account tools → Payment methods**. See [Meta's WhatsApp pricing](https://developers.facebook.com/docs/whatsapp/pricing). ## Test it 1. From a personal WhatsApp account, message your business number with a common question, such as "What is your refund policy?" 2. Check that your AI agent replies with an answer from your knowledge base. 3. In IrisAgent, open **Activity → Conversations** to see the conversation. ## Reply from the inbox To answer a customer yourself, open the conversation in **Activity → Conversations** and click **Take over**. The AI stops replying while you own the conversation, and your replies go to the customer on WhatsApp. When a customer asks for a person, the conversation waits in the inbox for an agent. See [Live chat](https://docs.irisagent.com/helpdesk/Live-Chat.md). WhatsApp only delivers replies within **24 hours of the customer's last message**. After that, the conversation shows as **Resolved**, and the customer's next message starts a new one. ## Manage the connection * **Pause or resume AI replies:** use the **AI replies** toggle on the WhatsApp card. While paused, messages are received but not answered. * **Change the number:** click **Change number** on the card, then **Connect with Facebook** and pick the new number. The previous number is disconnected. ## How your AI agent answers * Text messages and button replies are answered. Images, voice notes and other media are not answered yet. * Answers are plain text, with source links listed as "Title: URL". * After 24 hours without messages, the next message starts a new conversation. * IrisAgent doesn't send WhatsApp template messages, so it never messages a customer first. * A WhatsApp number can be connected to only one IrisAgent account. ## Other ways to connect Most teams should use [Connect with Facebook](#connect-with-facebook). These options are for teams with specific needs. > [accordion] Connect with IDs and a token > > For teams that manage Meta access themselves. > > 1. In [Business Settings → System users](https://business.facebook.com/settings/system-users), create a system user with **Full control** of your WhatsApp Business Account. > 2. Generate a token for it with expiry **Never** and the `whatsapp_business_messaging` and `whatsapp_business_management` permissions. > 3. In WhatsApp Manager, copy your **Phone number ID** (a numeric ID, not the phone number) and **WhatsApp Business Account ID**. > 4. On the WhatsApp card, click **Connect with IDs and a token instead**, fill in the three fields, and click **Connect WhatsApp**. > > IrisAgent checks that the token can access the number, then stores it encrypted. No webhook setup is needed. > [accordion] Connect through your own Meta app > > For teams that need to run WhatsApp through a Meta app in their own business portfolio. The IrisAgent team finishes the setup. > > 1. At [Meta for Developers](https://developers.facebook.com/apps), create an app with the use case **Connect with customers through WhatsApp**. > 2. In **WhatsApp → API Setup**, add and verify your phone number. > 3. In Business Settings, create a system user with **Full control** of the app and your WhatsApp Business Account, and generate a token with expiry **Never** and both WhatsApp permissions. > 4. In **App settings → Basic**, add your privacy policy URL, then **Publish** the app. No App Review is needed. > 5. Send your IrisAgent contact the **Phone number ID**, **WhatsApp Business Account ID**, **App ID**, **App secret** and **token** over a secure channel, such as a password manager share. Never send them in a regular email. > > IrisAgent subscribes your app and sets its webhook. To confirm, open **WhatsApp → Configuration** in your app: the callback URL starts with `https://frontend-api-server-v2.api.irisagent.com/v1/webhooks/whatsapp/` and **messages** is subscribed. > > You can switch to Connect with Facebook at any time; your number stays the same. > [accordion] Use a number that's already on WhatsApp > > A number can only be used by one WhatsApp service at a time. > > * **On the WhatsApp or WhatsApp Business app:** delete the WhatsApp account in the app first (**Settings → Account → Delete account**). Chat history stays on the phone but doesn't move to IrisAgent. > * **With another WhatsApp provider:** ask the provider to release the number first. ## Troubleshooting | Problem | What to do | | - | - | | The Facebook popup doesn't open | Allow pop-ups for web.irisagent.com, and check that an extension isn't blocking connect.facebook.net. | | "Meta did not accept the signup code…" | The signup took too long. Click **Connect with Facebook** again. | | "registering your number with WhatsApp failed…" | The number has a two-step verification PIN. Turn it off in **WhatsApp Manager → Phone numbers → Settings → Two-step verification** and connect again. | | "this WhatsApp phone number is connected to another customer" | The number is connected to a different IrisAgent account. Disconnect it there first, or [contact us](mailto:contact@irisagent.com). | | "WhatsApp only delivers replies within 24 hours…" | The customer last wrote more than 24 hours ago. Reply once they write again. | | "the access token cannot access this WhatsApp phone number" | (IDs and a token) Give the system user **Full control** of the WhatsApp Business Account and generate a new token. | | The card is read-only | Only dashboard admins can connect a number. Ask an admin. | | Customers get no replies | Check the card shows **Connected**, not **Paused**, and check the number's quality rating in WhatsApp Manager. | IrisAgent sets a two-step verification PIN on your number when it connects. If you ever move the number elsewhere, reset the PIN in **WhatsApp Manager → Phone numbers → Settings → Two-step verification**. ## Related pages * [WhatsApp through your help desk](https://docs.irisagent.com/deploying-irisagent/Chatbot-Automation-on-WhatsApp.md) * [Live chat](https://docs.irisagent.com/helpdesk/Live-Chat.md) * [Meta: WhatsApp Cloud API documentation](https://developers.facebook.com/docs/whatsapp/cloud-api) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.