Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Setting up social channels

Updated on November 7, 2022

Set up the conversational channels connections including Apple Business Chat, WhatsApp, SMS, and Facebook within the Digital Messaging Manager of your Digital messaging interface to enable customers to interact with Pega Intelligent Virtual Assistant (IVA) by sending messages from the respective messaging channels. By performing this task, you ensure that users can quickly and efficiently request information or report problems with your application through these conversational channels.

Note: Due to changes by Twitter in the API and the licensing model, direct integration with Twitter is no longer supported in the Digital Messaging channel interface.
Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide
Before you begin: Create a new Digital Messaging interface for IVA.
You use the Digital Messaging Manager that you can access from the Channel tab of your Digital Messaging interface to configure individual social channels from one place on your self-service application in the Pega Customer Service application.

Setting up Apple Business Chat

Before you begin: Perform the following tasks:
  • Create a Business Chat account in the Apple Business Chat portal by registering for the Apple iMessage service. Apple will generate a Business Chat identifier for your account. For more information, refer to the Apple Business Chat portal.
  1. Add a digital messaging channel connection of your choice in Digital Messaging Manager. For information on adding a connection, see Adding a social messaging channel connection.
    For example: Select the Apple Business Chat channel to add as a connection.
  2. On the Apple Business Chat Accounts page, click the Add new ABC account icon.
  3. In the Add New Business Chat Account window, in the Account Name field, enter a label for your Apple Business Chat account to use in the system.
    For example: Enter: Sample U+ Bank.
  4. In the Business Chat ID field, enter an identifier for your Apple Business Chat account.
    For example: :Enter: 427c3913-bas7-22f6-6c99c1ecbb2f.
    Apple generates a unique Business Chat identifier when you create an account in the Apple Business Chat portal.
  5. Click Submit.
  6. The system displays the Apple Business Chat connection in the Connections section.
  7. Close the window, and then in your Digital Messaging interface, click Save.

Setting up WhatsApp

Before you begin:
  • Create a Facebook Manager business account on the Facebook portal to generate a Facebook Manager business account ID. For more information, see Get Started with Facebook Business Manager Guide on the Facebook website.
  • Create a Twilio account on the Twilio portal. For more information, see Get started with a free Twilio account on the Twilio website.
  • Upgrade the Twilio account to a paid account. For more information, see Upgrading to a paid Twilio account on the Twilio support website.
  • Set up a WhatsApp number for your Twilio account.
  1. Add a digital messaging channel connection of your choice in Digital Messaging Manager. For information on adding a connection, see Adding a social messaging channel connection.
    For example: Select the WhatsApp channel to add as a connection.
  2. On the Twilio WhatsApp Accounts page, click Add New Twilio WhatsApp Number.
  3. In the Add New Twilio WhatsApp Number window, perform the following tasks:
    1. In the Name field, enter a name for your WhatsApp account.
    2. In the Number field, enter a WhatsApp number, including the country code.
      For example: Enter: +12239992233
    3. In the Account SID field, enter the identifier for your Twilio account.

      Twilio generates a unique identifier when you create a Twilio account.

      For example: Enter: BA6d82c336e8d135edef20311c2287g8cd
    4. In the Auth Token field, enter the authorization token for your Twilio account.
      Twilio generates an authorization token when you create a Twilio account.
      For example: Enter: d2377c436100cd1edd0836cf5feab23d
    5. Click Submit.
      Result: The page displays your WhatsApp account information including its name, number, account SID, and account token.
  4. In the Webhook for Twilio WhatsApp section, select and copy the generated webhook URL for WhatsApp.
    For example: Copy the following URL to the clipboard: https://incoming.sample.pega.digital/twilio-whatsapp
  5. Define the webhook URL for the WhatsApp numbers in your Twilio account by performing the following steps:
    1. Log in to your Twilio account.
    2. Click the More icon, and then click Programmable SMS WhatsApp Senders.
    3. In the displayed list, select a WhatsApp number, and then click Configure.
    4. In the Twilio Senders for WhatsApp window, in the Senders Configuration section in the A Message Comes In field, paste the webhook URL that you copied in step 7.
      This action ensures that when your phone number receives inbound messages from WhatsApp Messenger, Twilio forwards the messages to the IVA channel.
    5. To add additional WhatsApp numbers for your Twilio account to the webhook URL, repeat steps 8.c through 8.d.
    6. Click Close.
  6. The system displays the WhatsApp connection in the Connections section of Digital Messaging Manager.
  7. Close the window, and then in your Digital Messaging interface, click Save.

Setting up SMS

Before you begin:
  • Create a Twilio account for the mobile phone number that you plan to use with your self-service application on Pega Customer Service. Twilio will generate a unique identifier and authorization token for your Twilio account. For more information, refer to the Twilio portal.
  1. Add a digital messaging channel connection of your choice in Digital Messaging Manager. For information on adding a connection, see Adding a social messaging channel connection.
    For example: Select the SMS channel to add as a connection.
  2. On the SMS Accounts page, click Add New Twilio Number.
    This action ensures that you give permission to your Twilio SMS account to send and receive messages on behalf of the IVA channel.
  3. In the Add New Twilio Number window, perform the following steps: in the
    1. In the Name field, enter a name for your Twilio account.
    2. In the Number (Please include country code) field, enter the phone number, including the country code, for your Twilio account.
    3. In the Account ID field, enter the identifier for your Twilio account.
      Twilio generates a unique identifier when you create a Twilio account.
    4. In the Auth Token field, enter the authorization token for your Twilio account.
      Twilio generates an authorization token when you create a Twilio account.
    5. Click Submit.
  4. On the SMS Accounts page, highlight and copy the generated webhook URL for Twilio.
  5. Access your account on the Twilio portal, click Manage Numbers, and then click Active Numbers.
  6. In the Messaging section, in the field next to the A Message Comes In webhook section, paste the webhook URL that you copied in step 7.
    This action ensures that when your Twilio phone number receives inbound SMS messages, Twilio forwards the messages to the IVA channel.
  7. The system displays the SMS connection in the Connections section of Digital Messaging Manager.
  8. Close the window, and then in your Digital Messaging interface, click Save.

Setting up Facebook

Before you begin: If you do not have a Facebook Admin account and one or more Facebook pages, create them. For more information, see the Facebook developer portal.
Note: You use your Facebook Admin account to authorize the Pega Facebook App to retrieve Facebook messages that the system posts to your selected Facebook pages. Your Facebook account must be an Admin of the Facebook pages in order to provide this authorization.

You cannot use your Facebook Admin account to authorize a Facebook page for Digital Messaging in more than one Pega application at the same time, but you can use a Facebook Admin account to add multiple Facebook pages to the same application. When using Facebook, a Facebook page can have multiple Admins Create a Facebook page for your Facebook application. For more information, see the Facebook developer portal.

  1. Add a Digital Messaging channel connection of your choice in Digital Messaging Manager. For information on adding a connection, see Adding a social messaging channel connection.
    For example: Select the Facebook channel to add as a connection.
    Result: The systems displays the Facebook login page.
  2. Log into your Facebook account using your Facebook Admin account credentials.
    You must use an account that is an admin of the Facebook page that you want to authorize.
  3. In the open window, click Continue as <YOUR NAME>.
  4. In the page selection window for your Facebook page application, select the checkbox for the Facebook page that you plan to use with your Pega Customer Service application, and then click Next.
  5. Review the permissions for your Facebook page, and then click Done.
    Result: The window shows that your Facebook page is now linked to your Digital Messaging channel.
  6. Click Ok.
    Result: The system displays the following message: Authorization successful for <Facebook page> and then displays the page as a Facebook connection in the Connections section of digital messaging manager.
  7. To display Get Started in the Facebook Messenger, turn on the Messenger Get Started Button switch.

    Users see Get Started on the welcome screen in Messenger. When the user clicks Get Started, the Get Started message is posted in the conversation, and the page is granted permission to send messages.

    Note: Facebook provides Get Started. You cannot customize it.
    Connecting to the application upon clicking Get Started
    Clicking Get Started to connect to the application.
    Note: Users will see Get Started only the first time that they begin a conversation on Facebook Messenger with the page or if they have cleared a conversation by using Delete Chat in Messenger.

    The above scenario applies when the user starts a conversation directly on Facebook or follows a channel switch from Web Messaging to Facebook Messenger.

    Get Startedis enabled for connected Facebook pages in the Digital Messaging Managerwhen a user adds the page to its Web Messaging channel switch options.

  8. Close the window, and then in your Digital Messaginginterface, click Save.

Client Channel API

The Client Channel API provides you with a standardized method to exchange messages between several types of third-party client channels, for example, Teams, Webex, or Slack, and Digital Messaging Service.

The process of sending and receiving messages as JSON payload requests using the Client Channel API consists of four stages:

  1. Your client channel sends messages to the integration layer that you configure in premises (back-end), using the communication method that is specific to the type of client channel.
  2. In your integration layer, transform the received client channel payload into the format that is required by the Client Channel API. Then, pass the message to the endpoint for the Digital Messaging Service.

    This endpoint is the Digital Messaging Webhook URL that the system specifies in your Digital Messaging Manager and Client Channel API settings, for example: https://incoming.artemis.pega.digital/messages

    The Digital Messaging Service then forwards the message to your Pega Customer Service application.

  3. Your Pega Customer Service application returns a response to the Digital Messaging Service which then forwards the response to the endpoint that you specify for your integration layer in your Digital Messaging Manager Client Channel API settings, for example: https://sampleclientchannelwebhook.com. You must configure the webhook URL so that the URL is publicly accessible (off VPN) to enable communication with Digital Messaging Service. If your integration layer is behind a firewall or otherwise limits access to internal-only users and components, you must set up the webhook URL so that the URL is reachable publicly.
  4. Your integration layer transforms the received Digital Messaging Service payload into the required format by your client channel, and then passes the message to the client channel endpoint.
Note: To learn about the supported format of the JSON payloads for the Client Channel API, see

Supported message types

The system supports the following features during communication from a client channel to the Digital Messaging service:
  • Text messages
  • Typing indicators
  • Attachments
  • Postbacks
  • End session event (customer ended the conversation)
  • Context data
The system supports the following features while communicating with the Digital Messaging service to a client channel:
  • Text messages
  • Typing indicators
  • Attachments
  • List pickers
  • Links/buttons
  • Carousels
  • End session event (CSR/chatbot ended the conversation)

Creating a client channel connection

Use the Client Channel API to securely communicate between your Pega Customer Service application, your integration layer, and third-party client channels, for example, Teams, Webex, or Slack. As a result, you make Digital Messaging more accessible by engaging with your customers in their preferred social messaging channels. The Client Channel API provides you with a Digital Messaging Service endpoint to which you can send payload requests in JSON format. The payload requests indicate an action during a chat conversation, for example, when a customer in the client channel sends a message. Similarly, you can set up an endpoint for your integration layer to receive payload requests from the Digital Messaging Service, for example, when the chatbot or CSR sends a reply or is busy typing.

Before you begin:

Configure Digital Messaging channel security settings, and create a Digital Messaging channel if you do not have a channel interface for Digital Messaging. For more information, see Enabling Digital Messaging.

  1. In the Digital Messaging Manager of your Digital Messaging interface, select Add connection, and then click the Client Channel APIicon.
  2. In the New Client Channel API section, complete the following fields:
    1. In the Name field, enter a unique name for your channel.
    2. In the Client webhook field, enter the URL of a client webhook.
      Note:

      You must configure the webhook URL so that the URL is publicly accessible (off VPN) to enable communication withDigital Messaging Service. If your integration layer is behind a firewall or otherwise limits access to internal-only users and components, you must set up the webhook URL so that the URL is reachable publicly. Ensure that the URL string starts with "https."

  3. Click Save.
    Result: The Digital Messaging Service creates a new channel connection that displays the following fields:
    Connection ID (JWT issuer)
    A unique ID assigned to the connection. The ID connection is also an issuer for JSON Web Tokens (JWT).
    Client Webhook
    The URL that the client enters when creating the connection. This URL is the target on the client system where the Digital Messaging Service sends the messages.
    Digital Messaging Webhook
    Endpoint URL on the Digital Messaging Service. The service uses this URL to receive messages that the client sends.
    JWT Secret
    The service uses JWT Secret to authenticate the communication between the client and the Digital Messaging Service.

    On the Connections tab of your Digital Messaging interface, the system displays the Client Channel API connection.

Result:

After you configure a Client Channel API connection, users can send and receive messages from a chatbot or an agent the same way that they do using other native Digital Messaging channels.

Client Channel API guidelines

Use the guidelines in this section to help you design the best possible third-party client channel integration with the Digital Messaging channel.

Consider the following best practices for your client channel integration with the Client Channel API:

  • The Client Channel API does not provide a direct integration to any client channels, for example, Slack or Teams.
  • You cannot create an integration in your local environment that directly connects to your client channel and Digital Messaging Service. You must build a custom integration layer in your back-end that meets the endpoint and payload requirements for both your client channel and the Client Channel API, in order to pass messages between them.
  • Each client channel has unique setup and configuration guidelines for integrating with an API. Consult the documentation for the client channel for specific instructions on how to configure the integration.
  • You must configure the URL endpoints on your back-end to enable the message delivery between your client channel and the Client Channel API. The endpoint for the Client Channel API is displayed in your Digital Messaging Manager settings. For your client channel endpoints, consult API instructions that are specific to your third-party client channel, in order to create your implementation endpoints. You must configure the webhook URL so that the URL is publicly accessible (off VPN) to enable communication with Digital Messaging Service. If your integration layer is behind a firewall or otherwise limits access to internal-only users and components, you must set up the webhook URL so that the URL is reachable publicly.
  • You must secure all endpoints using the Transport Layer Security (TLS) protocol, by using https.
  • The system uses JSON Web Tokens (JWT) to authenticate the communication in both directions, between your back-end and Digital Messaging Service. You must generate a valid JWT to include in each request to send.
  • The Client Channel API does not track chat sessions. You must handle session control in your integration layer or the client channel.

Client Channel API payload requirements

To communicate between your Digital Messaging channel and a third-party client channel for example, WebEx or Teams, you use the Client Channel API by sending and receiving JSON data in a specific payload format. As a result, your integration layer can interact with Digital Messaging Service and your third-party client channel in the correct format, providing a seamless experience to the customer. You can configure different payload types in the same API in your integration layer.

Authorization

To send and receive JSON requests between the integration layer and Digital Messaging Service, JSON payload headers must include the following information:

Authorization token
The "Bearer {JWT}" value.
The connection_id value
The unique ID of the connection for your client channel.

Your integration layer must generate an authorization token that you include in each JSON request. Use the connection_id value as the JSON Web Token (JWT) issuer and sign the JWT using the value for JWT Secret, as shown in the following sample code:

var jwt = require("jsonwebtoken")
const token = jwt.sign({iss: "connection_id"}, 'jwt_secret');
console.log(token);

After you successfully add a Client Channel API connection in the Digital Messaging Manager, the system stores the connection_id and JWT Secret values in your Client Channel API settings. For more information, see Creating a client channel connection.

Note: For security reasons, each authorization JWT token is valid only for 5 minutes from the time your integration layer issues the token. This expiry period is fixed.

Incoming payload format

To send request payloads from your integration layer to Digital Messaging Service, invoke POST {DIGITAL_MESSAGING_WEBHOOK} with a JSON request body, for example: POST https://incoming.artemis.pega.digital/messages

When a customer performs any of the following actions in the client channel, send a request payload from your integration layer:

  • Sends a message
  • Is busy typing their message
  • Ends the chat conversation
Customer message

The following is the JSON body format of the request payload for the customer message that your integration layer sends to Digital Messaging Service:

Body (JSON)
{ 
   "type": "text", 
   "customer_id": "string", 
   "customer_name": "string", 
   "message_id": "string", 
   "text": ["string"], 
   "postback": "string", 
   "attachments": [ 
     { 
       "url": "string" 
     } 
   ], 
   "context_data": { 
      "string": "string" 
   } 
}

The following table describes the parameters passed in the Customer message payload request:

ParameterDescriptionType
typeThe static value "text"Required
customer_idThe ID of the customer sending the message. The ID is a unique value that is provided by the client channel.Required
customer_nameThe name of the customer sending the message.Optional
message_idThe ID of the message. The ID is a unique value that is provided by the client channel and must be different for every message.Required
textAn array of strings that specify messages from the customer. See also the note below.Optional
postbackThe payload value of the menu or carousel item that is selected. See also the note below.Optional
attachments.[].urlTemporary private URL that references a file attachment. See also the note below.Optional
context_data.keyThe context data key.Optional
context_data.valueThe context data value.Optional
Note: If the JSON payload that you send contains empty fields for the text, attachment and postback parameters, then Digital Messaging Service will not receive the message. The system uses the value passed in the postback parameter as a response to a menu or a carousel selection, and the value must match the menu or carousel item payload value that is selected by the customer. The system uses the key and value pairs to pass context data within the message.

The attachment URL must be a valid downloadable value, for example, https://samplesite.com/filename.pdf . The system receives message_id as the source_id and uses the value as the pySourceID in your application.

Typing indicator
The following code is the JSON body format of the request payload that your integration layer sends to Digital Messaging Service when the customer is typing a message:
Body (JSON) 
{ 
   "type": "typing_indicator", 
   "customer_id": "string", 
}

The following table describes the parameters passed in the Typing indicator payload request:

ParameterDescriptionType
typeThe static value "typing_indicator".Required
customer_idThe ID of the customer that is sending the message. The ID is a unique value that is provided by the client channel.Required
Customer ended the conversation
The following is the JSON body format of the request payload that your integration layer sends to Digital Messaging Service when the customer ends the conversation:
Body (JSON) 
{ 
   "type": "customer_end_session", 
   "customer_id": "string", 
}

The following table describes the parameters passed in the Customer ended the conversation payload request:

ParameterDescriptionType
typeThe static value "customer_end_session".Required
customer_idThe ID of the customer that is sending the message. The ID is a unique value that is provided by the client channel.Required

Outgoing payload format

To receive request payloads from Digital Messaging Service in your integration layer, the system uses POST {CLIENT_WEBHOOK} to send a JSON request body, for example: POST https://sampleclientchannelwebhook.com

You receive a request payload in your integration layer when the chatbot or CSR performs one of the following actions in your Digital Messaging channel:

  • Sends a message
  • Displays a menu
  • Displays a carousel
  • Sends a link
  • Is busy typing in the chat window
  • CSR ends the chat conversation
CSR message

The following is the JSON body format of the request payload that your integration layer receives from Digital Messaging Service when the chatbot or CSR sends a message:

Body (JSON)
{ 
   "type": "text", 
   "customer_id": "string", 
   "message_id": "string", 
   "csr_name": "string", 
   "text": ["string"], 
   "attachments": [ 
      { 
         "url": "string", 
         "content_type": "string", 
         "file_name": "string", 
         "size": numeric 
      } 
   ] 
}

The following table describes the parameters passed in the Text message payload request:

ParameterDescription
typeThe static value "text".
customer_idThe ID of the customer to which the chatbot or CSR sends the message.
message_idThe unique ID of the message.
csr_nameThe name of the CSR that is sending the message.
textAn array of strings that correspond to the messages sent by the chatbot or CSR.
attachments.[].urlA temporary private URL that references an attachment file.
attachments.[].content_typeThe content type for the file attachment.
attachments.[].file_nameThe attachment file name.
attachments.[].sizeThe size in bytes of the file attachment

Menu
The following is the JSON body format of the request payload that your integration layer receives from Digital Messaging Service for a menu selection:
Body (JSON)
{ 
   "type": "menu", 
   "customer_id": "string", 
   "message_id": "string", 
   "csr_name": "string", 
   "title": "string", 
   "items": [ 
      { 
         "text": "string", 
         "payload": "string", 
         "image_url": "string" 
      } 
   ] 
}

The following table describes the parameters passed in the Menu payload request:

ParameterDescription
menuA static value "menu".
customer_idThe ID of the customer to which the chatbot or CSR sends the message.
message_idThe unique ID of the message.
csr_nameThe name of the CSR that is sending the message.
titleThe title for the menu.
items.[].textThe label for the menu option.
items.[].payloadThe postback value for the reply option.
items.[].image_urlThe URL referencing an optional image for the reply option.

Carousel
The following is the JSON body format of the request payload that your integration layer receives from Digital Messaging Service for a carousel selection:
Body (JSON)
{
   "type": "carousel",
   "customer_id": "string",
   "message_id": "string",
   "csr_name": "string",
   "items": [
      {
         "title": "string",
         "sub_title": "string",
         "title_image_url": "string",
         "items": [
            {
               "text": "string",
               "payload": "string",
               "description": "string",
               "image_url": "string"
            }
         ]
      }
   ]
}

The following table describes the parameters passed in the Carousel payload request:

ParameterDescription
typeThe static value "carousel".
customer_idThe ID of the customer to which the chatbot or CSR sends the message.
message_idThe unique ID of the message
csr_nameThe name of the CSR that is sending the message.
items.[].sub_titleThe optional subtitle for the menu.
items.[].title_image_urlThe optional title image URL for the menu.
items.[].items[].textThe label for the menu.
items.[].items[].payload The postback value for the menu option.
items.[].items[].descriptionThe optional description for the menu option.
items.[].items[].image_urlThe URL referencing the optional image for the menu option.

Link
The following is the JSON body format of the request payload that your integration layer receives from Digital Messaging Service for a link:
Body (JSON)
{ 
   "type": "link_button", 
   "customer_id": "string", 
   "message_id": "string", 
   "csr_name": "string", 
   "title": "string",
   "label": "string",
   "url": "string"
   } 
}

The following table describes the parameters passed in the Link payload request:

ParameterDescription
typeThe static value "link_button".
customer_idThe ID of the customer to which the chatbot or CSR sends the message.
message_idThe unique ID of the message
csr_nameThe name of the CSR that is sending the message.
titleThe title for the link button.
labelThe label for the link button.
urlThe URL that opens when a customer taps the button.
Typing indicator
The following is the JSON body format of the request payload that your integration layer receives from Digital Messaging Service when the CSR or chatbot is typing:
Body (JSON)
{ 
   "type": "typing_indicator", 
   "customer_id": "string", 
}

The following table describes the parameters passed in the Typing indicator payload request:

ParameterDescription
typeThe static value "typing_indicator".
customer_idThe ID of the customer.
CSR ended the conversation

The following is the JSON body format of the request payload that your integration layer receives from Digital Messaging Service when the CSR ends the conversation:

Body (JSON)
{ 
   "type": "csr_end_session", 
   "customer_id": "string", 
}

The following table describes the parameters passed in the CSR ended the conversation payload request:

ParameterDescription
typeThe static value "csr_end_session".
customer_idThe ID of the customer.

Delivery confirmation

On successful delivery of a request payload from your integration layer to Digital Messaging Service, the system returns a success response, 200: Successful request, for example:

{
    "account_id": "string",
    "source_id": "string",
    "source": "custom",
    "date": "2022-07-08T14:51:01.589Z",
    "visibility": "private",
    "recipient_profile_id": "string",
    "customer": {
        "id": "string",
        "profile_name": "string",
        "profile_id": "string"
    },
        "consumer_id": "string",
        "content": {
            "text": "string"
    },
    "postback": "string",
    "context_data": {
        "string": "string"  
    }
}

In a case of failure, Digital Messaging Service returns one of the following response errors:

  • 400: Malformed payload (invalid message type)
  • 403: Invalid/Expired JWT
  • 404: API Endpoint not found
  • 422: Un-processable request (missing mandatory fields, invalid JSON)

Tags

Pega Customer Service 8.7 Pega Customer Service for Communications 8.7 Pega Customer Service for Financial Services 8.7 Pega Customer Service for Healthcare 8.7 Pega Customer Service for Insurance 8.7

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us