Skip to main content
LinkedIn
Copied!

Table of Contents

Third-party routing

If you have a shared pool of CSRs to attend Pega Call and Pega Customer Service chat and messaging requests, you can select this option to use the Pega Call routing services to route the chat and messaging requests.

When you select external routing, Pega Customer Service application redirects the queued chat requests to the configured external service URL as event notifications. The application also notifies the changes in the CSR availability to accept new requests. Pega Customer Service exposes a REST service over which the external routing system can communicate the final routing decision.

Enabling third-party routing

Enable third-party routing by performing the following steps:

  1. In the navigation pane of App Studio, click Settings Chat and messaging

  2. In the list of chat and messaging settings, click Routing.

  3. In the Disable Pega Routing section, select the Delegate Routing to non-pega routing services check box to delegate the routing of chat and messaging requests to an external routing service,

    1. In the Callback URL for incoming Chat requests field, enter the URL of the external routing system to send the metadata of the new chat and messaging requests that the routing system needs.

    2. In the Callback URL for CSR-presence updates field, enter the URL of the external routing system to send the updates on CSR availability and CSR or customer actions to route pending and transfer requests.

      Pega Customer Service uses the third-party routing API to exchange data with the external routing system.
      The external routing service URL has to be updated to czExternalRouteURL property in CSDefault settings data transform.
  4. Click Save.

Third-party routing API

With the Third-party routing API, you can use an external routing system for Pega Customer Service Legacy Webchat and Digital Messaging requests.

Update the external routing service URL with the czExternalRouteURL property in CSDefaultSettings data transform. In the CSDefaultSettings data transform provide the default values for the three properties:.czIsExternalRouting, .czRouteEventURL, and .czExternalRouteURL, if the values don't exist already. You can override these properties values from the third-party routing settings on the Routing page in AppStudio.

Third-party API REST connectors and REST services

The third-party routing API uses the following REST connectors and services:

Third-party API REST connectors

REST connector Description
cyFetchExternalRoute Sends the chat request metadata to the external routing system.
cyPostRoutingEvents Sends the CSR actions or the conversation changes to the external routing system after a CSR is offered the request.

Third-party API REST services

REST service Description
PostRoutingEvents Performs post-routing actions when a route is identified.

cyFetchExternalRoute connector

Use the czFetchExternalRoute to send the chat and messaging request metadata to an external routing system.

Request parameters

Name Required/Optional Description
_conversation_id Required The chat or messaging request ID
_queue_name Required The queue ID where the request is processed
_source Required The name of a chat channel or any supported unified messaging channel
_preferred_agent Optional The name of the preferred CSR who handled the chat previously if in an asynchronous channel
_priority_queuing Required Request will be given priority if the value is “true.”

Example request

{ "_conversation_id": "3bc1c3b45ea911ea88f277fee9bcd8c0",
                "_queue_name": "Billing",
                "_source": "Facebook",
                "_preferred_agent": "",
                "_priority_queuing": "true"
}

Response parameters

Parameter Required/Optional Description
_status Required The status of the routing activity

The following values are supported:

  • _identifying_route: The third-party routing system accepted the request and is searching for a CSR.
  • route_not_found: No CSRs are available to accept the request.
_wait_time Optional The average wait time for the request
_source Required The name of a chat channel or any supported unified messaging channel
_queue_position Optional The current position of the request

Example response

{
   "_status":"_identifying_route",
   "_wait_time":"",
   "_queue_position":""
}

Error codes

Error code Description
400 Bad request
500 Server not found

Extension or customization points

Data transform Purpose Available page Parameters
ChannelServices-Conversation-Queued. cyParseConversationResquest Adds more details to the request, such as a customer name or a customer policy number. Primary (ChannelServices-Conversation-Queued)
  • JSON data: The incoming or outgoing JSON data
  • Execution mode: The mode to execute mapping (Serialize or Deserialize)
ChannelServices-Conversation-Queued. cyParseConversationResponse_wait_time Adds more details to the response, such as queue capacity or an active agents count. Primary (ChannelServices-Conversation-Queued)
  • JSON data: The incoming or outgoing JSON data
  • Execution mode: The mode to execute the mapping (Serialize or Deserialize)

cyPostRoutingEvents connector

Use the cyPostRoutingEvents connector to send the updates on CSR availability and CSR or customer actions to the external routing system for routing pending and transfer requests.

Request parameters

Parameter Required/Optional Description
_conversation_id Optional The chat or messaging request ID
_agent_name Required The name of the CSR who is assigned the request
_event_name Required The CSR action on the request
_queue_name Optional Contains the queue ID where the request is processed
_source Optional The name of the channel from which the request originated

The source can be synchronous and asynchronous channels.

_transferred_from_agent Optional The name of the CSR who initiated the transfer
_ transferred_to_agent Optional The name of the CSR who received the transfer
_ transferred_to_queue Optional The name of the queue that received the transfer request
_ transferred_from_queue Optional The name of the queue from which the transfer originated

Example request

{
   "_conversation_id":"3bc1c3b45ea911ea88f277fee9bcd8c0",
   "_agent_name":"Sara",
   "_event_name":"Transfer-to-agent-accepted",
   "_queue_name":"Billing",
   "_source":"chat",
   "_transferred_from_agent":"lara@pegasystems.com",
   "_transferred_to_agent":"Sara",
   "_transferred_to_queue":"Technical",
   "_transferred_from_queue":"Billing"
}

Response parameters

Parameter Required/Optional Description
_status Required The status of the transfer request (Success or Fail)

Example response

{
   "_status":"Success"
}
            

Error codes

Error code Description
400 Bad request
500 Server not found

Extension or customization points

Data transform Purpose Available page Parameters
ChannelServices-Int-Routing. cyParseEventsRequestExtn Adds more details to the request, such as the current time stamp or the reason for transfer. Primary (ChannelServices-Conversation-Queued)
  • JSON data: The incoming or outgoing JSON data
  • Execution mode: The mode to execute the mapping (Serialize or Deserialize)

PostingRoutingEvents service

Use the PostingRoutingEvents service to perform post-routing activities after a route is identified.

The external routing system uses the following URL to access the PostingRoutingEvents service:

{{base_url}}/prweb/api/ConversationRouting/V1/PostRoutingEvents

{{base_url}} takes the value that is specific to the URL of the customer instance.

If the customer instance is http://10.225.93.236:9080/prweb/app/, then the {{base_url}} is http://10.225.93.236:9080.

Request parameters

Parameter Required/Optional Description
_conversation_id Required The chat or messaging request ID
_agent_id Required The name of the CSR that is identified by the third-party routing system

Example request

{
   "_conversation_id":"3bc1c3b45ea911ea88f277fee9bcd8c0",
   "_agent_id":"laura@pegasystems.com"
}

Response parameters

Parameter Required/Optional Description
_status Required The status of the transfer request (Success or Fail)

Example response

{
   "_status":"Success"
}
            

Error codes

Error code Description
400 Bad request
500 Server not found

Extension or customization points

Data transform Purpose Available page Parameters
ChannelServices-Conversation-Queued. cyParseConversationRouteResponse Adds more details, such as CSR capacity or CSR’s active interactions. Primary (ChannelServices-Conversation-Queued)
  • JSON data: The incoming or outgoing JSON data
  • Execution mode: The mode to execute the mapping (Serialize or Deserialize)

Third-party routing CSR events

The third-party routing API helps the CSR perform multiple events in Interaction Portal, such as joining queues, identifying agents, and transferring the case to agent or queues. The CSR can also work on negative cases, asynchronous cases, and requeuing cases.

Queue joining events

Event name Description
QueueJoined The CSR log into queues and sets the status to available.

Example

{"_conversation_id":"",
 "_agent_name ":"sara@pegasystems.com",
 "_ event_name":"QueuesJoined", 
"_queue_name":";Billing;;Technical;",
"_source":"",
"_transferred_from_agent":"",
"_transferred_to_agent":"",
"_transferred_from_queue":"",
 "_transferred_to_queue ":""}
QueueJoined but queue name will be empty. The CSR has logged in but remains unavailable for all queues.

Example

{"_conversation_id":"",
"_agent_name ":"sara@pegasystems.com",
"_ event_name":"QueuesJoined",
"_queue_name ":"",
"_source":"",
"_transferred_from_agent":"",
"_transferred_to_agent":"",
"_transferred_from_queue":"",
"_transferred_to_queue ":""}

Events once agent is identified

Event name Description
Offered A request from the customer is displayed as a chat pop-up and the CSR is identified.

Example

{"_conversation_id":
            "BotAgenta3256c9e885f48819dade129c245f2c9_1426819",
          "_agent_name ":"Sarah",
          "_ event_name":"Offered", 
          "_queue_name ":"Billing",
          "_source":"Facebook",
          "_transferred_from_agent":"",
          "_transferred_to_agent":"",
          "_transferred_from_queue":"",
           "_transferred_to_queue ":""}
Agent-Accepted The customer makes the request, and the request is displayed as a chat pop-up, which the identified CSR accepts.

Example

{"_conversation_id":"f04439e85ea411ea9c3583173b58cc69",
         "_agent_name":"sarah@pegasystems.com",
         "_ event_name":"Agent-Accepted",
         "_queue_name":"Billing",
         "_source":"chat",
         "_transferred_from_agent":"",
         "_transferred_to_agent":"",
         "_transferred_from_queue":"",
         "_transferred_to_queue ":""}
Agent-Declined The customer makes the request, and the request is displayed as a chat pop-up, but the identified CSR declines the request.

Example

{"_conversation_id":
                 "BotAgenta3256c9e885f48819dade129c245f2c9_1449198",
               "_agent_name ":"Sarah",
               "_ event_name":"Agent-Declined",
               "_queue_name ":"Billing",
               "_source":"Facebook",
               "_transferred_from_agent":"",
               "_transferred_to_agent":"",
               "_transferred_from_queue":"",
               "_transferred_to_queue ":""}
Expired The CSR is identified. The request from the customer is displayed as a chat pop-up, but the request expires.

Example

{"_conversation_id":
                 "84c5e3e85ed011ea8bddc75183dd79c8",
               "_agent_name ":"Sarah",
               "_ event_name":"ValidatePublish",
               "_queue_name ":"Billing",
               "_source":"chat",
               "_transferred_from_agent":"",
               "_transferred_to_agent":"",
               "_transferred_from_queue":"",
               "_transferred_to_queue ":""}
Conversation-Ended The CSR is identified. The request from the customer is displayed as a chat pop-up, but the customer ends the chat before the CSR action.

Example

{"_conversation_id":
                   "4aea63d05df211ea96270b756ec8016c",
               "_agent_name ":"sarah@pegasystems.com",
               "_ event_name":"Conversation-Ended",
               "_queue_name ":"Billing",
               "_source":"chat",
               "_transferred_from_agent":"",
               "_transferred_to_agent":"",
               "_transferred_from_queue":"",
               "_transferred_to_queue ":""}  
Conversation-Ended The CSR is identified. The request from the customer is displayed as a chat pop-up, but the customer ends the interaction by closing the interaction tab.

Example

{"_conversation_id":
                   "8sdf21r12df211ea96270b756ec2091s",
               "_agent_name ":"sarah@pegasystems.com",
               "_ event_name":"Conversation-Ended",
               "_queue_name ":"Billing",
               "_source":"chat",
               "_transferred_from_agent":"",
               "_transferred_to_agent":"",
               "_transferred_afrom_queue":"",
               "_transferred_to_queue ":""}  
Conversation-Ended The CSR is identified. The request from the customer is displayed as a chat pop-up, but the customer ends the interaction by wrapping up.

Example

{"_conversation_id":"2awe23f04df312ea96230b756ec1786d",
               "_agent_name ":"sarah@pegasystems.com",
               "_ event_name":"Conversation-Ended",
               "_queue_name ":"Billing",
               "_source":"chat",
               "_transferred_from_agent":"",
               "_transferred_to_agent":"",
               "_transferred_from_queue":"",
               "_transferred_to_queue ":""}  
Conversation-Ended The CSR is identified. The request from the customer is displayed as a chat pop-up, but the chat comes to end when the CSR ends the chat.

Example

{"_conversation_id":"4beb27s06ed2013a43270b756ec6210c",
               "_agent_name ":"sarah@pegasystems.com",
               "_ event_name":"Conversation-Ended",
               "_queue_name ":"Billing",
               "_source":"chat",
              "_transferred_from_agent":"",
              "_transferred_to_agent":"",
              "_transferred_from_queue":"",
              "_transferred_to_queue ":""}  
Conversation-Ended The CSR is identified. The request from the customer is displayed as a chat pop-up, but the chat ends when the customer ends the chat.

Example

{"_conversation_id":"4aea63d05df211ea96270b756ec8016c",
               "_agent_name ":"sarah@pegasystems.com",
               "_ event_name":"Conversation-Ended",
               "_queue_name ":"Billing",
               "_source":"chat",
               "_transferred_from_agent":"",
               "_transferred_to_agent":"",
               "_transferred_from_queue":"",
               "_transferred_to_queue ":""}
Agent-LoggedOff The conversation is active, but the agent logs off.

Example

{"_conversation_id":"a9affee25e1611eaae862f3fa01a2a93",
               "_agent_name":"sarah@pegasystems.com",
               "_ event_name":"Agent-LoggedOff",
               "_queue_name":"Billing",
               "_source":"chat",
               "_transferred_from_agent":"",
               "_transferred_to_agent":"",
               "_transferred_from_queue":"",
               "_transferred_to_queue ":""} 

Agent transfer

Event name Description
Transfer-To-Agent-Initiated The transfer to an agent is initiated and the CSR is identified.

Example

{"_conversation_id":"724f0bb25dfa11eaaf242fbec29fb4c5",
"_agent_name ":"sarah@pegasystems.com",
"_ event_name":"TransferredtoAgent",
"_queue_name ":"Billing",
"_source":"chat",
"_transferred_from_agent":"sarah@pegasystems.com",
"_transferred_to_agent":"Laura",
"_transferred_from_queue":"Billing",
"_transferred_to_queue ":"Technical"}
Transfer-To-Agent-Accepted The request is transferred and the identified CSR accepts the request.

Example

{"_conversation_id":"781e788e5d5011eaa0b93f49ea39efd3",
          "_agent_name ":"Laura",
          "_ event_name":"Transfer-To-Agent-Accepted",
          "_queue_name ":"Technical",
          "_source":"chat",
          "_transferred_from_agent":"sarah@pegasystems.com",
          "_transferred_to_agent":"Laura",
          "_transferred_from_queue":"Billing",
          "_transferred_to_queue ":"Technical"}
Transfer-To-Agent-Declined The request is transferred and the identified CSR declines the request.

Example

{"_conversation_id":"781e788e5d5011eaa0b93f49ea39efd3",
          "_agent_name":"sarah@pegasystems.com",
          "_ event_name":"Transfer-To-Agent-Declined",
          "_queue_name ":"Billing",
          "_source":"chat",
          "_transferred_from_agent":"Laura",
          "_transferred_to_agent":"",
          "_transferred_from_queue":"Technical",
          "_transferred_to_queue ":""}
Transfer-To-Agent-Expired The request is transferred, and the CSR is identified, but the request expires.

Example

{"_conversation_id":"3656a4345eaa11ea9f11571826868be0",
          "_agent_name ":"Laura",
          "_ event_name":"Transfer-To-Agent-Expired",
          "_queue_name ":"Technical",
           "_source":"chat",
           "_transferred_from_agent":"sarah@pegasystems.com",
           "_transferred_to_agent":"Laura",
           "_transferred_from_queue":"Billing",
           "_transferred_to_queue ":"Technical"}
Transfer-To-Agent-Abandoned The request is transferred, and the CSR is identified, but the customer ends the chat before the CSR action. This scenario is called "Abandoned."

Example

{"_conversation_id":"3bc1c3b45ea911ea88f277fee9bcd8c0",
          "_agent_name ":"Laura",
          "_ event_name":"Transfer-To-Agent-Abandoned",
          "_queue_name ":"Technical",
          "_source":"chat",
          "_transferred_from_agent":"sarah@pegasystems.com",
          "_transferred_to_agent":"Laura",
          "_transferred_from_queue":"Billing",
          "_transferred_to_queue ":"Technical"}

Queue transfer

Event name Description
Transfer-To-Queue-Initiated The transfer to the queue is initiated, and the CSR is identified.

Example

{"_conversation_id":"c8f9cbfa5d4b11eaae27dbc8263ea31f",
         "_agent_name ":"sarah@pegasystems.com",
         "_ event_name":"Transfer-To-Queue-Initiated",
          "_queue_name ":"Billing",
          "_source":"chat",
          "TransferFromAgentID":"sarah@pegasystems.com",
          "TransferToAgentID":""}
Transfer-To-Queue-Accepted The transfer to the queue is successful, and the identified CSR accepts the request.

Example

{"_conversation_id":"486bd29a5ddb11ea8fe5e72406874e0e",
          "_agent_name ":"Laura",
          "_ event_name":"Transfer-To-Queue-Accepted",
          "_queue_name ":"Technical",
          "_source":"chat",
          "_transferred_from_agent":"sarah@pegasystems.com",
          "_transferred_to_agent":"Laura",
          "_transferred_from_queue":"Billing",
          "_transferred_to_queue ":"Technical"} 
Transfer-To-Queue-Declined The transfer to the queue is successful, but the identified CSR declines the request.

Example

{"_conversation_id":"486bd29a5ddb11ea8fe5e72406874e0e",
          "_agent_name ":"sarah@pegasystems.com",
          "_ event_name":"Transfer-To-Queue-Declined",
          "_queue_name ":"Billing",
          "_source":"chat",
          "_transferred_from_agent":"Laura",
          "_transferred_to_agent":"sarah@pegasystems.com",
          "_transferred_from_queue":"Technical",
          "_transferred_to_queue ":"Billing"} 
Transfer-To-Queue-Expired The request is transferred to a queue and the CSR is identified, but the request expires.

Example

{"_conversation_id":"486bd29a5ddb11ea8fe5e72406874e0e",
          "_agent_name ":"sarah@pegasystems.com",
          "_ event_name":"Transfer-To-Queue-Expired",
          "_queue_name ":"Billing",
          "_source":"chat",
          "_transferred_from_agent":"Laura",
          "_transferred_to_agent":"sarah@pegasystems.com",
          "_transferred_from_queue":"Technical",
          "_transferred_to_queue ":"Billing"} 
Transfer-To-Queue-Abandoned The request is transferred to a queue and the CSR is identified, but the customer ends the chat before the CSR action.

Example

{"_conversation_id":"3b00aab05eab11eaba2b9b6b99bd5233",
          "_agent_name ":"Laura",
          "_ event_name":"Transfer-To-Queue-Abandoned",
          "_queue_name ":"Technical",
          "_source":"chat",
          "_transferred_from_agent":"sarah@pegasystems.com",
          "_transferred_to_agent":"Laura",
          "_transferred_from_queue":"Billing",
          "_transferred_to_queue ":"Technical"}

Negative cases

Event name Description
Conversation-Ended/Customer Network Disconnected The conversation is active, but the customer has an unstable network or any other network issue.

Example

{"_conversation_id":"3fhl14e04wr514ea96140b756ec3290b",
          "_agent_name ":"sarah@pegasystems.com",
          "_ event_name":"Conversation-Ended",
          "_queue_name ":"Billing",
          "_source":"chat",
          "_transferred_from_agent":"",
          "_transferred_to_agent":"",
          "_transferred_from_queue":"",
          "_transferred_to_queue ":""} 
Conversation-Ended/Customer Abandoned The conversation is active, but the customer accidentally closes the browser or has a network issue, and the chat gets disconnected.

Example

{"_conversation_id":"b3f24b585eac11eaa746b7b5cb19d100",
          "_agent_name ":"sarah@pegasystems.com",
          "_ event_name":"Conversation-Ended",
          "_queue_name ":"Billing",
          "_source":"chat",
          "_transferred_from_agent":"",
          "_transferred_to_agent":"",
          "_transferred_from_queue":"",
          "_transferred_to_queue ":""}
Agent-NeworkDisconnect The conversation is active, but there's a network disruption on the agent's side.

Example

{"_conversation_id":"c9f880e65eae11ea8fa4ab34045c802b",
          "_agent_name ":"sarah@pegasystems.com",
          "_ event_name":"Conversation-Ended",
           "_queue_name ":"Billing",
           "_source":"chat",
           "_transferred_from_agent":"",
           "_transferred_to_agent":"",
           "_transferred_from_queue":"",
           "_transferred_to_queue ":""} 
Agent-BrowserClose The conversation is active, but the CSR accidentally closes the browser.

Example

{"_conversation_id":"c9f880e65eae11ea8fa4ab34045c802b",
          "_agent_name":"sarah@pegasystems.com",
          "_ event_name":"Conversation-Ended",
          "_queue_name":"Billing",
          "_source":"chat",
          "_transferred_from_agent":"",
          "_transferred_to_agent":"",
          "_transferred_from_queue":"",
          "_transferred_to_queue ":""} 

Asynchronous cases

Event name Description
LongRunning-Interaction The conversation is active, but the CSR closes the browser due to a network issue and closes the interaction, but the customer messages come up (toaster pop-up).

Example

{"_conversation_id":"BotAgenta3256c9e885f48819dade129c245f2c9_1427039",
          "_agent_name ":"Sarah",
          "_ event_name":" LongRunning-Interaction",
          "_queue_name ":"Billing",
          "_source":"Facebook",
          "_transferred_from_agent":"",
          "_transferred_to_agent":"",
          "_transferred_from_queue":"",
          "_transferred_to_queue ":""}

Requeuing cases

Event name Description
Requeuing The request is requeued.

Example

{"_conversation_id":"BotAgenta3256c9e885f48819dade129c245f2c9_1427039",
          "_agent_name ":"Sarah",
          "_ event_name":"Requeuing",
          "_queue_name ":"Billing",
          "_source":"Facebook",
          "_transferred_from_agent":"",
          "_transferred_to_agent":"",
          "_transferred_from_queue":"",
          "_transferred_to_queue ":""}
Priority-Requeuing The request is requeued on priority.

Example

{"_conversation_id":"BotAgenta3256c9e885f48819dade129c245f2c9_1427039",
          "_agent_name ":"sarah",
          "_ event_name":"Priority-Requeuing",
          "_queue_name ":"Billing",
          "_source":"Facebook",
          "_transferred_from_agent":"",
          "_transferred_to_agent":"",
          "_transferred_from_queue":"",
          "_transferred_to_queue ":""}
Suggest Edit
Did you find this content helpful?

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.

Ready to crush complexity?

Experience the benefits of Pega Community when you log in.

We'd prefer it if you saw us at our best.

Pega Community has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice
Contact us