General requirements

• Use a secure HTTPS channel for data transmission.
• Use JWT for requests signature. When using symmetric JWT keys, the Private Data API transmits these keys to customers by default during the credentials creation.
  Important:

  • The Web Messaging Service or the messaging service stores the exchanged data, with encryption at rest
  • The Web Messaging Service or the messaging service stores the exchanged data only for the duration of the chat session.

Customer authentication using private data

Digital Messaging Service provides a Private Data API through which the system sends the authentication-related data to the Pega Customer Service application in key-value pairs. Pega Customer Service application receives the data as customer_private_data (JSON) and stores the data into the pyCustomerPrivateData property along with the key-value pairs that the Digital Messaging Service sent.

For every message from the customer, the Pega Customer Service application calls the pyPreProcess activity, which can access the pyCustomerPrivateData property. This activity is used for authentication.

Authenticating customers

Configure the pxAuthenticate activity in the pyPreProcess activity to authenticate the required private data of the customer. To authenticate you need access to the API details. You can get access to the API details in the Pega Customer Service application using the key-value pairs in the pyPreProcess activity in Dev Studio.

1. Log into Dev Studio.
2. In the search box, search for the pyPreProcess activity of the Work-Channel-Interaction class, and then open the activity.
3. On the Steps tab of the pyPreProcess activity, perform the following steps:
   1. In the Step 2.1 when rule, depending on the key that you use, you get the corresponding value which is set up in the step as shown in the following figure:

      

   2. In the Step 3 when rule, the system displays the pxAuthenticate activity. The pxAuthenticate activity is to invoke authentication.
      Note: After the externalUserId value is identified, pxAuthenticate is invoked with the value of the externalUserId as a parameter to mark the customer as authenticated when the system sends the private data.

      

      Note: After the authentication is successful, the system calls the pyOnAuthenticationsuccess extension point, which can be overridden by the adding the client’s logic. The pyOnAuthenticationsuccess is available in the pxAuthenticate activity as shown in the following figure:

      

Customer Private Data API

Perform the following tasks using the Private Data API:

• Handling callback in Web Messaging on a customer website
• Handling callback in an Android customer app
• Handling callback in an iOS customer app
• Using the customer Private Data API for Web Messaging
• Using the customer Private Data API for Mobile Messaging SDKs

Handling callback in Web Messaging on a customer website

Whenever the chat customer starts a new chat session by clicking on the chat bubble, the chat widget will invoke the PegaUnifiedChatWidget.onSessionInitialized callback.

The callback receives the current session id as a parameter. The following code is an example of how the chat widget must handle the callback on a Pega customer's website where the widget is running:

<script  type="text/javascript">
if (typeof PegaUnifiedChatWidget   === 'undefined') 
 {
  var PegaUnifiedChatWidget   = {};
 }

PegaUnifiedChatWidget.onSessionInitialized  = (sessionId)  => {
 // custom customer logic to handle the sessionId console.log(sessionId);
}
</script>

Handling callback in an Android customer app

When you set the sessionIdCallback field as part of the chat configuration, the SDK sends the sessionId that you can use in the Private Data API.

Whenever the chat customer starts a new chat session, the Mobile Messaging SDK will invoke the sessionIdCallback.

The callback receives the current session id as a string parameter. The following code is an example of how the SDK must handle the callback on a Pega customer's app where the SDK is running:

    override fun configuration() = ChatConfiguration( 
    apiUrl = "…", 
    apiId =”…”, 
    customerToken = "…", 
    // sessionIdCallback field is optional 
    sessionIdCallback = ::sessionId 
) 
fun sessionId(id: String) { 
    Log.d("Session ID", "Session ID received $id") 

} 

Handling callback in an iOS customer app

When you set privateDataDelegate: PDMPrivateDataDelegate of the PDMChatViewController class to a viewController and implement the sessionInitialized delegate method, the SDK sends the sessionId that you can use in the Private Data API.

1. Assign privateDataDelegate of PDMChatViewController to your viewController .
2. Have the required view controller conform to the PDMPrivateDataDelegate
3. Implement the sessionInitialized function.

Whenever the chat customer starts a new chat session, the Mobile Messaging SDK will invoke the sessionInitialized callback method.

public protocol PDMPrivateDataDelegate: AnyObject { 
    /// A method you can implement to be notified when session is initalized 
    
func sessionInitialized(sessionID id: String) 
} 

Using the customer Private Data API for Web Messaging

After retrieving the chat session id, the Private Data API endpoint can transmit the private or sensitive data to the chat session in a secure way.

HTTP Endpoint: https://widget.use1dev.chat.pega.digital /private-data
Method: POST
Required header params: authorization:Bearer JWT
Body: JSONPayload

All requests to the private-data endpoint must be JWT signed.

Using the customer Private Data API for Mobile Messaging SDK

After retrieving the chat session id, the Private Data API endpoint can transmit the private or sensitive data to the chat session in a secure way.

HTTP Endpoint: apiUrl/private-data (e.g https://widget.use1dev.chat.pega.digital/private-data) 
Method: POST 
Required header params: authorization: Bearer JWT 
Body: JSON Payload 

All requests to the private-data endpoint must be JWT signed.

Generating a JWT to sign your request

To generate the JWT when issuing requests to the private data endpoint, the customer needs the chat sessionId (retrieved in the callback) and the JWT Secret. The customer uses the session id as the issuer (iss) parameter. You can retrieve the JWT Secret on the Security tab of the Digital Messaging Manager.

The following code is an example of how to create a JWT using the JavaScript library jsonwebtoken:

var JWT = jwt.sign({  iss: sessionId  }, JWT_SECRET);

The following code block is an example of how to transmit private data using the generated JWT:

var privateData  = { userId:  12345 }
var token = jwt.sign({ iss: sessionId  }, JWT_SECRET);
var url = “https://widget.use1dev.chat.pega.digital/private-data”
fetch(url, {
   method: 'POST',
   body: JSON.stringify(privateData), headers:  {
   'Content-Type':  'application/json',
   'authorization':  'Bearer ' + token},
}
); 

Receiving private data with the customer message

If the private data exchange call is successful, all the customer chat messages that the Private Data API delivers to Pega instances should contain the private data as follows:

{
"content": {
"text": "Hi, I need help with my order"
},
"customer_private_data":  { "userId":  12345
},
...
}