# 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 products: - Bring Your Own Channel for CCaaS - Bring Your Own Bot (BYOB) This API is available in version 61.0 and later. ## URI `v1/route` ## HTTP Method POST ## Headers ### Authorization (User-Level Authentication) **Format:** `Bearer `\ String. Standard header. Used to authenticate the user, where `` is the Salesforce access token used as the bearer token to make requests to the Interaction Service APIs. Required. ### Content-Type **Format:** `application/json`\ String. Standard header. Format of the request payload. Required for any request that includes a body. ### OrgId **Format:** ``\ String. Custom header. The Salesforce org. `` is the 15-character Org ID of the Salesforce org. Required. ### RequestId **Format:** ``\ String. Custom header. Universally Unique Identifier (``) that references and tracks this request. Required. ### AuthorizationContext **Format:** ``\ 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 `` to the developer name of the ConversationChannelDefinition record. For example, Partner1\_ChannelDefinition1. Required. - For Bring Your Own Bot (BYOB), set `` to the developer name of the ExtConvParticipantIntegDef record. For example, Partnerapp_ExtConvParticipantIntegDef. Required. ### AuthorizationContextType **Format:** ``\ String. Custom header. Specifies the type of context for the request. - For Bring Your Own Channel for CCaaS, set `` to **ConversationChannelDefinition**. - For Bring Your Own Bot (BYOB), set `` to **ExternalConversationParticipant**. ### Sample Header ``` -H $'Authorization: Bearer 00DSG000009SWby!...LN8XxeRIxGe' \ -H "content-type: application/json" \ -H "OrgId: 00DSG000009SWby" \ -H "AuthorizationContext: Partner1_ChannelDefinition1" \ -H "AuthorizationContextType: ConversationChannelDefinition" \ -H "RequestId: a1b23c45-c06a-4784-c96c-cb95d3321bda" \ ``` ## Parameters | 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](https://developer.salesforce.com/docs/service/messaging-byoc-ccaas/guide/add-custom-objects.md), 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 | ## Example ### Routing Based on the Messaging Channel Setting This example routes a conversation based on the routing preference that’s set in the Messaging channel. ```sfdocs-code {"lang":"json", "title": "Sample Payload" } { "conversationIdentifier": "1234a5bc-52b8-43ed-9608-7997f7b88dc1", "routingType": "Initial" } ``` ### Flow-Based Routing This example routes a conversation based on the flow ID and fallback queue ID, plus optional routing attributes: ```sfdocs-code {"lang":"json", "title": "Sample Payload" } { "conversationIdentifier": "1234a5bc-52b8-43ed-9608-7997f7b88dc1", "routingType": "Initial", "routingInfo": { "flow":{ "flowId": "301SG00000Oq1tR", "queueId": "00GSG000004PZNl" }, "routingAttributes": { "input_OrderNumber" : "SAR21jac17emi14" } } } ``` ### Queue-Based Routing This example routes a conversation based on the ID of the target queue: ```sfdocs-code {"lang":"json", "title": "Sample Payload" } { "conversationIdentifier": "1234a5bc-52b8-43ed-9608-7997f7b88dc1", "routingType": "Transfer", "routingInfo": { "queueId": "00GSG000004PZNl" } } ``` ## Bring Your Own Bot Routing Examples For Bring Your Own Bot (BYOB), the Route Conversation API routes the conversation through the bot integration’s external conversation participant context. Set the `AuthorizationContextType` header to `ExternalConversationParticipant` and the `AuthorizationContext` header to the developer name of the `ExtConvParticipantIntegDef` record. ### Sample Header ``` -H $'Authorization: Bearer 00DSG000009SWby!...LN8XxeRIxGe' \ -H "content-type: application/json" \ -H "OrgId: 00DSG000009SWby" \ -H "AuthorizationContext: Partnerapp_ExtConvParticipantIntegDef" \ -H "AuthorizationContextType: ExternalConversationParticipant" \ -H "RequestId: a1b23c45-c06a-4784-c96c-cb95d3321bda" \ ``` ### Initial Routing with Flow This example routes a newly-established BYOB conversation based on the flow ID and fallback queue ID. ```sfdocs-code {"lang":"json", "title": "Sample Payload" } { "conversationIdentifier": "1234a5bc-52b8-43ed-9608-7997f7b88dc1", "routingType": "Initial", "routingInfo": { "flow": { "flowId": "301SG00000Oq1tR", "queueId": "00GSG000004PZNl" } } } ``` ### Transfer to Queue This example transfers an existing BYOB conversation to a queue. ```sfdocs-code {"lang":"json", "title": "Sample Payload" } { "conversationIdentifier": "1234a5bc-52b8-43ed-9608-7997f7b88dc1", "routingType": "Transfer", "routingInfo": { "queueId": "00GSG000004PZNl" } } ``` ## See Also - *GitHub*: [Interaction Service APIs](https://github.com/salesforce-misc/interaction-service-apis) - *Bring Your Own Channel for CCaaS:* [Configure Partner-Owned Routing and Consent](https://developer.salesforce.com/docs/service/messaging-byoc-ccaas/guide/configure-partner-routing-consent.md) - *Bring Your Own Channel for CCaaS:* [Add Support for Custom Objects](https://developer.salesforce.com/docs/service/messaging-byoc-ccaas/guide/add-custom-objects.md) - *Salesforce Help*: [Route Data to Objects in Bring Your Own Channel](https://help.salesforce.com/s/articleView?id=service.partner_messaging_parameters.htm)