Set Up a WhatsApp Channel

Overview

A WhatsApp channel lets your team communicate with customers directly via WhatsApp Business—all within the Virtual-Call UC Client. Incoming WhatsApp messages appear alongside other messaging channels in the UC Client and can be answered in real time. This article describes how to set up a WhatsApp channel in the Cloud PBX.

Prerequisites

• Meta Developer account: A registered account on the Meta for Developers portal.
• Business Portfolio (Meta Business Suite): A Meta Business Suite account linked to a verified business.
• Phone number: A valid phone number not already registered with another WhatsApp account. The number must be able to receive voice calls or SMS for verification.
• Domain name: Your Cloud PBX domain name must not contain underscores (_), as this can interfere with webhook authentication.
• Domain certificate: If your PBX uses a custom domain (not the provider's default domain), a valid domain certificate must be installed.
• Minimum version: The Cloud PBX must be running version 84.23.0.24 or later for all features described in this article to be available.

Limitations

Setup overview

Setting up a WhatsApp channel involves four steps:

1. Create a Meta app on the Meta for Developers portal
2. Obtain authentication credentials via Meta Business Suite
3. Create the WhatsApp channel in the PBX
4. Configure the webhook in the Meta app

Step 1: Create a Meta app

1. Log in to the Meta for Developers portal.
2. Go to My Apps and click Create App.
3. Fill in the app details:
   • Enter an app description (optional).
   • Under Use cases, select Other.
   • Select the app type Business, enter an app name, and select your Business Portfolio.
4. Click Create App.
5. In your new app, add the WhatsApp product by clicking Set up.
6. Register your business phone number under WhatsApp > API Setup. Click Add phone number and follow the verification process (SMS or phone call).
7. Note the following values—you will need them later:
   • Phone Number ID: In the WhatsApp section of the app dashboard under API Setup.
   • App Secret: Under App Settings > Basic.

Step 2: Obtain credentials via Meta Business Suite

For reliable message delivery, create a system user in Meta Business Suite and generate a permanent access token.

1. Log in to Meta Business Suite and navigate to Business Settings.
2. Navigate to Users > System Users and create a new system user with the Admin role.
3. Assign the Meta app created in Step 1 to this system user with Full Control. Click Assign Assets, select Apps, check your app, and enable Full Control.
4. Under Accounts > WhatsApp Accounts, add the system user to your WhatsApp Business account. Click Assign people and select the system user with Admin permission.
5. Generate an access token for the system user. Click Generate new token, select your app, and enable the following permissions:
   • whatsapp_business_messaging
   • whatsapp_business_management
6. Copy the generated access token—you will need it in Step 3.
7. Note your WhatsApp Business Account ID—found under Accounts > WhatsApp Accounts in Meta Business Suite.

Step 3: Create the WhatsApp channel in the PBX

1. Log in to the Cloud PBX admin portal.
2. Navigate to Messaging > Message Channel.
3. Click Add and select WhatsApp.
4. Configure the Authentication tab:
   • Name: A descriptive name (e.g., "WhatsApp Support" or "WhatsApp Sales").
   • Webhook URL: Generated automatically. Copy it—you will need it in Step 4.
   • Verify Token: Generated automatically. Copy it—you will need it in Step 4.
   • Access Token: Paste the permanent access token from Step 2.
   • App Secret: Paste the App Secret from Step 1.

5. Configure the Message Settings tab:
   • Phone Number: Enter the WhatsApp phone number in E.164 format (e.g., +4917612345678).
   • Phone Number ID: Enter the Phone Number ID from Step 1.
   • WhatsApp Business Account ID: Enter the Account ID from Step 2.
   • Destination for incoming messages: Select where incoming WhatsApp messages are routed:
     • Extension: Messages go directly to a specific extension.
     • Message queue: Messages go to a queue where multiple agents can handle them.
   • Eligible extensions: Select which extensions may send messages through this channel.
   • Auto-close session: Enable this option and set a timeout in days to automatically end inactive sessions.
   • Allow duplicate active sessions: Determines whether a new agent can create a session if an active session with the same contact already exists.
6. Click Save.

Step 4: Configure the webhook in the Meta app

For the PBX to receive incoming WhatsApp messages, you must set up a webhook in your Meta app:

1. Log in to the Meta for Developers portal and go to My Apps.
2. Open your app and navigate to WhatsApp > Configuration.
3. In the Webhook section:
   • Paste the Callback URL you copied from the PBX in Step 3.
   • Paste the Verify Token you copied in Step 3.
   • Click Verify and Save.
4. In the Webhook Fields section, subscribe to the messages field.

Result

After successful setup, the WhatsApp channel appears in the channel list under Messaging > Message Channel with a green status icon. The PBX automatically tracks the number of messages sent and received.

WhatsApp message templates

The PBX automatically synchronizes approved message templates from your WhatsApp Business account. Templates are required to start conversations outside the 24-hour customer service window—for example, for appointment confirmations, order notifications, or promotional messages.

To view synchronized templates, navigate to Messaging > Message Channel and click the template icon next to the WhatsApp channel. Click Refresh to manually update the template list (the system also updates automatically once a day).

Enhanced message interaction

Starting with version 84.24.0.73 (V25.2-GA), additional message interaction features are available for the WhatsApp channel in the Virtual-Call UC Client:

• Quote Reply: Messages (text, files, images, emojis, links) can be replied to as direct quotes, keeping the conversation context clear even when multiple topics are discussed at once.
• Read Receipts: A status icon indicates whether a sent message was delivered or read. This feature is disabled by default and must be enabled under PBX Settings > Preferences > Read Receipt. The UC Mobile Client requires at least iOS 5.29.14 or Android 5.29.12.
• Emoji Reactions: Messages can be acknowledged with an emoji reaction without sending a separate reply.

Important notes

• 24-hour window: WhatsApp requires businesses to reply within 24 hours of the customer's last message. After this window expires, the customer can only be contacted using an approved message template.
• Access token validity: Always use a permanent access token from a system user in Meta Business Suite. Temporary tokens from the Meta for Developers portal expire after 24 hours and cause the PBX to stop receiving messages.
• Business verification: Meta requires verification of your business before certain WhatsApp Business features and higher messaging limits become available. Complete verification in Meta Business Suite.
• MMS file size: Multimedia messages are limited to a maximum of 100 MB. Files are retained for 72 hours.
• IP access for multimedia: If you have configured IP access security rules, make sure access from Meta servers is allowed—otherwise multimedia files cannot be delivered.

Troubleshooting

Phone number status shows "Pending"

After registering a phone number, its status may temporarily show as Pending while the registration is being reviewed. This usually takes up to 24 hours. If the status persists longer, check the following:

• Confirm that the phone number was successfully verified (via SMS or call) and is not already linked to another WhatsApp account.
• In the Meta for Developers portal, check under WhatsApp > API Setup whether additional verification steps are required.
• Contact Virtual-Call Support if the status remains "Pending" after 48 hours.