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:

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:

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:

Outgoing payload format

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:

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:

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:

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:

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:

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)