Conversation Data API Endpoints

GET Fetch conversation entries.

GET /conversation-entries

Operation ID: getConversationEntries. Tags: ConversationEntries.

Retrieves the conversation entries for a given Conversation ID. The conversation entry (transcript) for a voice call isn’t available until after the voice call record is created. An error occurs if you try to fetch the transcript before the record is created.

Parameters

conversationIdentifier (query, string, required) Unique ID of the conversation associated with the conversation entries.
Example
```
17628be7-1cff-4878-b9f9-fa50433b0905
```
startTimestamp (query, integer (int64)) Start timestamp for the window of time being requested. The results will include all conversation entries created after this time.
Example
```
1752175937852
```
endTimestamp (query, integer (int64)) End timestamp for the window of time being requested. The results will include all conversation entries created before this time.
Example
```
1752262337852
```
limit (query, integer (int64)) Maximum number of entries to return. The maximum value can be up to 1000. If a value is not specified, the default value is 1000.
direction (query, string) Chronological direction to use when getting entries. If a value is not specified, the default value is 'fromEnd'.
Allowed values: FROMSTART–Query conversation entries in chronological ascending order, starting with the earliest entry., FROMEND–Query conversation entries in chronological descending order, starting with the most recent entry..
entryIdentifiersFilter (query, array of string) Filters conversation entries by their unique identifiers. Provide a comma-separated list of string IDs to retrieve only the entries for those IDs. This is a powerful way to fetch a small, targeted set of entries.
Example: 41c33058-2d80-4780-982a-6567049749bz.
entryTypeFilter (query, array of string) Filters conversation entries by entry type. Provide a comma-separated list of entry types to retrieve only the entries that match one of the specified entry types. For a full list of entry types, refer to the ConversationEntry Schema page.
Example
```
MESSAGE, PARTICIPANT_CHANGED, MESSAGE_DELIVERY_FAILED, ROUTING_RESULT, ROUTING_WORK_RESULT, NOTE, FLAG_RAISE, FLAG_LOWER, CLIENT_MENU, END_USER_CONSENT_UPDATED, SESSION_STATUS_CHANGED, CONSULT_CONVERSATION_INFO, SESSION_CONTEXT, SESSION_OWNER_CHANGED
```

Responses

200 The operation was successful. The example shows a sample ConversationEntry payload. Note that the payload's structure varies based on the ConversationEntry type specified. For complete details on all possible variations, refer to the ConversationEntry Schema page.

Media type: application/json. Schema: object.

conversationIdentifier (string) Unique ID of the conversation.
conversationEntries (array of object)

Example: Sample Success Response Sample Success Response

{
  "conversationIdentifier": "17628be7-1cff-4878-b9f9-fa50433b0905",
  "conversationEntries": [
    {
      "identifier": "41c33058-2d80-4780-982a-6567049749bz",
      "entryType": "Message",
      "entryPayload": {
        "entryType": "Message",
        "id": "41c33058-2d80-4780-982a-6567049749bz",
        "abstractMessage": {
          "inReplytoMessageId": null,
          "customHandlingType": null,
          "id": "41c33058-2d80-4780-982a-6567049749bz",
          "messageType": "StaticContentMessage",
          "staticContent": {
            "formatType": "Text",
            "text": "Hello! Can you please provide your order number?",
            "citationContent": null
          }
        },
        "messageReason": null,
        "wasRevised": false
      },
      "sender": {
        "role": "Agent",
        "appType": "messaging",
        "subject": "005x00000000001",
        "clientIdentifier": null
      },
      "transcriptedTimestamp": 1752175937852,
      "relatedRecords": [],
      "clientTimestamp": 1752175937852,
      "clientDuration": 0
    }
  ]
}

400 Bad Request. Validation failed. One or more invalid query parameters were specified. Refer to the error message to identify the exact issue that caused this error.

Media type: application/json. Schema: ErrorResponse.

Example: Conversation Does Not Exist Conversation does not exist

{
  "code": null,
  "errorCode": "BAD_ARGUMENT",
  "messageCode": "PERMISSION_DENIED",
  "message": "Conversation does not exist",
  "targets": [],
  "parameters": [],
  "errorDetails": []
}

Example: Invalid Data Type Invalid Data Type

{
  "code": null,
  "errorCode": "BAD_ARGUMENT",
  "messageCode": "VALIDATION_FAILED",
  "message": "Invalid value 'cat' for parameter 'limit'.",
  "targets": [],
  "parameters": [],
  "errorDetails": []
}

Example: Negative Limit Limit is a negative number

{
  "code": null,
  "errorCode": "BAD_ARGUMENT",
  "messageCode": "VALIDATION_FAILED",
  "message": "Limit cannot be negative.",
  "targets": [],
  "parameters": [],
  "errorDetails": []
}

Example: Limit Exceeded Limit exceeds maximum allowed

{
  "code": null,
  "errorCode": "BAD_ARGUMENT",
  "messageCode": "CONVERSATION_ENTRIES_LIMIT_EXCEEDED",
  "message": "Limit exceeded the configured maximum of 1000.",
  "targets": [],
  "parameters": [],
  "errorDetails": []
}

Example: Invalid Timestamp Range Start timestamp is after End timestamp

{
  "code": null,
  "errorCode": "BAD_ARGUMENT",
  "messageCode": "INVALID_TIMESTAMP_RANGE",
  "message": "Start timestamp must be less than or equal to end timestamp.",
  "targets": [],
  "parameters": [],
  "errorDetails": []
}

Example: Invalid Direction Invalid direction value is provided

{
  "code": null,
  "errorCode": "BAD_ARGUMENT",
  "messageCode": "VALIDATION_FAILED",
  "message": "Invalid value 'adf' for parameter 'direction'.",
  "targets": [],
  "parameters": [],
  "errorDetails": []
}

Example: Invalid Entry Type Entry type filter value is invalid

{
  "code": null,
  "errorCode": "BAD_ARGUMENT",
  "messageCode": "VALIDATION_FAILED",
  "message": "Entry type filter value is invalid.",
  "targets": [],
  "parameters": [],
  "errorDetails": []
}

403 User does not have permission to fetch the resources.
404 Conversation ID not found.
500 Internal server error.