# Set up a WhatsApp Channel A WhatsApp channel links your WhatsApp Business phone number to Cloud Voice, letting agents handle customer WhatsApp conversations directly in the Cloud Voice App instead of a separate WhatsApp client. This page walks you through creating the required Meta app, collecting the credentials Cloud Voice needs, and connecting the channel end to end. ## Requirements Confirm that both sides of the integration are ready before you begin. ### Cloud Voice PBX Your Cloud Voice PBX (private branch exchange: the hosted phone system that routes your calls and messages) must meet the following requirements. - **Firmware**: Version `84.23.0.24` or later. - **Domain name**: The PBX domain name must not contain underscore (`_`) characters. Because of a restriction on the third-party platform, an underscore causes the messaging channel to fail authentication or stop receiving messages. - **Domain certificate**: A valid domain certificate must be installed on the PBX. :::note If your Cloud PBX uses a custom root domain rather than one of the standard domains provided with Cloud Voice, install a valid domain certificate first. Otherwise the messaging channel will fail authentication or be unable to receive messages. ::: ### WhatsApp - **Product**: WhatsApp Business Platform. - **Accounts**: - A [Meta Developer account](https://developers.facebook.com/docs/development/register). :::note A single Meta Developer account is enough to create multiple Meta apps for WhatsApp channel integration, and there is no limit to the number of WhatsApp channels you can add to the PBX. ::: - A [Business Manager account (Business Portfolio)](https://www.facebook.com/business/help/1710077379203657?id=180505742745347). :::note After you create the Business Manager account, complete Meta's [business verification](https://www.facebook.com/business/help/2058515294227817?id=180505742745347). ::: - **Phone number**: A phone number that is valid and available for messaging. You can check a number's status on the [Meta Business Suite portal](https://business.facebook.com/) under **Account > WhatsApp accounts > WhatsApp Manager > Account tools > Phone numbers**. :::note Confirm the number's status shows as connected and available. A number still showing **Pending** in WhatsApp Manager is not ready for messaging yet, so resolve it on the Meta side before you continue. ::: ![Cloud Voice, WhatsApp Manager phone numbers list showing an available number and its status](/images/pbx/whatsapp-available-number-1.png) ## Limitations Keep the following constraints of the WhatsApp messaging channel in mind. | Item | Description | |------|-------------| | Message type | Text messages and multimedia messages are supported. WhatsApp determines which multimedia types are allowed; see [WhatsApp supported media types](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types). | | Messaging mechanism | Agents can receive and reply to inbound messages, and can also start a conversation proactively using a WhatsApp message template. | | Message sending rate | Up to **80** messages per second. | | File size | Up to **100 MB** per file. | | File retention period | Files are retained for **72 hours**. | :::caution When you send a multimedia message such as an image, WhatsApp downloads the file from a link that the PBX provides. If you use an Allowed Country/Region IP access protection rule, make sure the country where the WhatsApp server is located is permitted, or the file transfer will fail. ::: ## Integration workflow Setting up a WhatsApp channel takes four steps: 1. [Create a Meta app](#step-1-create-a-meta-app) on the Meta for Developers portal. 2. [Collect credentials](#step-2-collect-credentials-on-the-meta-business-suite-portal) on the Meta Business Suite portal. 3. [Create and configure the channel](#step-3-create-and-configure-the-channel-on-cloud-voice) on Cloud Voice. 4. [Configure the webhook](#step-4-configure-the-webhook-in-the-meta-app) in the Meta app. ## Step 1. Create a Meta app Create a Business-type Meta app, attach your WhatsApp phone number, and record the **phone number ID** and **app secret**. You will enter both values on Cloud Voice later. 1. Sign in to the [Meta for Developers portal](https://developers.facebook.com) with your Meta Developer account and open **My Apps** from the top menu. ![Meta for Developers top menu with the My Apps option highlighted](/images/pbx/meta-for-developers-myapp-1.png) 2. Create an app of the **Business** type. 1. Click **Create App**. ![App type selection page with the Create App button](/images/pbx/wa-create-app.png) 2. Fill in the app settings. In the **Business Portfolio** field, choose your Business Account so the app is tied to your business, apps that require [advanced access for permissions](https://developers.facebook.com/docs/graph-api/overview/access-levels/) must be linked to a verified business entity. ![Cloud Voice, app details form with the app name and Business Portfolio fields completed](/images/pbx/create-whatsapp-app-1.png) 3. On the **Add products to your app** page, scroll to **WhatsApp** and click **Set up**. You are taken to the WhatsApp product's **Quickstart** page. ![Add products page with the Set up button next to the WhatsApp product](/images/pbx/add-whatsapp-to-product.png) 4. In the left navigation pane, go to **WhatsApp > API Setup > Send and receive messages**, then do the following: 1. From the **From** drop-down list, click **Add phone number** and add your WhatsApp phone number for messaging. ![From drop-down list with the Add phone number option](/images/pbx/add-whatsapp-phone-number-1.png) 2. Select the added number in the list and note its **Phone number ID**: you will need it on the PBX. ![Selected phone number with its phone number ID displayed](/images/pbx/whatsapp-phone-number-1.png) :::caution If you are using the test number that WhatsApp provides for demos or testing, add the recipients' phone numbers in the **To** drop-down list. Otherwise messages may fail to send. ![To drop-down list where a recipient number is added](/images/pbx/add-recepient-number.png) ::: 5. In the left navigation pane, go to **App settings > Basic** and note the **App secret**. You will need it on the PBX later. ![Cloud Voice, Basic app settings page with the App secret field](/images/pbx/app-secret.png) ## Step 2. Collect credentials on the Meta Business Suite portal On the Meta Business Suite portal, create a system user, grant it access to the [Meta app from Step 1](#step-1-create-a-meta-app), and generate an **access token** for it. You also copy the **WhatsApp Business Account ID**, which Cloud Voice uses to pull in the account's message templates. :::caution Use the access token generated in Meta Business Suite rather than the one from the Meta for Developers portal. The Meta for Developers token is temporary and can lead to missed messages once it expires. ::: 1. From the top-left corner of the [Meta for Developers portal](https://developers.facebook.com), go to **App Dashboard > Business settings**. You are redirected to the **Business settings** page of the [Meta Business Suite portal](https://business.facebook.com/). ![App Dashboard menu with the Business settings link](/images/pbx/go-to-business-settings-whatsapp.png) 2. Go to **Users > System users** and create a system user with app permissions. 1. Click **Add** and create a system user with the **Admin** role. ![System users page with the Add dialog for a new admin user](/images/pbx/whatsapp-create-a-system-users-1.png) 2. Select the new user, click **Add assets**, and grant the user full control of the app. ![Cloud Voice, Add assets panel granting full control of the app to the system user](/images/pbx/assign-assets-to-whatsapp-user-1.png) 3. Go to **Accounts > WhatsApp Accounts**, add the system user to your WhatsApp Business account, and grant full control. ![Cloud Voice, WhatsApp account people settings assigning full control to the system user](/images/pbx/add-people-to-whatsapp-business-account-1.png) 4. Return to **Users > System users** and generate an access token with the `whatsapp_business_messaging` and `whatsapp_business_management` permissions enabled. ![Token generation dialog with the two WhatsApp permissions selected](/images/pbx/create-an-acess-token-for-whatsapp-application-1.png) :::note The token expires after 60 days by default. Set expiration to **Never** if you do not want it to expire. ::: The generated token appears in a pop-up window. :::caution Copy and save the access token before closing the pop-up. It is shown only once. ::: ![Pop-up window displaying the generated system user access token](/images/pbx/system-user-access-token-1.png) 5. Go to **Accounts > WhatsApp accounts**, open your WhatsApp Business Account, and copy the account ID. ![WhatsApp Business Account details with the account ID](/images/pbx/obtain-waba-id.png) ## Step 3. Create and configure the channel on Cloud Voice Create a WhatsApp channel on the PBX and populate it with the values you gathered in the previous steps so Cloud Voice can connect to WhatsApp for messaging. 1. Sign in to the PBX web portal and go to **Messaging > Message Channel**. 2. Click **Add** and select **WhatsApp**. 3. On the **Authentication** tab, enter the WhatsApp authentication details. ![Cloud Voice, WhatsApp channel Authentication tab with name, webhook, and token fields](/images/pbx/whatsapp-auth-setting-pce.png) - **Name**: A name that helps you identify the channel. - **Webhook URL**: Note this value down, you will paste it into WhatsApp in Step 4. - **Verify Token**: Note this value down, you will paste it into WhatsApp in Step 4. - **Access Token**: Paste the access token you generated in Meta Business Suite ([Step 2](#step-2-collect-credentials-on-the-meta-business-suite-portal)). - **App Secret**: Paste the app secret you copied from the Meta for Developers portal ([Step 1](#step-1-create-a-meta-app)). 4. On the **Messaging Settings** tab, configure the channel. 1. Enter the WhatsApp phone number details. ![Messaging Settings tab with phone number and phone number ID fields](/images/pbx/wa-phonenumber.png) - **Phone Number**: The WhatsApp phone number in E.164 format (`[+][country code][phone number]`), for example `+15559871234`. - **Phone Number ID**: The phone number ID you recorded in Step 1. 2. In the **WhatsApp Business Account ID** field, paste the account ID you copied in Step 2. The PBX then automatically syncs the message templates tied to that WhatsApp account into the channel. ![WhatsApp Business Account ID field on the channel form](/images/pbx/waba-id.png) 3. From the **Destination for Inbound Messaging** drop-down list, choose where inbound messages to this number are routed. ![Destination for Inbound Messaging drop-down list](/images/pbx/wa-destination.png) | Option | Description | |--------|-------------| | Extension | Choose an extension from the **Extension** drop-down list. Only that extension user receives inbound messages from the number. | | Message Queue | Choose a queue from the **Message Queue** drop-down list. Every agent in the queue is notified of new inbound sessions, but once an agent picks up a session, only that agent receives and replies to the follow-up messages in it. | | Third-Party Message Analytics Platform (Transmitted via API) | Inbound messages are automatically forwarded to a third-party message analytics platform over the API (application programming interface, a way for two systems to exchange data automatically) for advanced processing. This requires that your PBX is already integrated with the analytics platform via the API. Once integrated, incoming messages are relayed automatically, you can watch for the **New Message Notification** API event, and the PBX's Message API suite is available for deeper interaction. | 4. In the **Extensions Allowed to Create Messaging Sessions** section, select the extensions that may start a messaging session with customers. ![Extension selection list for allowing outbound session creation](/images/pbx/wa-initiator.png) 5. Configure the session settings as needed. | Setting | Description | |---------|-------------| | Close Session Automatically | To have the system close sessions that have been idle for a set time, select the checkbox and enter the number of days in **Session Timeout (Days)**. | | Allow the Creation of Duplicate Active Sessions | Select the checkbox to permit a new session even when an active session already exists between the same sender and receiver. When an agent tries to create such a session in the Cloud Voice App, a prompt appears; if the agent continues, the existing session is removed from the previous handler's list and taken over by the new agent, along with the full chat history. | ![Session Timeout field for automatically closing inactive sessions](/images/pbx/auto-close.png) 5. Click **Save**. ## Step 4. Configure the webhook in the Meta app Set up a webhook for your Meta app so it delivers real-time message events, allowing the PBX to process incoming WhatsApp messages. 1. Sign in to the [Meta for Developers portal](https://developers.facebook.com) with your Meta Developer account and open **My Apps** from the top menu. ![Meta for Developers top menu with the My Apps option](/images/pbx/meta-for-developers-myapp-1.png) 2. Click your app to open its details page. ![App list with the target app selected](/images/pbx/select-app.png) 3. Go to **WhatsApp > Configuration** to set the messaging webhook and subscribe to the webhook field so the PBX is notified when WhatsApp messages arrive. 1. Paste the **Webhook URL** and **Verify Token** you noted from the PBX in Step 3. ![Cloud Voice, WhatsApp webhook configuration with the callback URL and verify token entered](/images/pbx/wahtsapp-verity-webhook-pce-1.png) 2. In the **Webhook fields** section, subscribe to the **messages** field. ![Webhook fields list with the messages field subscribed](/images/pbx/webhook-fields-1.png) ## Result - The channel's **Status** shows a green indicator, confirming that the WhatsApp channel was created successfully. ![Message Channel list showing the WhatsApp channel with an active status](/images/pbx/whatsapp-channel-ok.png) - The PBX automatically counts the messages sent and received on the channel. The **Total** column shows all sent messages, including both successful and failed ones. :::tip Use the time filter to narrow the statistics to a specific period. ::: ![WhatsApp channel message report with sent and received totals](/images/pbx/wahtsapp-message-report.png) ## What to do next Send a text message to the WhatsApp number and confirm that the assigned agent receives it in the Cloud Voice App.