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.

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:

Parameter	Description	Type
type	The static value "text".	Required
customer_id	The ID of the customer sending the message. The ID is a unique value that is provided by the client channel.	Required
customer_name	The name of the customer sending the message.	Optional
message_id	The 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
text	An array of strings that specify messages from the customer. See also the note below.	Optional
postback	The payload value of the menu or carousel item that is selected. See also the note below.	Optional
attachments.[].url	Temporary private URL that references a file attachment. See also the note below.	Optional
context_data.key	The context data key.	Optional
context_data.value	The 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:

Parameter	Description	Type
type	The static value "typing_indicator".	Required
customer_id	The 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:

Parameter	Description	Type
type	The static value "customer_end_session".	Required
customer_id	The 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:

Parameter	Description
type	The static value "text".
customer_id	The ID of the customer to which the chatbot or CSR sends the message.
message_id	The unique ID of the message.
csr_name	The name of the CSR that is sending the message.
text	The text message string sent by the chatbot or CSR.
attachments.[].url	A temporary private URL that references an attachment file.
attachments.[].content_type	The content type for the file attachment.
attachments.[].file_name	The attachment file name.
attachments.[].size	The 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:

Parameter	Description
menu	A static value "menu".
customer_id	The ID of the customer to which the chatbot or CSR sends the message.
message_id	The unique ID of the message.
csr_name	The name of the CSR that is sending the message.
title	The title for the menu.
items.[].text	The label for the menu option.
items.[].payload	The postback value for the reply option.
items.[].image_url	The 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:

Parameter	Description
type	The static value "carousel".
customer_id	The ID of the customer to which the chatbot or CSR sends the message.
message_id	The unique ID of the message.
csr_name	The name of the CSR that is sending the message.
items.[].sub_title	The optional subtitle for the menu.
items.[].title_image_url	The optional title image URL for the menu.
items.[].items[].text	The label for the menu.
items.[].items[].payload	The postback value for the menu option.
items.[].items[].description	The optional description for the menu option.
items.[].items[].image_url	The 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:

Parameter	Description
type	The static value "link_button".
customer_id	The ID of the customer to which the chatbot or CSR sends the message.
message_id	The unique ID of the message
csr_name	The name of the CSR that is sending the message.
title	The title for the link button.
label	The label for the link button.
url	The 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:

Parameter	Description
type	The static value "typing_indicator".
customer_id	The 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:

Parameter	Description
type	The static value "csr_end_session".
customer_id	The 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)