dms-client-channel

Pega Digital Messaging Service client channel

This package will interface with the Pega Digital Messaging Service(DMS) client channel and provides callback methods for messages & events received from the Pega Digital Messaging Service. Once configured the dms-client-channel allow you to:

• Validate request tokens from the DMS
• Detect message types and run appropriate callbacks when a message or event is received from the DMS
• Send messages and events to the DMS messaging API using built-in methods

Installation

$ npm install dms-client-channel

Setup

In order for the Digital Messaging Service (and client channel) to communicate with your application, it will need to accessible through a public URL. For local testing and development you may use a reverse proxy service such as ngrok to make your localhost publicly accessible.

In your server.js file, add the following. See examples folder for express_endpoints_example.js implementation example using express.js.

//import the dmsClientChannel module
const dmsClientChannel = require("dms-client-channel");

//Add your channel credentials (found in the digital messaging manager portal).
const DMS_CONFIG = {
  JWT_SECRET: "your jwt secret here",
  CHANNEL_ID: "your channel id here",
  API_URL: "your messaging api URL",
};

//Create an instance of the dmsClientChannel and pass in the config set.
let dms = dmsClientChannel(DMS_CONFIG);

Please note that In a production environment the DMS_CONFIG variables should be retrieved from process environment variables, or some other secure resource.

Usage

onRequest

in your server, call the onRequest method every time your endpoint receives a request from the DMS. This method validates the request token and calls the appropriate onMessage callbacks. the returned values can be used for your server's DMS endpoint response.

• req should be the request object received from the DMS
• status http status code
• statusText http response text (success, forbidden etc.)

Please note that this method must be implemented in order for the dmsClientChannel onMessage callbacks to work correctly

/**
 * /dms endpoint to receive messages from the DMS layer using express.js to configure our server endpoints.
 */
app.post("/dms", async (req, res) => {
  try {
    //call the DMS on request method every time a request is received and pass in the request object
    dms.onRequest(req, async (status, message) => {
      res.status(status).send(message);
    });
  } catch (err) {
    return res.status(401).send(err);
  }
});

onMessage* callback methods

There are callback methods provided for each type of message or event received from the DMS. When a message is received, the appropriate callback is called. The developer should leverage these callbacks within their application to implement the client-channel specific logic for each event type received.

onTextMessage(message) {}
onMenuMessage(message) {}
onCarouselMessage(message) {}
onUrlLinkMessage(message) {}
onTypingIndicator(customer_id) {}
onCsrEndSession(customer_id) {}

onTextMessage callback method

called when your server receives text message(s) from the DMS

• message the message received from the DMS is passed to the callback

//Text Message object
{
	"type": "text",
	"customer_id": "string",
	"message_id": "string",
	"csr_name": "string",
	"text": ["string"],
	"attachments": [{
		"url": "string",
		"content_type": "string",
		"file_name": "string",
		"size": numeric
	}]
}

Example usage:

//Called when a text message is received from the DMS
dms.onTextMessage = async (message) => {
  console.log("onTextMessage callback. message:" + message.text);

  //translate message json from DMS-format to client channel format...

  //call send message api on client channel to send the message...
};

onMenuMessage callback method

called when your server receives a menu message from the DMS

• message the message received from the DMS is passed to the callback

Example usage:

//Called when a menu message is received from the DMS
dms.onMenuMessage = async (message) => {
  console.log("onMenuMessage callback. message:" + message.title);

  //translate message json from DMS-format to client channel format...

  //call send message api on client channel to send the message...
};

Menu message callback argument:

//Menu Message object
{
  "type": "menu",
  "customer_id": "string",
  "message_id": "string",
  "csr_name": "string",
  "title": "string",
  "items": [
    {
      "text": "string",
      "payload": "string",
      "image_url": "string"
    }
  ]
}

onCarouselMessage callback method

called when your server receives a carousel message from the DMS

• message the message received from the DMS is passed to the callback

Example usage:

//Called when a carousel message is received from the DMS
dms.onCarouselMessage = async (message) => {
  console.log("onCarouselMessage callback. message:" + message.items[0].title);

  //translate message json from DMS-format to client channel format...

  //call send message api on client channel to send the message...
};

message callback argument:

//Carousel Message object
{
  "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"
        }
      ]
    }
  ]
}

onUrlLinkMessage callback method

called when your server receives a URL link message from the DMS

• message the message received from the DMS is passed to the callback

Example usage:

//Called when a url link message is received from the DMS
dms.onUrlLinkMessage = async (message) => {
  console.log("onUrlLinkMessage callback. message:" + message.items[0].title);

  //translate message json from DMS-format to client channel format...

  //call send message api on client channel to send the message...
};

URL link message callback argument:

//Link Message object
{
  "type": "link_button",
  "customer_id": "string",
  "message_id": "string",
  "csr_name": "string",
  "title": "string",
  "label": "string",
  "url": "string"
}

onTypingIndicator callback method

called when your server receives text message(s) from the DMS

• customer_id String - the customer_id of the person who should receive the typing indicator.

Example usage:

//Called when a typing indicator is received from the DMS
dms.onTypingIndicator = async (customer_id) => {
  console.log("onTypingIndicator callback. customer_id: " + customer_id);
  //call client api to send typing indicator...
};

onCsrEndSession callback method

called when a CSR ends the session

• customer_id String - the customer_id of the session that's been ended

Example usage:

//Called when the CSR ends the chat session
dms.onCsrEndSession = async (customer_id) => {
  console.log("onCsrEndSession callback. customer_id: " + customer_id);
  //call client api to notify of CSR end session event.
};

sendTextMessage callback method

Sends a text message to DMS/Pega args:

• CustomerID String - the customer_id of the person who's agent
• MessageID Unique id of the message returns:
• response.status the http status of the DMS api request
• response.statusText the text string status of the DMS api request. Example usage:

//Send a text message to DMS
dms.sendTextMessage(
  "CustomerID", //
  "MessageID", //Unique id of the message
  "Hello there!",
  "Customer Name",
  function (response) {
    //Return status from DMS
    return res.status(response.status).send(response.statusText);
  }
);

sendMessage callback method

Sends a message to DMS/Pega args:

• dms_message any valid DMS message object returns:
• response.status the http status of the DMS api request
• response.statusText the text string status of the DMS api request. Example usage:

//Send a text message to DMS
dms.sendMessage(dms_message, function (response) {
  //Return status from DMS
  return res.status(response.status).send(response.statusText);
});

TODO

• add license, author.

Issue Reporting

Author

License