--- schema_version: "1" id: dc2d3d991d73737e293877c0c349d71cb8c24e1a6575908284acdc8e4b0890cf title: Establish a Conversation collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/service-cloud/interaction-service-api/references/api-conversation.md canonical_url: https://developer.salesforce.com/docs/service/interaction-service-api/references/interaction-service-reference/api-conversation.html source_site: developer.salesforce.com content_type: documentation content_hash: a6c19da39dd5d5430ee18af9b519eadcd827365c28227f5b6aa896473466af54 products: - Interaction Service API - Service Cloud Developer Content --- # 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. ## URI `v1/conversation` ## 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 Channel for Messaging, set `` to the developer name of the ConversationChannelDefinition record. For example, Partner1_ChannelDefinition1. Required. ### Sample Header ``` -H $'Authorization: Bearer 00DSG000009SWby!...LN8XxeRIxGe' \ -H "content-type: application/json" \ -H "OrgId: 00DSG000009SWby" \ -H "AuthorizationContext: Partner1_ChannelDefinition1" \ -H "RequestId: a1b23c45-c06a-4784-c96c-cb95d3321bda" \ ``` ## Parameters | 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](https://developer.salesforce.com/docs/service/messaging-partner/guide/add-custom-objects.html) 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](/docs/service/interaction-service-api/references/interaction-service-reference/interaction-type-message.html) (`/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](https://developer.salesforce.com/docs/service/interaction-service-api/references/interaction-service-reference/api-route.md) to configure the routing attributes instead. | No | ## Example ### Request ```json { “channelAddressIdentifier”: “a12bc345-1303-44c2-866c-f30d546b58de” “participants”: [ { "subject”: “UserName01" "role”: “EndUser" "appType": "custom" } ], routingAttributes: { "newEndUserName" : "Sally Goforth" } } ``` ### Response ```json { "conversationIdentifier":"34ync34-34c34-v5v56n6-bn76n576" "messagingSessionId": "0MwSG00000BhyYr0A" "success":true } ``` ## See Also - _GitHub_: [Interaction Service APIs](https://github.com/salesforce-misc/interaction-service-apis) - _Bring Your Own Channel for CCaaS:_ [Enable Third-Party Bots for a Partner Contact Center](https://developer.salesforce.com/docs/service/messaging-byoc-ccaas/guide/third-party-bots.html)