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 products:
- 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.
Tip: 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.
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.
v1/conversationHistory
POST
| 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 |
| conversationIdentifier | string | The unique ID for the conversation channel. 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 |
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 |
Configure the static content (entryPayload.abstractMessage.staticContent) details for messages and file attachments.
| Property Name | Type | Description | Required |
|---|---|---|---|
| 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. |
See also