Send Historical Conversation Entries

Sends historical conversation entries between an end user and a third-party bot to Salesforce. If any of the historical conversations include file attachments, those are sent as well.

This API applies to the following product:

Bring Your Own Channel for Contact Center as a Service

This API is available in version 63.0 and later.

When you call this API for the first time, a messaging session ID is sent with the response, which you can use to route the conversation from a bot. While routing is in progress, you can continue to call this API using the same session ID to complete the upload.

This endpoint can send up to five conversation entries for a maximum of three messaging session participants at one time.

Upload the transcript in reverse order, first uploading the latest message and then earlier messages. This helps the rep see the latest conversation in case routing happens before the entire transcript is uploaded.

Tip

To send a file attachment, such as PDF documents, images, and video recordings, upload the file to Salesforce and then pass the attachment information using the conversationEntries.entryPayload parameter.

Limitations

This API has the following limitations:

A 30-minute cache window after conversation close (MultiConversations channels only). After a successful history import on a MultiConversations channel, Messaging Conversation Service (MCS) caches the conversation ID for up to 30 minutes. If you call the API again within that window for the same user, MCS reuses the cached ID instead of creating a new one. Your request fails with error 10078 because the new entry timestamps fall outside the closed conversation’s time window. This limitation doesn’t apply to SingleConversation channels, where the system always generates a new UUID for each conversation.
You can’t pass a conversationId in the request body on subsequent requests. As a result, you can’t explicitly specify which conversation the entries are written to.
This API isn’t available for accounts onboarded to Bring Your Own Bot (BYOB). To sync conversation entries with Salesforce, BYOB uses a real-time mechanism rather than uploading all entries at the end of the conversation.

Conversation Cardinality

The conversationCardinality field on the channel address controls whether a channel supports one active conversation per end user at a time or multiple concurrent conversations.

Value	Description	Channels
SingleConversation	One active conversation per end user at a time. The system ignores any provided conversation ID and generates a new UUID. Exception: Email preserves the provided ID.	Text (SMS), Facebook, LINE, Apple Business Chat, WeChat, WhatsApp, Custom (BYOC), RCS
MultiConversations	Multiple concurrent conversations per end user. The system preserves the conversation ID from the request. Requires `clientNamespace` to be configured on the channel address.	Embedded Messaging, Email, MsCopilot

URI

v1/conversationHistory

HTTP Method

POST

Headers

Authorization (User-Level Authentication)

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.

Content-Type

Format: application/json
String. Standard header. Format of the request payload. Required for any request that includes a body.

OrgId

Format: <Salesforce Org ID>
String. Custom header. The Salesforce org. <Salesforce Org ID> is the 15-character Org ID of the Salesforce org. Required.

RequestId

Format: <UUID>
String. Custom header. Universally Unique Identifier (<UUID>) that references and tracks this request. Required.

AuthorizationContext

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.

AuthorizationContextType

Format: <AuthorizationContextType>
String. Custom header. Specifies the type of context for the request.

For Embedded Messaging, set <AuthorizationContextType> to EmbeddedMessagingChannel.
For Bring Your Own Channel for CCaaS, set <AuthorizationContextType> to ConversationChannelDefinition.

Sample Header

1-H $'Authorization: Bearer 00DSG000009SWby!...LN8XxeRIxGe' \
2-H "content-type: application/json" \
3-H "OrgId: 00DSG000009SWby" \
4-H "AuthorizationContext: Partner1_ChannelDefinition1" \
5-H "AuthorizationContextType: ConversationChannelDefinition" \
6-H "RequestId: a1b23c45-c06a-4784-c96c-cb95d3321bda" \

Parameters

Property Name	Type	Description	Required
channelAddressIdentifier	string	The globally unique ID (GUID) for the conversation channel (MessagingChannel.ChannelAddressIdentifier) field. Maximum size is 240 characters.	Yes
conversationParticipants	array	A list of participants in the conversation.	Yes
conversationParticipants.displayName	string	The name of the participant. The name, along with the timestamp, appears below each conversation entry in the Conversation UI to identify the participant.	Yes
conversationParticipants.participant	string	A description of the participant in the conversation. The `subject` represents the unique ID for the end user on the customer’s client side. The `role` represents the participant type. Valid values are: - EndUser for an end user participant. - Chatbot for a bot. The `appType` represents the type of app used by the conversation and must be set to custom.	Yes
conversationParticipant. joinedTime	string	The date and time when the participant joined the conversation.	Yes
conversationParticipants.leftTime	string	If the participant is a bot, this value represents the date and time when the bot left the conversation. A conversation can only be routed with one active caller. In this case, before the conversation can be routed to a rep, the bot must leave the conversation so the end user–the remaining active caller–can be routed. If the participant is EndUser, don’t set this field.	No
conversationEntries	object	A list of conversation entries between the end user and third party bot participants within the conversation. Each conversation entry is a message, which can be of format type text or file attachment. Each request can include up to five conversation entries. For file attachments, see conversationEntries Payload for details on how to configure this object.	Yes
messagingSession	object	The details for the messaging session.	No
messagingSession.messagingSessionRequestType	string	Determines whether to create a new messaging session with this historical conversation entry or attach this historical conversation entry to an existing messaging session. Valid values include: - EstablishMessagingSession - Create a new messaging session. If set, you must set `startTime` and optionally set `endTime`. - AttachMessagingSession - Attach this conversation entry to an existing messaging session, If set, you must set `sessionId`.	Yes
messagingSession.payload	object	The payload for the messaging session.	Yes
messagingSession.payload.startTime	string	If `messagingSession.messagingSessionRequestType` is set to EstablishMessagingSession, set this value to the date and time when the messaging session started.	Yes
messagingSession.payload.endTime	string	If `messagingSession.messagingSessionRequestType` is set to EstablishMessagingSession, set this value to the date and time when the messaging session ended. If this value isn’t set, the messaging session remains open.	No
messagingSession.payload.sessionId	string	If `messagingSession.messagingSessionRequestType` is set to AttachMessagingSession, set this value to the unique ID of the MessagingSession record to which this historical conversation entry is attached.	Yes

conversationEntries Payload

Configure the conversation entries (conversationEntries) for file attachments.

Property Name	Type	Description	Required
clientTimestamp	int64	The date and time when the conversation entry was sent.	Yes
sender	string	The sender in the conversation entry. The `subject` represents the unique ID for the end user (endClientUserId) or bot (chatbotId) on the customer’s client side. The `role` represents the participant type and must be set to EndUser for the end user participant or Chatbot for the third party bot. The `appType` represents the type of app used in the conversation and must be set to custom to represent a custom channel.	Yes
entryPayload	object	The content of the conversation entry.	Yes
entryPayload.entryType	string	The payload representing the type of conversation entry. Always set this value to Message.	Yes
entryPayload.id	string	A unique ID for the interaction. Maximum size is 36 characters. This value must match the `entryPayload.abstractMessage.id` value in this payload.	Yes
entryPayload.abstractMessage	object	The message details.	Yes
entryPayload.abstractMessage.messageType	string	The message type for the interaction. Set this value to StaticContentMessage.	Yes
entryPayload.abstractMessage.id	string	A unique ID for the interaction. This value must match the `entryPayload.id` value in this payload.	Yes
entryPayload.abstractMessage.staticContent	object	The details for the static content. For messages, set `formatType` to Text, and set text to the message content. For file attachments, see staticContent Settings for File Attachments for details on how to configure this object.	Yes
entryPayload.abstractMessage.inReplyToMessageId	string	For messages, don’t set this parameter. For file attachments, set this value to the MessageId of the message being replied to.	Yes
entryPayload.abstractMessage.references	object	For messages, don’t set this parameter. For file attachments, set `recordId` to the unique ID of the `ContentVersion` record for the file. The record ID is 15 characters long. The record ID is also in the URL of the file attachment. Set `id` to a unique ID for the interaction. This value must match the `entryPayload.abstractMessage.staticContent.attachments.id` value in this payload.	Yes

staticContent Settings for File Attachments

Configure the static content (entryPayload.abstractMessage.staticContent) details for messages and file attachments.

Property Name	Type	Description
formatType	string	The type of static content. For file attachments, set this value to Attachments.
text	string	The message that’s sent with the attachment. If the attachment is sent without text, set this value to null.
attachments	object	The details for the file attachment.
attachments.name	string	The filename of the file attachment.
attachments.attachmentUploadResult	string	The result of the attachment upload for mobile-originated messages.
attachments.id	string	A unique ID for the interaction. This value must match the `conversationEntries.entryPayload.abstractMessage.references.id` value in this payload.
attachments.mimeType	string	The non-ASCII or binary file type of the file. For example, `“mimeType": "image/jpeg"`.
attachments.url	string	The URL location of the uploaded file.
attachments.referenceId	string	The unique ID of the associated `FlowDefinitionView` record.

Example

Request

1{
2  "channelAddressIdentifier": "c05a3a16-0179-4a83-9460-10eae3208164",
3  "conversationParticipants": [
4    {
5      "displayName": "",
6      "participant": {
7        "subject": "end-user-0001",
8        "role": "EndUser",
9        "appType": "custom"
10      },
11      "joinedTime": "1732182671000"
12    },
13    {
14      "displayName": "The Chatbot",
15      "participant": {
16        "subject": "Omx000000O3YTR",
17        "role": "Chatbot",
18        "appType": "custom"
19      },
20      "joinedTime": "1732182791000",
21      "leftTime": "1732183151000"
22    }
23  ],
24  "conversationEntries": [
25    {
26      "clientTimestamp": "1732182791000",
27      "entryPayload": {
28        "entryType": "Message",
29        "id": "20c18c3c-e119-4f1b-bff8-4e196fd92876",
30        "abstractMessage": {
31          "messageType": "StaticContentMessage",
32          "id": "20c18c3c-e119-4f1b-bff8-4e196fd92876",
33          "staticContent": {
34            "formatType": "Text",
35            "text": "My burr coffee grinder is making a weird sound."
36          }
37        }
38      },
39      "sender": {
40        "subject": "end-user-0001",
41        "role": "EndUser",
42        "appType": "custom"
43      }
44    },
45    {
46      "clientTimestamp": "1732182671000",
47      "entryPayload": {
48        "entryType": "Message",
49        "id": "ba042a99-0577-4444-b26c-318874c76c0c",
50        "abstractMessage": {
51          "messageType": "StaticContentMessage",
52          "id": "ba042a99-0577-4444-b26c-318874c76c0c",
53          "staticContent": {
54            "formatType": "Text",
55            "text": "Does it make the same sound when you adjust the grind size?"
56          }
57        }
58      },
59      "sender": {
60        "subject": "Omx000000O3YTR",
61        "role": "Chatbot",
62        "appType": "custom"
63      }
64    }
65  ],
66    "messagingSession": {
67        "messagingSessionRequestType": "EstablishMessagingSession",
68        "payload": {
69            "startTime": "1732182671000",
70            "endTime": "1732182671000"
71        }
72    }
73}

1{
2  "channelAddressIdentifier": "c05a3a16-0179-4a83-9460-10eae3208164",
3  "conversationParticipants": [
4    {
5      "displayName": "",
6      "participant": {
7        "subject": "end-user-0001",
8        "role": "EndUser",
9        "appType": "custom"
10      },
11      "joinedTime": "1732182671000"
12    },
13    {
14      "displayName": "The Chatbot",
15      "participant": {
16        "subject": "Omx000000O3YTR",
17        "role": "Chatbot",
18        "appType": "custom"
19      },
20      "joinedTime": "1732182791000",
21      "leftTime": "1732183151000"
22    }
23  ],
24  "conversationEntries": [
25    {
26      "clientTimestamp": "1732182791000",
27      "entryPayload": {
28        "entryType": "Message",
29        "id": "20c18c3c-e119-4f1b-bff8-4e196fd92876",
30        "abstractMessage": {
31          "messageType": "StaticContentMessage",
32          "id": "20c18c3c-e119-4f1b-bff8-4e196fd92876",
33          "staticContent": {
34            "formatType": "Text",
35            "text": "My burr coffee grinder is making a weird sound."
36          }
37        }
38      },
39      "sender": {
40        "subject": "end-user-0001",
41        "role": "EndUser",
42        "appType": "custom"
43      }
44    },
45    {
46      "clientTimestamp": "1732182671000",
47      "entryPayload": {
48        "entryType": "Message",
49        "id": "ba042a99-0577-4444-b26c-318874c76c0c",
50        "abstractMessage": {
51          "messageType": "StaticContentMessage",
52          "id": "ba042a99-0577-4444-b26c-318874c76c0c",
53          "staticContent": {
54            "formatType": "Text",
55            "text": "Does it make the same sound when you adjust the grind size?"
56          }
57        }
58      },
59      "sender": {
60        "subject": "Omx000000O3YTR",
61        "role": "Chatbot",
62        "appType": "custom"
63      }
64    }
65  ],
66    "messagingSession": {
67        "messagingSessionRequestType": "AttachMessagingSession",
68        "payload": {
69            "sessionId": "0Mxxx0000004DBK"
70        }
71    }
72}

1{
2  "channelAddressIdentifier": "a12bc345-1303-44c2-866c-f30d546b58de",
3  "conversationParticipants": [
4    {
5      "displayName": "UserName01",
6      "participant": {
7        "subject": "end-user-0001",
8        "role": "EndUser",
9        "appType": "custom"
10      },
11      "joinedTime": "16881908840000"
12    }
13  ],
14  "conversationEntries": [
15    {
16      "clientTimestamp": "16881908840000",
17      "entryPayload": {
18        "entryType": "Message",
19        "id": "14d678a6-0dc1-4383-b28c-25102024004",
20        "abstractMessage": {
21          "messageType": "StaticContentMessage",
22          "inReplyToMessageId": null,
23          "id": "14d678a6-0dc1-4383-b28c-25102024004",
24          "references": [
25            {
26              "recordId": "068xx0000004C92",
27              "id": "49fb0259-45de-42e0-a47e-af5fa5dbec52"
28            }
29          ],
30          "staticContent": {
31            "formatType": "Attachments",
32            "text": null,
33            "attachments": [
34              {
35                "name": "image.png",
36                "attachmentUploadResult": null,
37                "id": "49fb0259-45de-42e0-a47e-af5fa5dbec52",
38                "mimeType": "image/png",
39                "url": "https://test-dev.develop.test1.my.pc.company.com/img/spinner.png"
40                }
41              ]
42            }
43          }
44        }
45      },
46      "sender": {
47        "subject": "end-user-0001",
48        "role": "EndUser",
49        "appType": "custom"
50      }
51    }
52  ],
53  "messagingSession": {
54    "messagingSessionRequestType": "EstablishMessagingSession",
55    "payload": {
56      "startTime": "1732182671000",
57      "endTime": "1732182671000"
58    }
59  }
60}