Set up a WhatsApp Channel

This topic describes how to set up a WhatsApp channel on Yeastar P-Series Software Edition, 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 83.12.0.23 or later
  • Plan: Enterprise Plan (EP) or Ultimate Plan (UP)
  • FQDN: PBX can be accessed via Yeastar FQDN.
    Note: Due to the limitation of the third-party platform, the FQDN domain name must NOT contain underscore character(s), otherwise the messaging channel will encounter authentication failure, or will fail to receive messages.

    For more information about the configuration, see Configure Network for Remote Access by a Yeastar FQDN.
WhatsApp
  • Product: WhatsApp Business Platform
  • Account:
  • Phone number: Ensure that your phone number is valid and available for messaging.
    Note: You can check the status of your phone number on 'Meta Business Suite' portal (Path: Account > WhatsApp accounts > WhatsApp Manager > Account tools > Phone numbers).

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 Supports to receive and reply to Inbound messages, but agents can NOT initiate a messaging session with a WhatsApp user.
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.
Session auto closure

A session that has been inactive for more than 24 hours will be closed automatically.

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, 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 Add products to your app page, scroll down to find WhatsApp and click Set up.

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

  4. On the left navigation bar, go to WhatsApp > API Setup > Send and receive messages, and complete the followings:
    1. In the From drop-down list, click Add phone number to add your WhatsApp phone number for messaging.

    2. Select the added phone number from the list, then note down the corresponding Phone number ID as you will need to add them on the PBX later.

      Important: If you are using the test number provided by WhatsApp for demo or testing purposes, you need to specify the recipients' phone number in the To drop-down list, otherwise message sending may FAIL.

  5. On the left navigation bar, go to App settings > Basic, note down the App secret of the app, as you will need it later on PBX.

Step 2. Generate Permanent Access Token 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.
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. At the top-left corner of the 'Meta for Developers' portal, go to App Dashboard > Business settings.

    You are redirected to the Business settings page of 'Meta Business Suite' portal.

  2. 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 control permission of the app to the created user.

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

  4. 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.

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.

    • Phone Number: Enter the WhatsApp phone number in E.164 format ([+][country code][phone number]). For example, +15559871234.
    • Phone Number ID: Paste the phone number ID.
    • Destination for Inbound Messaging: 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.
  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, then go to My Apps from the top menu.

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

  3. Go to WhatsApp > Configuration to configure the messaging webhook and subscribe to webhook field, so that PBX can get notified upon receiving WhatsApp messages.
    1. Paste the Webhook URL and verify token obtained from the PBX.

    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.