> ## Documentation Index
> Fetch the complete documentation index at: https://docs.libredesk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# WhatsApp
> Connect a WhatsApp number through Meta's Cloud API
Libredesk connects directly to Meta's WhatsApp Cloud API. You create a Meta app, register a business phone number, then add its credentials to a WhatsApp inbox in Libredesk.
## Before you start
You need:
* A Facebook account with access to a Meta business portfolio, or permission to create one
* A phone number that can receive an SMS or voice call
* A public HTTPS URL for your Libredesk instance
* A public privacy policy URL for publishing the Meta app
For this setup, use a number that is not registered with the WhatsApp or WhatsApp Business mobile app. Removing an existing account from either app deletes its chat history.
## Create the Meta app
Open [Meta for Developers](https://developers.facebook.com/apps/), select **My Apps → Create App**, then enter an app name and contact email.
Select **Connect with customers through WhatsApp**, then select **Next**.
Select the business portfolio that will own the WhatsApp Business Account. Review the requirements, confirm the app details, then select **Create app**.
In the app dashboard, go to **Use cases → Customize** next to **Connect with customers through WhatsApp**. Under **Basic setup**, open **Step 2. Production setup**.
## Add and verify the phone number
In **Step 2. Production setup**, expand **Register your WhatsApp phone number** and select **Add new number**.
Complete the four stages shown by Meta:
1. Enter the legal business name, website or social profile, and country.
2. Create the WhatsApp Business profile, including its customer-facing display name.
3. Enter the phone number and choose SMS or voice verification.
4. Enter the verification code sent by Meta.
Meta reviews eligible [display names](https://developers.facebook.com/documentation/business-messaging/whatsapp/display-names) before showing them in chat headers. If yours is rejected, review Meta's naming guidelines and update it in WhatsApp Manager.
### Copy the account IDs
If your app dashboard has an **API Setup** panel, select your business number and copy its **Phone number ID** and **WhatsApp Business Account ID**. Make sure you select your own number, not Meta's test number.
Alternatively, open [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/) and select the WhatsApp Business Account you created.
* The account selector at the top shows the **WhatsApp Business Account ID**.
* Under **Account tools → Phone numbers**, select your number to show its **Phone number ID**.
These are numeric IDs. Do not enter the phone number, app ID, or business portfolio ID in their place.
## Copy the Meta credentials
### System User access token
Use a [System User access token](https://developers.facebook.com/documentation/business-messaging/whatsapp/access-tokens#system-user-access-tokens) for this connection.
1. Open [Meta Business Settings](https://business.facebook.com/settings/) and select the business portfolio that owns your app and WhatsApp Business Account.
2. Go to **Users → System Users**, select **Add**, and create a system user with the **Admin** role.
3. Select **Assign assets**, choose your app, and grant **Full control → Manage app**. Ensure the system user also has access to your WhatsApp Business Account under **Accounts → WhatsApp Accounts → WhatsApp Account Access**.
4. Return to the system user and select **Generate token**. Choose your app and **Never** for expiration if available.
5. Select both `whatsapp_business_messaging` and `whatsapp_business_management`, then generate the token and store it securely.
These [permissions](https://www.postman.com/meta/whatsapp-business-platform/documentation/wlk6lh4/whatsapp-cloud-api) cover messaging, account management, templates, and webhooks. The broader `business_management` permission in Meta's general setup guide is for business portfolio operations; Libredesk does not require it.
App-dashboard user tokens expire and will stop the connection from working. Use a System User token; if it has an expiry date, replace it in Libredesk before it expires.
### App secret
Open **App settings → Basic**, select **Show** next to **App secret**, then copy it.
## Complete Cloud API registration
Adding a number and verifying its SMS or voice code does not complete [Cloud API registration](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/registration). If your number is not already registered, register it through Meta's API after generating the access token above. Libredesk does not register the phone number for you.
Replace the placeholders below with the Graph API version shown in Libredesk's WhatsApp inbox form, your Phone number ID, your System User token, and a six-digit PIN:
```bash theme={null}
curl -X POST 'https://graph.facebook.com/GRAPH_API_VERSION/PHONE_NUMBER_ID/register' \
-H 'Authorization: Bearer SYSTEM_USER_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product":"whatsapp","pin":"SIX_DIGIT_PIN"}'
```
For a number with two-step verification already enabled, use its existing PIN. Otherwise, choose a new six-digit PIN and store it securely. This PIN is separate from the SMS or voice verification code and is not entered in Libredesk. If you have forgotten it, follow Meta's [PIN reset instructions](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/phone-numbers#two-step-verification) before retrying registration.
## Publish the Meta app
Open **App settings → Basic** and add the privacy policy URL. Then open **Publish**, complete any requirements Meta lists, and publish the app.
Some webhooks are not delivered while the Meta app is in Development mode. Publish the app and confirm it is in **Live** mode before testing incoming messages. See Meta's [webhook troubleshooting](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview#troubleshooting).
Business verification is optional for the initial connection. New business portfolios start with:
* A [messaging limit](https://developers.facebook.com/documentation/business-messaging/whatsapp/messaging-limits) of 250 unique customers outside the 24-hour customer-service window per rolling 24 hours, shared across all phone numbers in the portfolio.
* A [registration limit](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/phone-numbers#registered-number-cap) of two business phone numbers across the portfolio.
Business verification is one path to higher limits, subject to Meta's eligibility checks. Start it under **Step 3. Business verification** and check your current messaging limit in **WhatsApp Manager → Account tools → Messaging limits**.
## Connect the number to Libredesk
First, go to **Admin → Settings → General** and set **Root URL** to the public HTTPS address of your Libredesk instance.
Then go to **Admin → Inboxes → New inbox → WhatsApp** and enter:
| Libredesk field | Value |
| ---------------------------- | ------------------------------------------------------ |
| Name | A name that identifies the inbox in Libredesk |
| Phone number ID | The number's ID from API Setup or WhatsApp Manager |
| WhatsApp Business Account ID | The account's ID from API Setup or WhatsApp Manager |
| Access token | The System User token generated above |
| App secret | The secret from **App settings → Basic** |
| API version | Leave the default unless Meta requires another version |
| Webhook verify token | A random secret that you create |
Generate a webhook verify token with:
```bash theme={null}
openssl rand -hex 32
```
Save the inbox. Libredesk checks that the token can access the phone number and that the number belongs to the WhatsApp Business Account, then attempts to register a callback for that account in the background.
## Configure webhooks
Libredesk automatically attempts to subscribe your app to the WhatsApp Business Account and set an account-level callback override for messages. This does not change the app-level callback shown in Meta's dashboard.
Meta's [callback overrides](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/override#supported-webhook-fields) do not apply to template status updates. Configure the app-level callback as well to receive those updates:
1. Open the WhatsApp inbox in Libredesk and copy its **Callback URL** and **Webhook verify token**.
2. In Meta, open **Use cases → Customize → Step 2. Production setup → Configure Webhooks**.
3. Set the app-level **Callback URL** and **Verify token** to the copied values, then select **Verify and save**.
4. Under **Webhook fields**, subscribe to `messages` and `message_template_status_update`.
5. Save the inbox again in Libredesk to retry account-level webhook registration with Meta's configuration in place.
The `messages` field delivers incoming messages and delivery statuses. The `message_template_status_update` field keeps template approval statuses current in Libredesk.
Automatic registration failures are recorded in Libredesk's server logs; saving the inbox can still succeed. If registration fails, check that the Root URL is public HTTPS, Meta can reach the callback, and the System User token has access to the account, then save the inbox again to retry.
## Test the connection
Send a WhatsApp message from another phone to the registered business number. A new conversation should appear in Libredesk. Reply from Libredesk to confirm that outgoing messages work.
If the conversation does not appear, confirm that:
* The Meta app is published and in **Live** mode
* The Libredesk Root URL is a public HTTPS address that Meta can reach
* Libredesk's server logs show successful automatic webhook registration; after correcting a registration failure, save the inbox again
* Both webhook fields above show **Subscribed**
* The **App secret** matches the same Meta app used to generate the token. A wrong secret rejects incoming webhooks even when saving the inbox succeeds; the server logs report `whatsapp webhook signature verification failed`
If replies fail, check that the number has completed Cloud API registration and the token has `whatsapp_business_messaging` permission. If template statuses do not update, check the app-level callback and the `message_template_status_update` subscription.
## Business-initiated messages
Replies are allowed for 24 hours after the customer messages you. After that window, start the conversation with an approved WhatsApp template.
To send business-initiated template messages, return to **Step 2. Production setup** and expand **Add payment to send business-initiated messages**. Add a payment method in Meta's Billing Hub.