Route a Conversation
Routes a newly-established conversation, transfers an existing conversation to a target participant, such as a rep, queue, bot, or Agentforce service agent, or adds more callers to an existing conversation through conferencing.
Only use this API if routing is partner-owned (if ConversationChannelDefinition.routingOwner is set to Partner).
When routing starts, a pending service routing (PSR) record is created. The PSR record is a Salesforce object that gets created when work is routed. The PSR is a transient object that contains routing information about a work item that’s in the midst of being routed. Once a rep accepts the work, the PSR record is deleted. If the PSR record isn’t automatically deleted, call the DELETE /route API to delete it.
How this API is called depends on the information it uses to route the conversation:
- Routing based on the Messaging channel setting–Defer to the routing preference that’s set in the Messaging channel by the Salesforce admin. This is the recommended approach.
- Flow-based routing–Route the conversation based on the specified flow ID and fallback queue ID that’s specified in the payload.
- Queue-based routing–Route the conversation based on the target queue ID that’s specified in the payload.
If routing information is set in the Messaging channel as well as being passed using the routingInfo object in this API, the API takes precedence over the Omni-Channel Routing Messaging channel setting.
This API applies to the following product:
- Bring Your Own Channel for Contact Center as a Service
This API is available in version 61.0 and later.
v1/route
POST
Format: Bearer <Salesforce Access Token>
String. Standard header. Used to authenticate the user, where <Salesforce Access Token> is the Salesforce access token used as the bearer token to make requests to the Interaction Service APIs. Required.
Format: application/json
String. Standard header. Format of the request payload. Required for any request that includes a body.
Format: <Salesforce Org ID>
String. Custom header. The Salesforce org. <Salesforce Org ID> is the 15-character Org ID of the Salesforce org. Required.
Format: <UUID>
String. Custom header. Universally Unique Identifier (<UUID>) that references and tracks this request. Required.
Format: <AuthorizationContext>
String. Custom header. Additional information for the request authorization used to authenticate and validate requests against the connected app scopes.
- For Bring Your Own Channel for CCaaS, set
<AuthorizationContext>to the developer name of the ConversationChannelDefinition record. For example, Partner1_ChannelDefinition1. Required. - don’t set this header.
Format: <AuthorizationContextType>
String. Custom header. Specifies the type of context for the request.
- For Bring Your Own Channel for CCaaS, set
<AuthorizationContextType>to ConversationChannelDefinition.
| Property Name | Type | Description | Required |
|---|---|---|---|
| conversationIdentifier | string | The unique ID for the conversation channel. | Yes |
| routingType | string | Determines whether the conversation that’s being routed is a new conversation, one that’s being transferred, or one that’s bringing in more participants through conferencing. Valid values include: - Initial - A newly-established conversation. - Transfer - An existing conversation that’s being transferred. - Conference - An existing conversation that’s bringing in more participants through conferencing. This value is required if routingContext is required. | Yes |
| routingInfo | object | The routing details, including flow details, specifying how a conversation is routed. This object is only required for newly-established conversations (“routingType” : “Initial”). Conversation routing can be based on an Omni-Channel flow that’s configured in the Messaging channel, flow-based (based on the flow ID and fallback queue ID), or queue-based (based on the target queue ID). If conversation routing is based on an Omni-Channel flow that’s configured in the Messaging channel, don’t include this object. If conversation routing is flow-based, include the flow.flowId and flow.queueId parameters. If conversation routing is based on the queue ID, set the queueId parameter. | No |
| routingInfo.flow | object | If conversation routing is flow-based, set flowId to the unique ID of the FlowDefinitionView record, and set queueId to the ID of the fallback queue. You can also include optional routing attributes. | Yes |
| routingInfo.queueId | string | If conversation routing is queue-based, set this value to the ID of the target queue. | Yes |
| routingInfo.routingAttributes | object | An optional object containing custom data to use for routing the conversation. If Bring Your Own Channel for CCaaS conversation routing is flow-based and you add support for custom parameters, set routingAttributes to a key-value pair, where key is set to the channel variable name in the parameter mapping, and value is set to the value of the custom parameter in Salesforce. The value length must be less than or equal to the Maximum Length that the Salesforce admin set for the custom parameter in Messaging Settings. | No |
This example routes a conversation based on the routing preference that’s set in the Messaging channel.
This example routes a conversation based on the flow ID and fallback queue ID, plus optional routing attributes:
This example routes a conversation based on the ID of the target queue:
- GitHub: Interaction Service APIs
- Bring Your Own Channel for CCaaS: Configure Partner-Owned Routing and Consent
- Bring Your Own Channel for CCaaS: Add Support for Custom Objects
- Salesforce Help: Route Data to Objects in Bring Your Own Channel