Establish a Conversation
Establishes a conversation and generates a conversation ID (conversationIdentifier) and messaging session ID (messagingSessionId).
The conversation channel address identifier (channelAddressIdentifier) combined with the end user client identifier (participants.subject) creates a new conversation.
If the API request doesn’t find a conversation corresponding to the passed in conversation channel and end user client identifier, a new conversation is created and a new conversationIdentifier value is returned. Similarly, if the API request doesn’t find a corresponding messaging session, a new messagingSessionId is returned.
If the API request finds a conversation corresponding to the conversation channel address identifier and end user client identifier that’s passed in, the existing conversationIdentifier value is returned. Similarly, it returns the existing messagingSessionId if one exists.
The conversationIdentifier value is used by other Interaction Service APIs to perform tasks, such as route conversations, create AgentWork records, and send historical conversation entries.
This API applies to the following products:
- Bring Your Own Channel for Contact Center as a Service
- Bring Your Own Channel for Messaging
This API is available in version 61.0 and later.
v1/conversation
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. - For Bring Your Own Channel for Messaging, set
<AuthorizationContext>to the developer name of the ConversationChannelDefinition record. For example, Partner1_ChannelDefinition1. Required. - don’t set this header.
| Property Name | Type | Description | Required |
|---|---|---|---|
| channelAddressIdentifier | string | The globally unique ID for the conversation channel (MessagingChannel.ChannelAddressIdentifier). | Yes |
| participants | string | A list of end user and rep participants in the conversation. | Yes |
| participants.subject | string | The end user client identifier. | Yes |
| participants.role | string | The role within the conversation. Set this value to EndUser. | Yes |
| participants.appType | string | The app type used for the conversation. Set this value to custom to represent a custom channel. | Yes |
| routingAttributes | object | An optional object containing custom data to use for routing the conversation. This data helps Salesforce direct the conversation to the most appropriate rep or queue. For Bring Your Own Channel for Messaging: - If you add support for custom parameters and call this API for an AI agent to initiate a conversation with proactive messaging, set routingAttributes to a key-value pair. 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. - If the messaging end user initiates the conversation instead, set routingAttributes in the Message Interaction API (/interactions). If conversation routing is partner-owned for Bring Your Own Channel for CCaaS and you add support for custom parameters, use the /route API to configure the routing attributes instead. | No |
- GitHub: Interaction Service APIs
- Bring Your Own Channel for CCaaS: Enable Third-Party Bots for a Partner Contact Center