Skip to main content


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

Client Channel API payload requirements

Updated on March 3, 2023

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 set up your Pega Intelligent Virtual Assistant (IVA) and 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 Setting up the IVA for Client Channel API.

Note: For security reasons, each authorization JWT token is valid only for 5 minutes from the time your integration layer issues the token. This exipry 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.
textThe text message string 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[].payloadThe 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)

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