Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Third-party routing

Updated on May 10, 2021

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.

Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide
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 SettingsChat 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.
      Note: 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.

Note: 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 connectorDescription
cyFetchExternalRouteSends the chat request metadata to the external routing system.
cyPostRoutingEventsSends 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 serviceDescription
PostRoutingEventsPerforms 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

NameRequired/OptionalDescription
_conversation_idRequiredThe chat or messaging request ID
_queue_nameRequiredThe queue ID where the request is processed
_sourceRequiredThe name of a chat channel or any supported unified messaging channel
_preferred_agentOptionalThe name of the preferred CSR who handled the chat previously if in an asynchronous channel
_priority_queuingRequiredRequest 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

ParameterRequired/OptionalDescription
_statusRequiredThe 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_timeOptionalThe average wait time for the request
_sourceRequiredThe name of a chat channel or any supported unified messaging channel
_queue_positionOptionalThe current position of the request

Example response

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

Error codes

Error codeDescription
400Bad request
500Server not found

Extension or customization points

Data transformPurposeAvailable pageParameters
ChannelServices-Conversation-Queued. cyParseConversationResquestAdds 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_timeAdds 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

ParameterRequired/OptionalDescription
_conversation_idOptionalThe chat or messaging request ID
_agent_nameRequiredThe name of the CSR who is assigned the request
_event_nameRequiredThe CSR action on the request
_queue_nameOptionalContains the queue ID where the request is processed
_sourceOptionalThe name of the channel from which the request originated

The source can be synchronous and asynchronous channels.

_transferred_from_agentOptionalThe name of the CSR who initiated the transfer
_ transferred_to_agentOptionalThe name of the CSR who received the transfer
_ transferred_to_queueOptionalThe name of the queue that received the transfer request
_ transferred_from_queueOptionalThe 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":"[email protected]",
   "_transferred_to_agent":"Sara",
   "_transferred_to_queue":"Technical",
   "_transferred_from_queue":"Billing"
}

Response parameters

ParameterRequired/OptionalDescription
_statusRequiredThe status of the transfer request (Success or Fail)

Example response

{
   "_status":"Success"
}
            

Error codes

Error codeDescription
400Bad request
500Server not found

Extension or customization points

Data transformPurposeAvailable pageParameters
ChannelServices-Int-Routing. cyParseEventsRequestExtnAdds 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.

For example: 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

ParameterRequired/OptionalDescription
_conversation_idRequiredThe chat or messaging request ID
_agent_idRequiredThe name of the CSR that is identified by the third-party routing system

Example request

{
   "_conversation_id":"3bc1c3b45ea911ea88f277fee9bcd8c0",
   "_agent_id":"[email protected]"
}

Response parameters

ParameterRequired/OptionalDescription
_status RequiredThe status of the transfer request (Success or Fail)

Example response

{
   "_status":"Success"
}
            

Error codes

Error codeDescription
400Bad request
500Server not found

Extension or customization points

Data transformPurposeAvailable pageParameters
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 nameDescription
QueueJoinedThe CSR log into queues and sets the status to available.

Example

{"_conversation_id":"",
 "_agent_name ":"[email protected]",
 "_ 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 ":"[email protected]",
"_ event_name":"QueuesJoined",
"_queue_name ":"",
"_source":"",
"_transferred_from_agent":"",
"_transferred_to_agent":"",
"_transferred_from_queue":"",
"_transferred_to_queue ":""}

Events once agent is identified

Event nameDescription
OfferedA 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":"[email protected]",
         "_ event_name":"Agent-Accepted",
         "_queue_name":"Billing",
         "_source":"chat",
         "_transferred_from_agent":"",
         "_transferred_to_agent":"",
         "_transferred_from_queue":"",
         "_transferred_to_queue ":""}
Agent-DeclinedThe 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 ":""}
ExpiredThe 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 ":"[email protected]",
               "_ event_name":"Conversation-Ended",
               "_queue_name ":"Billing",
               "_source":"chat",
               "_transferred_from_agent":"",
               "_transferred_to_agent":"",
               "_transferred_from_queue":"",
               "_transferred_to_queue ":""}  
Conversation-EndedThe 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 ":"[email protected]",
               "_ event_name":"Conversation-Ended",
               "_queue_name ":"Billing",
               "_source":"chat",
               "_transferred_from_agent":"",
               "_transferred_to_agent":"",
               "_transferred_afrom_queue":"",
               "_transferred_to_queue ":""}  
Conversation-EndedThe 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 ":"[email protected]",
               "_ event_name":"Conversation-Ended",
               "_queue_name ":"Billing",
               "_source":"chat",
               "_transferred_from_agent":"",
               "_transferred_to_agent":"",
               "_transferred_from_queue":"",
               "_transferred_to_queue ":""}  
Conversation-EndedThe 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 ":"[email protected]",
               "_ event_name":"Conversation-Ended",
               "_queue_name ":"Billing",
               "_source":"chat",
              "_transferred_from_agent":"",
              "_transferred_to_agent":"",
              "_transferred_from_queue":"",
              "_transferred_to_queue ":""}  
Conversation-EndedThe 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 ":"[email protected]",
               "_ event_name":"Conversation-Ended",
               "_queue_name ":"Billing",
               "_source":"chat",
               "_transferred_from_agent":"",
               "_transferred_to_agent":"",
               "_transferred_from_queue":"",
               "_transferred_to_queue ":""}
Agent-LoggedOffThe conversation is active, but the agent logs off.

Example

{"_conversation_id":"a9affee25e1611eaae862f3fa01a2a93",
               "_agent_name":"[email protected]",
               "_ event_name":"Agent-LoggedOff",
               "_queue_name":"Billing",
               "_source":"chat",
               "_transferred_from_agent":"",
               "_transferred_to_agent":"",
               "_transferred_from_queue":"",
               "_transferred_to_queue ":""} 

Agent transfer

Event nameDescription
Transfer-To-Agent-InitiatedThe transfer to an agent is initiated and the CSR is identified.

Example

{"_conversation_id":"724f0bb25dfa11eaaf242fbec29fb4c5",
"_agent_name ":"[email protected]",
"_ event_name":"TransferredtoAgent",
"_queue_name ":"Billing",
"_source":"chat",
"_transferred_from_agent":"[email protected]",
"_transferred_to_agent":"Laura",
"_transferred_from_queue":"Billing",
"_transferred_to_queue ":"Technical"}
Transfer-To-Agent-AcceptedThe 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":"[email protected]",
          "_transferred_to_agent":"Laura",
          "_transferred_from_queue":"Billing",
          "_transferred_to_queue ":"Technical"}
Transfer-To-Agent-DeclinedThe request is transferred and the identified CSR declines the request.

Example

{"_conversation_id":"781e788e5d5011eaa0b93f49ea39efd3",
          "_agent_name":"[email protected]",
          "_ 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-ExpiredThe 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":"[email protected]",
           "_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":"[email protected]",
          "_transferred_to_agent":"Laura",
          "_transferred_from_queue":"Billing",
          "_transferred_to_queue ":"Technical"}

Queue transfer

Event nameDescription
Transfer-To-Queue-InitiatedThe transfer to the queue is initiated, and the CSR is identified.

Example

{"_conversation_id":"c8f9cbfa5d4b11eaae27dbc8263ea31f",
         "_agent_name ":"[email protected]",
         "_ event_name":"Transfer-To-Queue-Initiated",
          "_queue_name ":"Billing",
          "_source":"chat",
          "TransferFromAgentID":"[email protected]",
          "TransferToAgentID":""}
Transfer-To-Queue-AcceptedThe 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":"[email protected]",
          "_transferred_to_agent":"Laura",
          "_transferred_from_queue":"Billing",
          "_transferred_to_queue ":"Technical"} 
Transfer-To-Queue-DeclinedThe transfer to the queue is successful, but the identified CSR declines the request.

Example

{"_conversation_id":"486bd29a5ddb11ea8fe5e72406874e0e",
          "_agent_name ":"[email protected]",
          "_ event_name":"Transfer-To-Queue-Declined",
          "_queue_name ":"Billing",
          "_source":"chat",
          "_transferred_from_agent":"Laura",
          "_transferred_to_agent":"[email protected]",
          "_transferred_from_queue":"Technical",
          "_transferred_to_queue ":"Billing"} 
Transfer-To-Queue-ExpiredThe request is transferred to a queue and the CSR is identified, but the request expires.

Example

{"_conversation_id":"486bd29a5ddb11ea8fe5e72406874e0e",
          "_agent_name ":"[email protected]",
          "_ event_name":"Transfer-To-Queue-Expired",
          "_queue_name ":"Billing",
          "_source":"chat",
          "_transferred_from_agent":"Laura",
          "_transferred_to_agent":"[email protected]",
          "_transferred_from_queue":"Technical",
          "_transferred_to_queue ":"Billing"} 
Transfer-To-Queue-AbandonedThe 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":"[email protected]",
          "_transferred_to_agent":"Laura",
          "_transferred_from_queue":"Billing",
          "_transferred_to_queue ":"Technical"}

Negative cases

Event nameDescription
Conversation-Ended/Customer Network DisconnectedThe conversation is active, but the customer has an unstable network or any other network issue.

Example

{"_conversation_id":"3fhl14e04wr514ea96140b756ec3290b",
          "_agent_name ":"[email protected]",
          "_ event_name":"Conversation-Ended",
          "_queue_name ":"Billing",
          "_source":"chat",
          "_transferred_from_agent":"",
          "_transferred_to_agent":"",
          "_transferred_from_queue":"",
          "_transferred_to_queue ":""} 
Conversation-Ended/Customer AbandonedThe 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 ":"[email protected]",
          "_ event_name":"Conversation-Ended",
          "_queue_name ":"Billing",
          "_source":"chat",
          "_transferred_from_agent":"",
          "_transferred_to_agent":"",
          "_transferred_from_queue":"",
          "_transferred_to_queue ":""}
Agent-NeworkDisconnectThe conversation is active, but there's a network disruption on the agent's side.

Example

{"_conversation_id":"c9f880e65eae11ea8fa4ab34045c802b",
          "_agent_name ":"[email protected]",
          "_ event_name":"Conversation-Ended",
           "_queue_name ":"Billing",
           "_source":"chat",
           "_transferred_from_agent":"",
           "_transferred_to_agent":"",
           "_transferred_from_queue":"",
           "_transferred_to_queue ":""} 
Agent-BrowserCloseThe conversation is active, but the CSR accidentally closes the browser.

Example

{"_conversation_id":"c9f880e65eae11ea8fa4ab34045c802b",
          "_agent_name":"[email protected]",
          "_ event_name":"Conversation-Ended",
          "_queue_name":"Billing",
          "_source":"chat",
          "_transferred_from_agent":"",
          "_transferred_to_agent":"",
          "_transferred_from_queue":"",
          "_transferred_to_queue ":""} 

Asynchronous cases

Event nameDescription
LongRunning-InteractionThe 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 nameDescription
RequeuingThe 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-RequeuingThe 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 ":""}

Have a question? Get answers now.

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

Did you find this content helpful?

Want to help us improve this content?

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

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us