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
Enter the app details
Open Meta for Developers, select My Apps → Create App, then enter an app name and contact email.
Choose the WhatsApp use case
Select Connect with customers through WhatsApp, then select Next.
Choose the WhatsApp use case when creating the app
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.
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.
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:
- Enter the legal business name, website or social profile, and country.
- Create the WhatsApp Business profile, including its customer-facing display name.
- Enter the phone number and choose SMS or voice verification.
- 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'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.
The WhatsApp Business Account ID in the account selector
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.
- Open Meta Business Settings and select the business portfolio that owns your app and WhatsApp Business Account.
- Go to Users → System Users, select Add, and create a system user with the Admin role.
- 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.
- Return to the system user and select Generate token. Choose your app and Never for expiration if available.
- Select both
whatsapp_business_messagingandwhatsapp_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 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 → 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 |
| Reopen window (hours) | A reply within this many hours of resolving reopens the conversation. 0 always starts a new one. Default 48 |
| 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
Click Create. libredesk checks that the token can access the phone number and that the number belongs to the WhatsApp Business Account. libredesk then attempts to register a callback for that account in the background.
When CSAT Surveys is on, libredesk submits the CSAT survey template to Meta when you save the inbox. Surveys are sent with it once Meta approves it.
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:
- Open the WhatsApp inbox in libredesk and copy its Callback URL and Webhook verify token.
- In Meta, open Use cases → Customize → Step 2. Production setup → Configure Webhooks.
- Set the app-level Callback URL and Verify token to the copied values, then select Verify and save.
- Under Webhook fields, subscribe to
messagesandmessage_template_status_update. - Save the inbox again in libredesk to retry account-level webhook registration with Meta's configuration in place.
Enter the libredesk callback URL and verify token
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.
The 24-hour reply window
Agents can send free-form replies and attachments for 24 hours after the contact's latest message. After that, only approved templates can be sent, and the reply box shows a Send template button. Private notes work at any time. The window opens again when the contact replies.
Business-initiated messages
Send an approved template to start a new conversation or to message a contact whose reply window is closed.
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.
Templates
Manage templates under Admin → WhatsApp templates. Each WhatsApp inbox has its own template list.
Click New template, fill in the form, then click Submit to Meta. The template stays PENDING until Meta reviews it, and only APPROVED templates can be sent. If Meta rejects it, hover over the status to see the reason, then edit and resubmit.
Sync from Meta imports templates you created in WhatsApp Manager. libredesk also syncs every 6 hours.
libredesk can send templates with a text header or no header. Templates with image, video, or document headers can be synced but not sent.
To send a template in a conversation, click Send template in the reply box, pick a template, fill in its values, and click Send.
Start a WhatsApp conversation
Open New conversation, select the WhatsApp tab, choose the inbox, and enter the contact's phone number. A new WhatsApp conversation always starts with an approved template.
A contact can have one open WhatsApp conversation per inbox. If one exists, the form links to it.
Message types
Incoming text, images, video, audio, voice notes, documents, stickers, locations, contact cards, and button replies appear in the conversation. Reactions are ignored.
Agents can send text and attachments. WhatsApp allows one file per message, so libredesk sends each attachment as its own message. WebP images are not supported.
Delivery and read status
Outgoing messages show sent, delivered, read, or failed. Hover over a failed message to see the reason. When an agent opens a conversation, the contact sees a read receipt.
Contacts
Replies go to the contact's WhatsApp number. Editing the contact's phone number does not change where replies go.
To message an existing contact who has no WhatsApp number, such as an email contact, libredesk uses the phone number and country code saved on the contact.
Multiple phone numbers
Create one WhatsApp inbox per phone number. Inboxes can share a WhatsApp Business Account.
Permissions
| Action | Permission |
|---|---|
| Create, edit, delete, and sync templates | inboxes:manage |
| Send replies and templates in a conversation | messages:write |
| Start a WhatsApp conversation | conversations:write |
| Start a WhatsApp conversation with a number that has no contact | conversations:write and contacts:write |
