Set up a WhatsApp Channel

This topic describes how to set up a WhatsApp channel on Yeastar P-Series PBX System, so that agents in your business can receive and reply to WhatsApp messages from customers on their Linkus UC Clients.

Requirements

Make sure the following resources are ready.
Platform Requirement
Yeastar PBX
  • Firmware: Version 37.23.0.24 or later.
  • Plan: Enterprise Plan (EP) or Ultimate Plan (UP)
  • Domain Name: PBX can be remotely accessed via a domain name.
    Note:
    • Due to the limitation of the third-party platform, the domain name must NOT contain underscore character(s), otherwise the messaging channel will encounter authentication failure, or will fail to receive messages.
    • If you use a self-managed domain name, make sure you have installed a valid domain certificate for the domain name, otherwise the messaging channel will encounter authentication failure, or will fail to receive messages.
    For more information about the domain configuration, see the following topics:
WhatsApp
  • Product: WhatsApp Business Platform

Limitations

Learn about the limitations of WhatsApp messaging channel.

Item Description
Message type Supports text messages and multimedia messages, where the multimedia message types are determined by WhatsApp. For more information, see WhatsApp supported media types.
Important: When sending multimedia messages (such as images), WhatsApp downloads the file from a link provided by the PBX. Therefore, if you have set Allowed Country/Region IP Access Protection rule, make sure that you have allowed the IP access from the country where the WhatsApp server is located, otherwise the file transmission would fail.
Messaging mechanism You can receive and reply to customers' inbound messages, or proactively initiate a messaging session using a WhatsApp message template.
Message sending rate Supports to send up to 80 messages per second.
File size Supports to send a file with a maximum size of 100 MB.
File retention period Files can be retained for 72 hours.

Procedure

Video Tutorial

Step 1. Create a Meta app on 'Meta for Developers' portal

On 'Meta for Developers' portal, create a Meta app on the Meta for Developers portal, add phone number to the app, and obtain a phone number ID as well as the app secret, which is required later when configuring the WhatsApp channel on the PBX.

  1. Log in to 'Meta for Developers' portal with your Meta Developer account, then go to My Apps from the top menu.

  2. Create an app of the Business type.
    1. Click Create App.

    2. Complete the app settings.
      Note: In the Business Portfolio field, select your Business Account to connect the app with your business, as apps that need advanced access for permissions must be connected to a verified business entity.

  3. In the Available products section, scroll down to find WhatsApp and click Set up.

    You are redirected to the configuration page of the WhatsApp product.

  4. Optional: At the left navigation bar, go to WhatApp > Step 1. Try it out, test the message sending using the test number.
    1. Generate a temporary access token.
      Note: The access token is valid for 24 hours only and can not be used in production.

    2. Add a recipient number to receive the test message.

    3. Send a test message to the specified number, then check the webhook records below.

      You can check the webhook record to see the message delivery details.

  5. On the left navigation bar, go to WhatApp > Step 2. Production setup, add your business nubmer(s) and obtain the required number information for the channel integration:
    1. In the Register your WhatsApp phone number section, click Add new number to add your WhatsApp phone number for messaging.

    2. Note down the corresponding Phone Number ID of the number you added as you will need to add it on the PBX later.
  6. On the left navigation bar, go to App settings > Basic, note down the App secret of the app for the channel integration.

Step 2. Obtain essential credentials on 'Meta Business Suite' portal

On 'Meta Business Suite' portal, create a system user and grant permissions to the user, then generate an access token for the user to grant access the Meta App you created in the previous step, which is required when configuring WhatsApp channel on the PBX. Additionally, obtain the WhatsApp Business Account ID, which is needed to retrieve message templates associated with the account.
Important: It is recommended to use the access token from Meta Business Suite instead of the one from Meta for Developer portal, as the latter is a temporary token that may cause missed messages once it expires.
  1. Log in to 'Meta Business Suite' portal with your Business Manager account.
  2. On the left navigation bar, go to Settings.
  3. Go to Users > System users, create a system user and grant app permission to the user.
    1. Click Add to create a system user with Admin role.

    2. Select the created user, click Add assets and grant the full access permission of the app you created to the created user.

  4. Go to Accounts > WhatsApp Accounts, add the created user to your WhatsApp Business account and grant the user full access permission.

  5. Go back to Users > System users, generate an access token with the whatsapp_business_messaging and whatsapp_business_management permissions enabled.
    Note: By default, the token expires after 60 days. You can set it to Never if you don't want the token to expire.

    The pop-up window shows the generated access token.
    Important: Make sure that you have copied and properly saved the access token before closing the pop-up window, as it is only displayed ONCE.

  6. Go to Accounts > WhatsApp accounts, click your WhatsApp Business Account, then copy the account ID.

Step 3. Create and configure a WhatsApp channel on PBX

On the PBX, create a WhatsApp channel and configure it using the information obtained in the previous steps. This ensures that the PBX can connect to the WhatsApp for messaging.

  1. Log in to PBX web portal, go to Messaging > Message Channel.
  2. Click Add, and select WhatsApp.
  3. In the Authentication tab, enter the authentication information of WhatsApp.

  4. In the Messaging Settings tab, configure the channel.
    1. Enter WhatsApp phone number information.

    2. In the WhatsApp Business Account ID field, paste the account ID obtained from 'Meta Business Suite' portal.

      PBX will automatically synchronize the message templates associated with the WhatsApp account to the channel.

    3. In the Destination for Inbound Messaging drop-down list, specify the destination of inbound messages from the number.

      Option Description
      Extension If selected, choose an extension from the Extension drop-down list.

      Only the extension user can receive inbound messages from the number.
      Message Queue If selected, choose a queue from the Message Queue drop-down list.

      All the agents in the selected message queue can receive inbound message(s) of new sessions in the queue. However, only the user who picks up a session will be able to receive and respond to the follow-up inbound messages in the session.
      Third-Party Message Analytics Platform (Transmitted via API) If selected, inbound messages will be automatically forwarded to a third-party message analytics platform via API for advanced processing.
      Note: To enable automatic forwarding of inbound messages to a third-party message analytics platform, ensure that your PBX server has been integrated with the third-party message analytics platform via API. Once this option is selected, the PBX system will automatically transmit inbound messages to the designated platform. You can get notified by monitoring the API event (30031) New Message Notification. Additionally, the PBX provides a comprehensive Message API suite for advanced message interaction with the integrated third-party message analytics platforms.
    4. In the Extensions Allowed to Create Messaging Sessions section, select the extensions that are allowed to initiate a messaging session with customers.

    5. Configure the following session settings as needed.
      Setting Description
      Close Session Automatically If you want the system to automatically close the sessions that have been inactive for a specific period of time, select the checkbox, then set the timeout in the Session Timeout (Days) field.

      Allow the Creation of Duplicate Active Sessions To allow creating a new session when an active session with the same sender and receiver already exists, select the checkbox.

      When enabled, if an extension user creates a session on Linkus client and an active session with the same sender and receiver already exists in the system, a pop-up prompt will appear. If the user chooses to continue creating the new session, the original session will be removed from the previous handler's session list, and taken over by the creator, along with the complete chat history.
  5. Click Save.

Step 4. Configure webhook in the Meta app

On the 'Meta for Developers' portal, set up a webhook for your Meta app to receive real-time message events. This allows the PBX to process incoming messages from WhatsApp.

  1. Log in to 'Meta for Developers' portal with your Meta Developer account, then go to My Apps from the top menu.

  2. Click the created app to enter the details page.

  3. In the left navigation bar, go to WhatsApp > Step 2. Production setup, configure the messaging webhook and subscribe to webhook field, so that PBX can get notified upon receiving WhatsApp messages.
    1. In the Configure Webhooks section, paste the Webhook URL and verify token obtained from the PBX, then click Verify and save.

    2. In the Webhook fields section, subscribe to messages webhook field.

Result

  • The Status of the WhatsApp channel shows , which indicates that you have successfully created a WhatsApp channel.

  • PBX automatically tracks and records the number of messages sent and received on the channel, where the Total column displays the total amount of the sent messages, including both successfully sent messages and failed ones.
    Tip: You can filter the statistics by a time period using the time filter.

What to do next

Send text messages to the phone number and see if the specified agent can receive messages on his or her Linkus UC Client.