Route a Conversation
Routes a newly-established conversation or transfers an existing conversation to a target participant, such as a rep, queue, bot, or Agentforce service agent.
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.
- 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.
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
Authorization: Bearer <Salesforce access token>
String. Standard header. The authorization token, where \<token\> is the JSON Web Token (JWT). Required.
Content-Type: <Request body format>
String. Standard header. The format of the request body. Valid format is multipart/form-data. Required.
OrgId: <Salesforce Org Id>
String. Standard header. The 15-character Org ID of the Salesforce org. Required.
AuthorizationContext: <ConversationChannel Definition developer name>
String. Standard header. The ConversationChannelDefinition developer name in the format {prefix}_{ConversationChannelDefinitionName}. The prefix must match the developer name prefix of the corresponding connected app. For example, Partner1_ChannelDefinition1. Required.
RequestId: <GUID>
String. Standard header. A globally unique ID (GUID). Required.
For example,
| 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 or one that’s being transferred. Valid values include: - Initial - A newly-established conversation. If set to Initial, this API executes the inbound Omni-Channel flow that’s associated with the conversation channel. Alternatively, you can pass in the target flow ID and fallback queue ID through routingInfo.flow. - Transfer - An existing conversation that’s being transferred. | 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 | If Bring Your Own Channel for CCaaS conversation routing is flow-based and you add support for custom parameters, set routingAtttributes to a key-value pair, where key is set to the channel variable name in the parameter mapping, and value is set to the name of the custom parameter in Salesforce. | Yes |
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