WhatsApp

WhatsApp is connected through Meta's WhatsApp Cloud API: you create an app in Meta, register a business phone number there, and enter the number's IDs and keys in a WhatsApp inbox in your panel. The channel is marked Beta in the panel.

What you need before you start

• A Facebook account that can manage a Meta business portfolio, or is allowed to create one.
• A phone number where you can get a code by SMS or by voice call. Take a number that is not registered in the WhatsApp or WhatsApp Business app: to move such a number you would have to delete its account in the app, and that deletes its chat history.
• A public page with your privacy policy. Meta asks for its address before the app can be published.

A public HTTPS address for the webhook is also required, and you already have it: your site address. There is nothing to set up for it on your side.

Create the Meta app

1. Go to Meta for Developers (developers.facebook.com/apps), choose "My Apps", then "Create App", and give the app a name and a contact email.
2. As the use case, pick "Connect with customers through WhatsApp" and press "Next".
3. Choose the business portfolio that should own the WhatsApp Business Account, read Meta's requirements, confirm the details and press "Create app".
4. In the app dashboard open "Use cases" and press "Customize" next to the WhatsApp use case. Under "Basic setup" you find "Step 2. Production setup", which you need for the next steps.

Register the phone number

In "Step 2. Production setup", open "Register your WhatsApp phone number" and press "Add new number". Meta then takes you through four stages:

1. your business details: legal name, website or social media page, country;
2. the WhatsApp Business profile, including the display name your customers will see;
3. the phone number, and whether the code comes by SMS or by voice call;
4. the code Meta sends you.

Meta checks display names before it shows them at the top of chats. If your name is turned down, read Meta's rules for display names and change the name in WhatsApp Manager.

Find the two IDs

The inbox needs two IDs: Phone number ID and WhatsApp Business Account ID.

• In the app dashboard, if you see an "API Setup" panel, pick your business number there (not the test number Meta offers) and copy both IDs.
• Otherwise open WhatsApp Manager (business.facebook.com/latest/whatsapp_manager) and select your WhatsApp Business Account. The account ID is shown in the account selector at the top. For the phone number ID, open "Account tools", "Phone numbers" and click your number.

Both IDs are long numbers issued by Meta. The phone number itself, the app ID or the business portfolio ID do not work in their place, and the panel checks on saving that the number belongs to the account.

Create a permanent access token

The panel talks to Meta with the access token of a system user, which does not run out the way a personal token does.

1. Open Meta Business Settings (business.facebook.com/settings) and pick the portfolio that owns both your app and your WhatsApp Business Account.
2. Under "Users", "System Users", press "Add" and set up a system user, giving it the "Admin" role.
3. Press "Assign assets", choose your app and give it "Full control", "Manage app". Make sure the system user can also reach the WhatsApp Business Account: "Accounts", "WhatsApp Accounts", "WhatsApp Account Access".
4. Go back to the system user and press "Generate token". Pick your app and, when Meta offers it, "Never" as the expiry.
5. Tick whatsapp_business_messaging and whatsapp_business_management, generate the token and keep it in a safe place.

These two permissions are enough for messages, account management, templates and webhooks. The broader business_management permission that some Meta guides mention is not needed.

A token generated on the app dashboard expires, as the hint under Access token says after 24 hours, and the channel stops working then. If your system user token has an expiry date, replace it in the panel before that date. When Meta rejects the saved token, the inbox form shows a red notice until you paste a new token and save.

Copy the app secret

In the Meta app open "App settings", "Basic", press "Show" next to "App secret" and copy the value. The panel uses it to check that incoming messages really come from Meta.

Register the number with the Cloud API

Verifying the number with the SMS or voice code does not complete its registration for the Cloud API, and the panel does not register numbers for you. Unless your number is registered already, send this request once from any computer with curl, after you have the access token:

curl -X POST 'https://graph.facebook.com/API_VERSION/YOUR_PHONE_NUMBER_ID/register' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data '{"messaging_product":"whatsapp","pin":"123456"}'

Put in the value of API version from the WhatsApp inbox form (v26.0 unless you changed it), your phone number ID, your token and a six-digit PIN.

• If the number already has two-step verification, enter that PIN.
• If not, make up a six-digit PIN and write it down.
• The PIN is not the SMS or voice code, and you never enter it in the panel.
• If you forgot the PIN, reset it following Meta's two-step verification help, then send the request again.

Publish the app

In "App settings", "Basic", enter the address of your privacy policy. Then open "Publish", do whatever Meta still lists there, and publish the app. Check that the app is in "Live" mode before you test: while it is in development mode, Meta holds back some webhooks.

You can start without business verification. A new business portfolio begins with limits that all its numbers share:

• business-initiated messages to at most 250 different customers outside the 24-hour window in any 24 hours;
• at most two registered business phone numbers.

Business verification is one way to get higher limits, if Meta considers your business eligible. You start it under "Step 3. Business verification" and see your current limit in WhatsApp Manager under "Account tools", "Messaging limits".

Add the WhatsApp inbox

Open Admin > Inboxes > New inbox and choose WhatsApp. Admin is the shield, the last icon of the upper group in the left icon bar (tooltip Admin). Inboxes is the item under Channel in the admin menu, not the Inboxes icon at the top of the bar.

field	what to enter
Name	how the inbox is called in the panel, for example WhatsApp
Phone number ID	the phone number ID from Meta
WhatsApp Business Account ID	the account ID from Meta
Access token	the system user token
App secret	the app secret
API version	keep v26.0 unless Meta asks for another version
Webhook verify token	a long random string that you make up

For the verify token, any long random string will do, for example from a password generator or from openssl rand -hex 32 in a terminal. Keep a copy: after saving, the form shows this field masked, and you need the value again in Meta.

Leave Root URL under Admin > General as it is. It already holds your site address, and the webhook address is built from it.

Press Create. The panel checks that the token can reach the phone number and that the number belongs to the account; if the check fails, you see "Meta rejected these credentials" followed by the reason. After saving, the panel subscribes your app to the WhatsApp Business Account in the background and points the account's message callback at this inbox.

The form also has Enabled, which switches the inbox on and off, and Prompt to tag before replying, which warns agents before they reply in a conversation without tags.

Set the webhook in Meta

The callback that the panel sets for the account delivers messages, but Meta does not send template status updates through it. Set the webhook on the app level as well:

1. Open the WhatsApp inbox in the panel and copy its Callback URL. It appears after the first save and looks like https://<your site address>/webhooks/whatsapp/<inbox number>. Take the verify token from your own copy.
2. In the Meta app go to "Use cases", "Customize", "Step 2. Production setup", "Configure Webhooks", and enter the callback URL and your verify token there. Press "Verify and save".
3. In "Webhook fields", turn on the subscriptions for messages and message_template_status_update.
4. Back in the panel, save the inbox once more. The panel then repeats the account-level registration with Meta's settings in place.

messages brings incoming messages and delivery statuses. message_template_status_update keeps the approval status of your templates up to date in the panel. The panel never changes the app-level webhook in Meta's dashboard: if your site address changes later, the panel moves the account-level callback by itself, but you update the app-level Callback URL in Meta by hand.

Route the inbox to the assistant

The assistant answers only conversations assigned to it, and an automation rule makes that assignment for each inbox. Inboxes that existed when your site was set up got their rule then. A WhatsApp inbox you add later needs the rule described in Routing a new channel to the assistant: add it yourself right after creating the inbox, or write to support@epavdesk.com and the rule appears at the next system update. Until then, WhatsApp conversations wait in the list for an agent, although the AI notice still goes out.

Test the connection

From another phone, send a WhatsApp message to your business number. A new conversation should appear in the panel. Reply to it from the panel to check that sending works too.

If no conversation appears, check that:

• the Meta app is published and in "Live" mode;
• both webhook fields show "Subscribed" in Meta;
• the App secret comes from the same Meta app as the access token. With a wrong secret the inbox still saves, but the panel rejects every incoming message as not coming from Meta;
• the account-level registration went through. You cannot see the server log of your site, so after fixing the Meta settings save the inbox again, and if messages still do not arrive, write to support@epavdesk.com and we check the log for you.

If your replies fail, check that the number finished the Cloud API registration and that the token has whatsapp_business_messaging. If template statuses do not change in the panel, check the app-level webhook and the message_template_status_update subscription.

The 24-hour window and templates

For 24 hours after the customer's last message you can reply without a template, by the assistant or by an agent. These replies are not free: since 1 October 2026 Meta charges for each of them, per message at the rate of the recipient's country, the same as utility templates. Replies in the 72-hour window that a Click to WhatsApp ad opens stay free. Meta bills you directly. Current rates and any free allowance are in Meta's pricing documentation and in your Billing Hub.

During the last four hours of that window, the reply box shows "Reply window closes in ...", and once it has closed, "24-hour reply window closed" with a Send template button: from then on only templates approved by Meta can be sent.

• Templates are managed in Admin > WhatsApp templates. Create one with New template and send it for approval with Submit to Meta, or load templates you already approved in Meta with Sync from Meta.
• In a conversation, Send template in the reply box sends an approved template.
• To write to someone first, press New conversation in the sidebar above My Inbox, open the WhatsApp tab, and choose the inbox, the contact or phone number, and the template.

Paid messages, both the replies above and the templates that start conversations from your side, need a payment method in Meta: in "Step 2. Production setup" open "Add payment to send business-initiated messages" and add it in Meta's Billing Hub.

When Meta does not deliver a message, the message gets a red mark, and hovering it shows the reason in your panel language: for example a payment method problem in Billing Hub, more than 24 hours since the customer's last message (only a template can be sent then), a number without WhatsApp, a spam limit on your number or a restricted account. Other reasons show Meta's own text. When the reason is the payment method (Meta code 131042), the conversation also gets a private note, and users who can manage inboxes get one notification a day per inbox, in the panel, by push and by email. Until a payment method is in place, no reply of the assistant or the agents arrives; afterwards, send the failed replies again by hand.

The AI notice

Every new WhatsApp conversation that a rule hands to the assistant starts with the notice that the customer is talking to an AI: "You are chatting with an AI assistant. Ask for a human at any time and I will pass you on." With AI chat without agents on, only the first sentence is sent. The notice comes in the language the assistant answers in, as far as the panel has a translation for it: usually the language of the customer's first message, or always the same language if the assistant's Languages list holds just one (see Assistant settings). The WhatsApp form has no greeting field, so the notice is the whole first message.

While the assistant answers

• The customer sees their message marked as read and the typing indicator while the assistant prepares an answer.
• When the assistant offers the customer one to three short options, they appear as tap buttons under its message, and a tap comes back as the customer's reply. WhatsApp takes buttons only with labels of up to 20 characters under a message of up to 1024 characters; otherwise the message goes out as plain text without buttons.
• When the assistant asks whether the answer helped, the question comes with the buttons Yes, thanks and I need more help in the language of the answer, within the same limits.
• WhatsApp does not take messages longer than 4096 characters and does not show tables, so a long answer arrives in several parts and a table as lines of text.
• Voice messages are turned into text for the assistant and the agent: see Voice messages.

AI chat without agents

Turn on AI chat without agents in the WhatsApp inbox when nobody but the bot answers there. The assistant then never hands a conversation to agents: when the knowledge base has no answer, it says so and asks for another question. More in AI chat without agents.

When a conversation continues

While a conversation is open, everything the customer writes goes into it. After it is resolved, Reopen window (hours) decides what happens to the next message: within that many hours the same conversation reopens, later a new one starts. A new inbox starts with 48 hours, and 0 means the next message always starts a new conversation.

Customer ratings (CSAT)

With CSAT Surveys on, the form shows the CSAT survey template: Message, Button text and Language. The panel registers this text with Meta as a template. Once Meta approves it, a resolved conversation gets the survey even when the 24-hour window has already closed. Until then the panel sends the survey text with a rating link, but only while the window is open. If neither is possible, the conversation gets the note "CSAT survey was not sent. The WhatsApp reply window is closed." A conversation gets one survey at most.

Files

WhatsApp takes one file per message. The size limits depend on the type: images up to 5 MB, video and audio up to 16 MB, documents up to 100 MB.

Identity checks

A WhatsApp number proves only that the person owns the phone, not who they are in your own systems. The assistant therefore never treats a WhatsApp contact as signed in: custom tools marked Require verified contact run only after the person confirms an email address with a one-time code that the assistant sends by email. The code is sent with your own mail set up in Admin > Notifications > Email, or by the EPAV mailbox when it is switched on in the cabinet: the mailbox sends customers these codes and nothing else. See Custom tools.

Keys stay hidden

The access token, the app secret and the verify token are stored encrypted and shown masked in the form. When you save the form with a masked value unchanged, the stored value stays. To replace a key, paste the new value over the masked one and save.