> For the complete documentation index, see [llms.txt](https://docs.1millionbot.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.1millionbot.com/chatbot/channels/whatsapp-cloud-api.md).

# WhatsApp Cloud API

## Set up

> Meta frequently updates and redesigns its developer console, so the steps and menu names in this guide may become outdated. If something doesn't match what you see on screen, check Meta's official, always up-to-date documentation: [WhatsApp Cloud API – Get Started](https://developers.facebook.com/documentation/business-messaging/whatsapp/get-started).

To set up the integration of your agent in WhatsApp Cloud API, you will need the following:

* A Meta account registered as a developer in the [developers console](https://developers.facebook.com/).
* A Business Portfolio in Meta Business — it can be created during app creation if you don't already have one.
* An available phone number.

### Create a Meta app

> Meta redesigned the app creation flow around "use cases". You no longer create a generic 'Other' > 'Business' app and then look for the WhatsApp module in the Dashboard: WhatsApp is selected directly as a use case during app creation.

1. Access the [Meta developers console](https://developers.facebook.com/apps/).
2. Click on 'Create app'.
3. Enter the app name and a contact email.
4. On the use case selection screen, choose **'Connect with customers through WhatsApp'** and click 'Next'.
5. Select an existing business portfolio linked to your Meta Business, or create a new one.
6. Review the publishing requirements (they may appear empty at this point) and click 'Create app' to finish.

Once created, the app opens directly into the WhatsApp use case view (there is no longer a need to locate the module from a general 'Dashboard').

### Add your phone number

1. In the app's side menu, go to **Customize use case** > **Connect on WhatsApp** > **Quickstart**.
2. Click on 'Start using the API'.
3. Connect an existing WhatsApp Business account or create a new one from the same wizard.
4. Select an available phone number, or click on 'Add a phone number', fill in the details, and validate the link with the WhatsApp Business API account through the confirmation SMS or call.

### Generate a Permanent Access Token

1. Navigate to [Facebook Business](https://business.facebook.com/).
2. From the side menu, select **Users** > **System Users**.
3. Add a new user with administrator privileges.
4. In the side menu, go to **Accounts** > **WhatsApp Accounts**.
5. Grant full control permissions to the newly created user.
6. Return to the **System Users** section and click on **Assign Assets**.
7. Choose the desired application and assign admin permissions.
8. Once saved, click on **Generate New Token**.
9. Select the application, set the expiry to **Never**, and enable WhatsApp permissions.
10. Copy the generated authentication token for future use.

### Obtain the Phone Number ID

1. Navigate to [Meta developers console](https://developers.facebook.com/apps/).
2. Access to the created application.
3. Go to the **Customize use case** > **Connect on WhatsApp** > **Quickstart** (or **API Setup**) menu section.
4. Select the linked phone and copy the ID displayed below it (Phone Number ID).

### Obtain the application secret key

1. Navigate to [Meta developers console](https://developers.facebook.com/apps/).
2. Access to the created application.
3. Go the **Settings** > **Basic Information** menu section.
4. Click show and copy the application secret key.

### Connect your app with your agent

#### Activate integration in 1millionbot platform

1. Go to the **Channels** section on the platform.
2. Activate WhatsApp and click on 'Settings'.
3. Enter the previously obtained data: Application Secret Key, Permanent Access Token and Phone Number ID
4. Click on 'Save'.\
   ![](https://2695835661-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fr8C1OyhEMqQrgYKVMdeJ%2Fuploads%2FCY0f1Ss9nn94estckq6m%2FWS_7.png?alt=media\&token=63cc994a-7e2c-4664-93e3-a9c2bdb83706)

#### Activate integration in Meta

**Obtain the Callback URL**

1. Go to the 1millionbot platform and click on the 'Info' button in the WhatsApp Cloud channel to get the callback URL.\
   ![](https://2695835661-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fr8C1OyhEMqQrgYKVMdeJ%2Fuploads%2FYuwtAwTVKjdni7tc83hx%2FWS_8.png?alt=media\&token=78b77a13-b313-4c60-ba54-8a403eec753e)

**Configure the Meta Webhook**

1. In the **Customize use case** > **Connect on WhatsApp** > **Configuration** menu section of the Meta developers console, click on 'Edit' in the **Webhook** section.
2. Paste the callback URL obtained from the 1millionbot platform and enter the Permanent Authentication Token.
3. Click 'Save' to apply the changes.

### Set permissions

1. In the same **Configuration** section, click on 'Manage' next to the Webhook to activate the necessary subscription fields:\
   \- *messages*
2. Click 'Save' to apply the changes.

### Publish Meta app

1. Now, your application is in development mode, so you can test the agent's operation as long as the phone number you use to interact with the agent belongs to one of the users with access to the application (up to 5 test numbers).
2. To publish the agent for public interaction, change the mode from development to production and provide all the necessary information (found at the top of the Meta developer console).
3. Complete your Meta Business **Business Verification**. It isn't required to publish the app, but it is required to raise the initial messaging limit and unlock higher messaging tiers (see Limitations).
4. Done! Once published, perform tests to verify the operation of your agent on the provided phone number in WhatsApp. 🎉

> ⚠️ **Important:** if you later change your phone number's **Display Name** and Meta approves the change, the number automatically becomes **unregistered** and can no longer send or receive messages until it's registered again. Meta explicitly states that this re-registration **cannot be done with buttons from the console or WhatsApp Manager**: it can only be done through a direct API call.

#### How to re-register the number after a Display Name change

1. Find or reset your 6-digit **two-step verification PIN** in WhatsApp Manager: **Settings** > **WhatsApp Accounts** > your account > **Settings** > **WhatsApp Manager** > select the number > **Settings** > **Two-step verification** > **Change PIN**.
2. Make a `POST` request to Meta's registration endpoint with your Permanent Access Token, the Phone Number ID, and that PIN:

   ```
   curl -X POST \
     'https://graph.facebook.com/v23.0/{PHONE_NUMBER_ID}/register' \
     -H 'Authorization: Bearer {PERMANENT_ACCESS_TOKEN}' \
     -H 'Content-Type: application/json' \
     -d '{"messaging_product": "whatsapp", "pin": "{YOUR_PIN}"}'
   ```
3. If you don't have a tool to make this request (Postman, cURL...) or a developer to help you, contact 1millionbot support to complete the registration for you.

Meta limits this call to 10 requests per number every 72 hours (error `133016` if exceeded).

## Limitations

* Initial limit of 250 business-initiated conversations per 24h for new phone numbers. This scales automatically to 1,000, 10,000, 100,000 or unlimited based on sustained usage volume and Business Verification ([+ info](https://developers.facebook.com/documentation/business-messaging/whatsapp/messaging-limits)).
* Maximum of 3 quick-reply buttons per message.
* Each quick-reply button can have a maximum of 20 characters.