> For the complete documentation index, see [llms.txt](https://aibotkit.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://aibotkit.gitbook.io/documentation/channels-and-integrations/whatsapp.md). # WhatsApp Connect your AI Bot Kit chatbot to WhatsApp Business so customers can chat with the same trained bot directly from WhatsApp. Replies, lead capture, and human handover all work -- including a per-conversation **takeover** so an agent can step in. ## What you need * A **business phone number** that's eligible for WhatsApp Business API * A **Meta Business** account (the embedded signup flow takes you through verification) * A paid plan (Basic, Essential, or Business) You do **not** need a Meta developer account or BSP approvals up front -- AI Bot Kit handles delivery through **Pinnacle**, our WhatsApp BSP. ## How to connect 1. Open your chatbot and go to **INTEGRATIONS** in the left sidebar. 2. Click **Connect** on the WhatsApp card. 3. The Pinnacle embedded-signup iframe opens. Sign in with your Meta Business account, pick the phone number you want to use, and approve the requested permissions. 4. Once connected, the card shows **Connected** status. 5. Toggle **Enable WhatsApp** to start receiving messages. You can pause delivery at any time without losing the connection. > **Note:** Records created before the toggle was added are treated as enabled by default. When connected, you'll see: * **Connected status** -- "Your WhatsApp channel is active. Messages are being processed by your AI agent." * **Feature bullets:** * **End-to-end encrypted** -- Secure messaging via WhatsApp * **Instant replies** -- Your bot responds in real time * **2B+ users on WhatsApp** -- Reach customers on the world's most popular messaging app * **Share with your customers** -- A `wa.me` link and QR code customers can use to start chatting * **Disable WhatsApp** toggle -- Turn delivery on/off without disconnecting ## What happens when a customer messages you 1. Pinnacle delivers the message to `/api/whatsapp/callback`. The webhook verifies the HMAC-SHA256 signature. 2. The message is parsed (text or media), the session ID is `wa_`, and it's enqueued for the RAG engine. 3. The chatbot generates a reply. HTML and tool markers are stripped (WhatsApp doesn't render HTML), then the reply is sent back via Pinnacle. 4. Both messages appear in your dashboard's **Conversations** view with a WhatsApp source badge. If the chatbot's per-session AI toggle is **off**, the message is stored but no AI reply is sent -- you can reply manually as the owner. See [Live Chat & Human Takeover](/documentation/chatbot-editor/live-chat.md). ## The 24-hour customer-service window WhatsApp (Meta) only allows free-form messages **within 24 hours of the customer's last inbound message**. AI Bot Kit tracks `last_inbound_at` per conversation: * If you try to reply manually after the 24-hour window, the composer is disabled with a tooltip explaining why. * The owner-send API returns `409 WA_WINDOW_CLOSED` if attempted out-of-window. * Once the customer messages again, the window reopens automatically. ## Frequently Asked **Can I use my existing WhatsApp number?**\ Yes, if it's not currently registered with the WhatsApp Business API on another BSP. The embedded signup flow detects this and guides you through migration. **Do messages count against my Monthly AI Messages quota?**\ Yes. Every assistant reply on WhatsApp is counted exactly the same as a website widget reply. **What about media (images, voice notes)?**\ Inbound media is logged. The chatbot replies with text only by default; rich responses are on the roadmap. **Can I disconnect?**\ Yes. Toggle **Enable WhatsApp** off to stop delivery. Use the **Disconnect** action to remove credentials. Existing conversation history is preserved. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://aibotkit.gitbook.io/documentation/channels-and-integrations/whatsapp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.