Skip to main content
LibredeskLibredesk
Search

WhatsApp

Connect a WhatsApp number through Meta's Cloud API

Abhinav Raut · Last updated

Note:

WhatsApp support is still in development and is not available in any released version yet. This guide is published ahead of the release. You cannot set up a WhatsApp inbox until the feature ships.

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

Warning:

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

1. Enter the app details

Open Meta for Developers, select My Apps → Create App, then enter an app name and contact email.

2. Choose the WhatsApp use case

Select Connect with customers through WhatsApp, then select Next.

Meta app creation option named Connect with customers through WhatsApp

Choose the WhatsApp use case when creating the app

3. Connect the business portfolio

Select the business portfolio that will own the WhatsApp Business Account. Review the requirements, confirm the app details, then select Create app.

4. Open production setup

In the app dashboard, go to Use cases → Customize next to Connect with customers through WhatsApp. Under Basic setup, open Step 2. Production setup.

Meta production setup with Webhooks, phone number, payment, and messaging tasks

The production setup tasks in Meta

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 before showing them in chat headers. If yours is rejected, review Meta's naming guidelines and update it in WhatsApp Manager.

Meta phone number wizard with Business information, WhatsApp Business Profile, Add number, and Verify number stages

Meta's phone number registration wizard

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 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.

Example WhatsApp Business Account with its numeric ID

The WhatsApp Business Account ID in the account selector

Example registered WhatsApp number with its Phone number ID

The Phone number ID after selecting a registered number

Copy the Meta credentials

System User access token

Use a System User access token for this connection.

  1. Open Meta Business 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 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.

Warning:

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. 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:

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 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.

Meta Publish page showing the privacy policy requirement and WhatsApp use case

Meta requires a privacy policy URL before publishing

Warning:

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.

Business verification is optional for the initial connection. New business portfolios start with:

  • A messaging limit 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 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:

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 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.

Meta webhook configuration fields for Callback URL and Verify token

Enter the Libredesk callback URL and verify token

Meta webhook fields for messages and message template status updates

The two webhook fields required by Libredesk

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. openssl rand -hex 32

Was this article helpful?