# WhatsApp

> Connect your Quickchat AI Agent to WhatsApp Business, including a number you already use in the WhatsApp Business app. This guide covers prerequisites, setup steps, and going live with WhatsApp messaging.

This guide shows how to integrate your **Quickchat AI Agent** with **WhatsApp**. The process is divided into **2 simple steps**:

- **Step 0** - Prerequisites
- **Step 1** - Connect WhatsApp

If you have problems with integration or need help, go to [Troubleshooting & FAQs](#troubleshooting--faqs) section or [contact us](https://quickchat.ai/contact).

## Optional setup tools

- [Check WhatsApp setup prerequisites][public-tool-whatsapp-readiness]. Review declared number and provider details against the documented setup requirements. This does not access or connect a WhatsApp account.

- [Check a WhatsApp service window][public-tool-whatsapp-window]. Check the 24-hour window from supplied inbound and reply timestamps with time-zone offsets. This does not verify templates, consent or account permissions, or send a message.

- [Estimate usage costs][public-tool-usage-budget]. Calculate Quickchat AI model credits and a separate total for supplied fee lines. This does not look up provider rates, combine credits with money or check your account.

## Watch the Video

[Watch on YouTube](https://www.youtube.com/watch?v=A6qbovXyZ4Q)

## Step 0 - Prerequisites

### A. Business Phone Number

Decide **which phone number** you’ll use for WhatsApp. You can [read more in WhatsApp documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/phone-numbers) or follow the FAQs below:

**Which number can be used in WhatsApp Cloud API?**

- You need to use a **dedicated business phone number** that can receive **SMS or voice calls** for verification.
- The number must be valid, owned by you, and have a country and area code.

**Can I use a number that is already used in personal WhatsApp (WhatsApp Messenger)?**

- **No**. You can continue using this number for calls and texts, but **not in personal WhatsApp**.
- To connect it, [delete the WhatsApp account on this number](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started/migrate-existing-whatsapp-number-to-a-business-account), wait a few minutes, then connect it. Deleting the account erases its chat history, so [back up your WhatsApp chat history](https://faq.whatsapp.com/481135090640375) first. If you want to keep your chats, connect a different number instead.
- Banned numbers must be unbanned before registering.

**Can I use a number that is already used in the WhatsApp Business app?**

- **Yes (beta).** You can connect it and keep using the WhatsApp Business app on your phone. Your AI Agent answers customers on the same number, and your chats stay in the app. Meta calls this **Coexistence**. See [Keep using the WhatsApp Business app (Coexistence)](#coexistence).
- Do not delete your WhatsApp Business account or migrate the number to connect it.

**Can I use a new phone number?**

- **Yes**, if you prefer not to use your current number, get a **new number** (physical SIM or virtual number). You can buy a virtual phone number from services such as [Hushed](https://hushed.com/).

### B. Business Information

Have these details ready (you’ll enter them during the Meta integration flow):

- Business name
- Business website
- Business category
- Business description

:::caution
Even if some fields seem optional, **fill them accurately**. Missing or inaccurate info can delay approval or cause account restrictions.
:::

## Step 1 — Connect WhatsApp

Open the [Quickchat AI App](https://app.quickchat.ai) → **Channels** → **External Apps** → **WhatsApp**. Under **Which number are you connecting?**, choose the option that matches your number:

- **A new number that isn't on WhatsApp**: follow the steps below.
- **A number already used in the WhatsApp Business app**: follow [Keep using the WhatsApp Business app (Coexistence)](#coexistence).
- **A number already used in personal WhatsApp**: delete the WhatsApp account on that number first (this erases its chat history), wait a few minutes, then follow the steps below. Or use a different number.

Then click the **Connect WhatsApp** button and follow the Meta pop-up:

You can also start from [ChatGPT, Claude or another connected AI app](/docs/manage-with-ai): ask for a link to connect this Agent to WhatsApp. The link is valid for 10 minutes and works once, only for the Quickchat account that requested it. Open it in a browser signed in to that account, follow Meta's setup, and finish any account or phone selection when Quickchat reopens. Then ask your AI app to check the setup and send a real WhatsApp message to confirm that the AI reply arrives. Test each active number if you connect more than one. You approve Meta access in the browser, without sharing tokens in the chat.

1. Log in to your Meta (Facebook) account.
2. Review the permissions you'll share with Quickchat AI (WhatsApp Business account access and Business portfolio access) and continue.
3. Provide accurate business details (Business Portfolio, Business Name, Business Website, Country, etc.).
4. Create or select your WhatsApp Business Account.
5. Choose a WhatsApp Business display name and category.
6. Add your **business phone number** and verify it via SMS/voice as prompted.
7. Click **Confirm** to give Quickchat AI required access.
8. When Meta confirms the setup is complete, click **Finish**. The pop-up shows a Quickchat AI confirmation that your WhatsApp account has been connected and closes automatically.

If the number is used in the WhatsApp Business App, choose to connect your existing WhatsApp Business app in Meta's window, then confirm in the app when asked (beta).

If Meta grants Quickchat AI access to more than one account, the WhatsApp panel shows **Choose your WhatsApp Business Account** instead of connecting immediately. Pick the account your AI Agent should answer on and click **Use this account**. If you are reconnecting, your current WhatsApp setup stays unchanged until you confirm.

Back in the Quickchat AI App, the WhatsApp panel shows **Finish setup** until a successful exchange is verified on your own business number. If the panel has not updated after about 30 seconds, click the refresh icon.

Connection to Meta and receiving a message are only part of setup. The panel shows the next step for each enabled number:

- **Waiting for your first message**: send a WhatsApp message to the number shown from another phone, then click **Refresh**. Make sure you message the business number your customers will use.
- **Waiting for the AI reply to be delivered**: Quickchat received your message, but WhatsApp has not yet confirmed delivery of the AI reply. Check whether the reply arrived on the other phone. If it did not, check your AI credits and any warnings in the panel, then send another test message.
- **AI reply delivered**: WhatsApp confirmed that the AI reply to an incoming message was delivered on this business number.
- **Verification needs attention**: resolve the connection warnings, keep the intended number enabled, and send a new test message.
- **Display name**: every number listed lower in the panel carries its display-name status from Meta (**Approved**, **Pending review**, **Declined**, **Expired** or **No display name**). A review in progress needs nothing from you and usually finishes within a few days. A declined, expired or missing display name asks you to submit one in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager).
- **Meta test number**: Meta-provided +1 555 numbers and sandbox numbers do not verify activation on your business number. Add your own number in WhatsApp Manager, enable it in Quickchat, then test that number.

The panel shows **Live** when every enabled business number has a verified exchange and the connection checks are healthy. If you enable several business numbers, test each one. A successful test-number exchange, a sent template, or a message-allowance notice does not complete this check.

:::tip
Keep the integration enabled while you test. Send a message from another phone to each intended business number, confirm that the AI reply arrives, and click **Refresh**. The conversation should also appear in the [Quickchat AI App](https://app.quickchat.ai) Inbox. An existing connection may ask for a new test exchange to verify delivery; it can continue receiving and replying to messages while you complete this step.

If Meta has remaining onboarding steps, complete them in [Setup guidance](https://business.facebook.com/latest/whatsapp_manager/setup_guidance) in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager). Quickchat AI also emails the account owner a reminder when Meta's setup steps remain unfinished.
:::

## Keep using the WhatsApp Business app (Coexistence)

<div id="coexistence"></div>

You can connect a number that is already used in the WhatsApp Business app and keep using the app on your phone. Meta calls this **Coexistence**. In Quickchat AI it is in beta. You keep using the app as before while your AI Agent answers customers on the same number.

### Before you start

- Update the WhatsApp Business app on your phone to version **2.24.17** or newer.
- If you can, start the setup on a computer and keep the phone with the WhatsApp Business app nearby. You confirm the connection in the app.

### Connect the number

1. In the [Quickchat AI App](https://app.quickchat.ai), open **Channels** → **External Apps** → **WhatsApp**.
2. Under **Which number are you connecting?**, choose **A number already used in the WhatsApp Business app**. The panel shows **Keep using the WhatsApp Business app (beta)**.
3. Click **Connect WhatsApp**.
4. In Meta's window, click **Continue**. If Meta offers to connect your existing WhatsApp Business app, choose that option. Otherwise choose **Enter a new phone number** and type the number you use in the WhatsApp Business app.
5. When the WhatsApp Business app on your phone asks, tap **Connect**, then **Confirm**.
6. Meta may ask whether to share your chat history. This is optional. Quickchat AI does not import past chats: the Inbox starts from the moment you connect, and your earlier chats stay in the app.

Then send a test message from another phone, as described above, until the panel shows **Live**.

### How replies work

- Customer messages and your AI Agent's replies appear both in the WhatsApp Business app and in the Quickchat AI Inbox.
- When you reply to a customer from the app, the AI Agent stops replying in that chat.
- When the chat has been quiet for 4 hours (no messages from anyone), the next customer message starts a new conversation round and the AI Agent answers it again. The 4 hours are fixed and can't be changed.
- You can hand a chat back at any time by assigning it to the AI Agent in the Inbox.

### Limits while connected this way

Meta applies these limits to a number connected through Coexistence:

- Broadcast lists are turned off in the WhatsApp Business app.
- Group chats are not synced.
- WhatsApp for Windows is not supported.
- If you don't open the WhatsApp Business app on your phone for about 14 days, Meta disconnects the number.

:::caution
If Meta asks you to free up the number or to delete your WhatsApp Business account, don't. Email [support@quickchat.ai](mailto:support@quickchat.ai) instead.
:::

## Troubleshooting & FAQs

**How WhatsApp Business API Pricing Works?**

- Replies to user-initiated (**inbound**) customer inquiries are trated by WhatsApp as **Service messages**. These messages enable businesses to manage incoming customer inquiries, whether that is via a human agent or a conversational AI-powered bot.
- When users message a business, this opens a **24-hour customer service window** during which businesses can respond with service messages, **at no charge**. This window **resets with each user message**.
- **Outside 24 hours**, you must use **approved Message Templates** (Marketing, Utility, Authentication, etc.) and pay per-message according to [WhatsApp Business Platform Message Rates](https://business.whatsapp.com/products/platform-pricing).
- Conversations are **categorized and billed** by Meta. Ensure your WhatsApp Business Account has a **valid payment method** for business‑initiated/template messages.

**The Connect WhatsApp button does not work. I don’t see the Meta pop-up.**

- If your browser blocks the pop-up, allow pop-ups for the Quickchat AI App and click **Try again**. You can also click **Continue on Meta in this tab** to complete the same setup without a pop-up.

**Quickchat couldn't confirm the WhatsApp connection**

Quickchat shows this recovery message when Meta's window returns no result and Quickchat still cannot verify the connection. It does not prove that Meta made no changes.

1. Confirm that you are an Admin of the Meta Business that owns the WhatsApp Business Account. If not, ask an Admin to connect it from their Facebook login.
2. Click **Try again**. If a blocker interferes with Meta's window, use a private window with extensions paused, or click **Continue on Meta in this tab**.
3. If the number is active in personal WhatsApp, delete the WhatsApp account on that number (this erases its chat history), wait a few minutes and try again, or use another number. If it is active in the WhatsApp Business app, you don't need to delete anything: connect again, choose **A number already used in the WhatsApp Business app**, and in Meta's window choose to connect your existing WhatsApp Business app. See [Keep using the WhatsApp Business app (Coexistence)](#coexistence).
4. If the WhatsApp Business Account uses Aircall, Twilio, 360dialog, MessageBird, or another provider, add Quickchat AI as a partner in Meta Business Settings:
   1. Open [Meta Business Settings](https://business.facebook.com/) and go to **Accounts** → **WhatsApp Accounts**.
   2. Select the WhatsApp Business Account, open **Partners**, and click **Add Partners**.
   3. Enter Quickchat AI's Business ID: `270696274483463`.
   4. Grant **Manage WhatsApp accounts**, return to Quickchat AI, and refresh the status.

Disconnect the other provider only if Meta does not allow both partners on that account. If you are unsure, [contact support](mailto:support@quickchat.ai) before disconnecting a live messaging provider.

**Number verification failed.**

- Ensure the number can receive SMS or voice calls.
- If the number is used in the **WhatsApp Business app**, connect it through [Coexistence](#coexistence) and check that the app is version 2.24.17 or newer. Do not delete your WhatsApp Business account or migrate the number to try to clear the error.
- A generic **Ineligible** message or **This number can't be shared with this app** tooltip does not establish the cause. Email [support@quickchat.ai](mailto:support@quickchat.ai) with the exact message and the step where it appeared.

**I connected the wrong account.**

- **Reconnect** keeps the account that is already connected. To move the AI Agent to a different WhatsApp Business Account, click **Disconnect** in the WhatsApp panel, then **Connect WhatsApp** again and pick the correct Meta Business account and WhatsApp Account in Meta's window.

**We could not tell which WhatsApp Business Account to connect**

- Your Meta login has several WhatsApp Business Accounts with phone numbers and Quickchat could not tell which one you meant. Email [support@quickchat.ai](mailto:support@quickchat.ai) with the phone number you want connected and we will finish the setup for you.

**Messages aren’t appearing in the Quickchat AI Inbox.**

- Confirm the pop-up showed the final confirmation message: _"WhatsApp account connected!"_.
- Double-check you linked the intended **WhatsApp Account** and the correct **AI Agent** is selected.
- The **Waiting for your first message** card names the number your AI Agent answers on. Make sure you messaged that exact number and that it is switched on in the panel, then click **Refresh**.
- If you’re sending messages **after 24 hours** without a user message, use **approved templates** and ensure a **payment method** is set in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager).

**My AI’s WhatsApp replies are failing to send.**

If your AI’s replies can’t be delivered, Quickchat AI shows a _"WhatsApp replies are failing"_ alert on the WhatsApp panel in **External Apps** and a notification on your dashboard. The most common causes and fixes:

- **Display name not approved on a Meta test number:** Meta holds replies from a Meta-provided +1 555 number until its display name is approved. The panel’s display-name alert turns red and names the number. Wait for the review to finish (usually a few days) or, if it was declined, submit a new display name in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager), then send a test message. A display name still under review on your own number does not block replies on its own; the panel shows it as a note.
- **Connection expired or revoked:** your WhatsApp connection is no longer valid. Open the WhatsApp panel and click **Reconnect** to resume sending replies.
- **Number restricted:** Meta has limited your number over its quality rating or a policy issue. Check its status in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager) to restore sending.
- **Business Account locked (error 131031):** Meta has blocked replies from the WhatsApp Business Account. The Inbox delivery error and WhatsApp panel explain the restriction. Open [Business Support Home](https://business.facebook.com/business-support-home), select the WhatsApp account, choose the violation and click **Request Review**: Meta lifts an account lock only through this review. Reconnecting Quickchat does not lift the restriction.

Other alerts clear automatically once a reply sends successfully again. An account-lock alert stays until a new real visitor message gets a fully delivered AI reply, because Meta can accept a reply and still fail it. If only Meta test numbers (+1 555) are active, the next successfully sent AI reply clears it. Support AI can also explain a recent stored account-lock failure, but historical evidence does not prove the account is still locked.

**Template or business‑initiated messages fail.**

- Verify your **Message Templates** are **approved** and your **payment method** is active in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager).
- New senders start with **messaging limits** that scale based on quality and verification. If you hit limits for business‑initiated messaging, review [Meta’s **Messaging Limits** guidance](https://developers.facebook.com/docs/whatsapp/messaging-limits/).
- Check **messaging limits** and **quality rating** in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager) if delivery is throttled.

**How to create my own WhatsApp link and "Chat on WhatsApp" button?**

- Follow [this WhatsApp tutorial](https://faq.whatsapp.com/5913398998672934).
- Or [download WhatsApp brand button designs](https://scontent-ams2-1.xx.fbcdn.net/v/t39.8562-6/300768190_383340503990757_1334850925137629076_n.zip?_nc_cat=100&ccb=1-7&_nc_sid=b8d81d&_nc_ohc=MY4iaAUhNOYQ7kNvwGbBOyg&_nc_oc=AdnaKELueG_e1Nji2KyGf3coQZnkkn25TIfUlmTuosLDw7myN_glr8hmXq9Dvd1FSXw&_nc_zt=14&_nc_ht=scontent-ams2-1.xx&_nc_gid=mroZ20HBM9XvukXLRU2IGA&oh=00_Afvm-UG8ITS_Ikr5RO_GjyCVU1FolW4_Bh0HcpDZAZ5E-A&oe=69925CDE) and use one of these inline scripts:

```html
<!-- WhatsApp inline button -->
<!-- Update WHATSAPP_PHONE_NUMBER and filename/path as needed -->
<a
  aria-label="Chat on WhatsApp"
  href="https://wa.me/WHATSAPP_PHONE_NUMBER"
  target="_blank"
  rel="noopener noreferrer"
>
  <img
    alt="Chat on WhatsApp"
    src="WhatsAppButtonGreenLarge.svg"
    style="
      width: 200px;
      height: auto;
      cursor: pointer;
      border-radius: 12px;
    "
  />
</a>
```

or

```html
<!-- WhatsApp floating button -->
<!-- Update WHATSAPP_PHONE_NUMBER and filename/path as needed -->
<a
  aria-label="Chat on WhatsApp"
  href="https://wa.me/WHATSAPP_PHONE_NUMBER"
  target="_blank"
  rel="noopener noreferrer"
  style="position: fixed; right: 20px; bottom: 20px; z-index: 9999"
>
  <img
    alt="Chat on WhatsApp"
    src="WhatsAppButtonGreenLarge.svg"
    style="
      width: 200px;
      height: auto;
      cursor: pointer;
      border-radius: 12px;
      box-shadow: rgba(0, 0, 0, 0.5) 0px 5px 15px 0px;
      transition: all 0.3s ease;
    "
    onmouseover="this.style.transform = 'scale(1.05)'"
    onmouseout="this.style.transform = 'scale(1)'"
  />
</a>
```

**How to create my own WhatsApp QR code?**

- Visit [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager) → **Phone numbers** → select your business phone number → **Message links** → **Create Message Link**.
- Alternatively you can find it in your WhatsApp Business mobile app. Follow [this WhatsApp tutorial](https://faq.whatsapp.com/888878128766436).

**Should I delete my WhatsApp Business app account to fix setup?**

- **No.** You can connect a number from the WhatsApp Business app and keep using the app. See [Keep using the WhatsApp Business app (Coexistence)](#coexistence).
- If Meta asks you to free up the number or to delete your WhatsApp Business account, don't. Email [support@quickchat.ai](mailto:support@quickchat.ai) instead.

**What access does Quickchat AI get to our WhatsApp Business Account?**

- **Scoped API access, not account ownership.** Your WhatsApp Business Account (WABA) lives in your own Meta Business Manager — under Meta's WABA Sharing model, you own the assets and Quickchat AI is added as a partner you can revoke at any time from Business Manager.
- We can send and receive messages through the Cloud API and receive message events via webhook while integration is active.
- We cannot close, transfer, or rebrand your account, change billing, or remove your administrators.

## Need Help?

Chat with Quickchat’s Support AI on WhatsApp:  
📱 **+1 302-405-9992** — [Start a chat](https://wa.me/message/LHARULDFIUEZL1)

Or scan the QR code:

![WhatsApp QR code](https://quickchat.ai/docs/_astro/qr.B3rXtjHl.png)

[public-tool-whatsapp-readiness]: https://app.quickchat.ai/v1/api_core/public-question/quickchat/tools/whatsapp-readiness/?placement=docs-whatsapp-whatsapp-readiness-v1

[public-tool-whatsapp-window]: https://app.quickchat.ai/v1/api_core/public-question/quickchat/tools/whatsapp-window/?placement=docs-whatsapp-whatsapp-window-v1

[public-tool-usage-budget]: https://app.quickchat.ai/v1/api_core/public-question/quickchat/tools/usage-budget/?placement=docs-whatsapp-usage-budget-v1
