Retrieve Conversation Entries

Retrieve messages from a conversation.

This API applies to the following product:

Bring Your Own Bot (BYOB)

For authentication details, see Generate an Access Token.

URI

v1/conversationEntry

HTTP Method

GET

Headers

Authorization

Format: Bearer <Salesforce Access Token>
String. Standard header. The authorization token, where <token> is the JSON Web Token (JWT). Required.

Content-Type

Format: application/json
String. Standard header. The format of the request body. Valid format is application/json. Required.

OrgId

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

AuthorizationContext

Format: <External Conversation Participant Integration Definition developer name>
String. Standard header. The ExtConvParticipantIntegDef developer name in the format {prefix}_{ExtConvParticipantIntegDef}. The prefix must match the developer name prefix of the corresponding ExternalClientApp. For example, Partnerapp_ExtConvParticipantIntegDef. Required.

AuthorizationContextType

Format: ExternalConversationParticipant
String. Standard header. Set this value to ExternalConversationParticipant. Required.

RequestId

Format: <GUID>
String. Standard header. A globally unique ID (GUID). Required.

Sample Header

-H $'Authorization: Bearer 00DSG000009SWby!...LN8XxeRIxGe' \
-H "content-type: application/json" \
-H "OrgId: 00DSG000009SWby" \
-H "AuthorizationContext: ExtConvParticipantIntegDef" \
-H "AuthorizationContextType: ExternalConversationParticipant" \
-H "RequestId: a1b23c45-c06a-4784-c96c-cb95d3321bda" \

Parameters

Property Name	Type	Description	Required
conversationIdentifier	string	A unique identifier generated for the conversation.	Yes
startTime	timestamp	Specifies the starting time boundary for retrieving conversation entries. Must be greater than 0. If invalid, returns error code 10090.	Yes
endTime	timestamp	Specifies the ending time boundary for retrieving conversation entries. Must be greater than 0 and greater than `startTime`. If invalid, returns error code 10091. If omitted, queries up to the current time.	No
direction	string	Defines the order or direction in which conversation entries are retrieved. Valid values are `FROM_START` and `FROM_END`.	No
limit	number	Sets a maximum number of conversation entries to be returned in the API response. Valid range is 1–20; server maximum is 20. If invalid, returns error code 10092.	No

Bring Your Own Bot Example

Request

{
  "conversationIdentifier": "3f5e2d4e-e41c-424a-90db-df70c8153a67",
  "startTime": 1741763707000,
  "endTime": 1741765807000,
  "direction": "FROM_START",
  "limit": 20
}

Response

{
  "success": true,
  "conversationEntries": [
    {
      "clientTimestamp": "1741763887000",
      "sender": {
        "appType": "CUSTOM",
        "subject": "EndUser123",
        "role": "EndUser"
      },
      "entryPayload": "{\"entryType\":\"Message\",\"id\":\"12345678\",\"abstractMessage\":{\"messageType\":\"StaticContentMessage\",\"id\":\"123456\",\"staticContent\":{\"formatType\":\"Text\",\"text\":\"Hi. Message from EndUser123.\"}}}"
    },
    {
      "clientTimestamp": "1741763707000",
      "sender": {
        "appType": "CUSTOM",
        "subject": "EndUser123",
        "role": "EndUser"
      },
      "entryPayload": "{\"entryType\":\"Message\",\"id\":\"1122334455\",\"abstractMessage\":{\"messageType\":\"StaticContentMessage\",\"id\":\"1122334455\",\"staticContent\":{\"formatType\":\"Text\",\"text\":\"I have a question\"}}}"
    }
  ]
}