Skip to main content
Conversations

Get conversation by ID

Retrieves a single conversation by its ID, including conversation parts (messages).

GET
/v2/conversations/{id}

Path Parameters

  • id - The conversation ID (short ID)

Hard Limit of 500 Parts

The maximum number of conversation parts that can be returned via the API is 500. If a conversation has more than 500 parts, only the 500 most recent conversation parts will be returned.

Response Format

Returns a single conversation object with:

  • object - Always "conversation"
  • id - Unique conversation identifier (short ID)
  • title - Conversation title
  • state - Current state ("open", "closed", or "snoozed")
  • priority - Whether the conversation is marked as priority
  • adminAssigneeId - ID of assigned admin (if any)
  • teamAssigneeId - ID of assigned team (if any)
  • participants - Array of participants
  • source - Information about the first message
  • conversationParts - Array of conversation parts (messages, max 500)
  • createdAt - Creation timestamp
  • updatedAt - Last update timestamp

Conversation Parts

Each conversation part includes:

  • object - Always "conversation_part"
  • id - Unique part identifier
  • partType - Type of part (e.g., "user_msg", "admin_msg", "bot_msg")
  • body - Message body (HTML content)
  • author - Author information with name, email, and profile picture
  • channel - Channel through which the message was sent
  • createdAt - Creation timestamp
  • updatedAt - Last update timestamp

Example

{
  "object": "conversation",
  "id": "12345",
  "title": "Question about pricing",
  "state": "open",
  "priority": false,
  "adminAssigneeId": "507f1f77bcf86cd799439011",
  "participants": [
    { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" }
  ],
  "conversationParts": [
    {
      "object": "conversation_part",
      "id": "1",
      "partType": "user_msg",
      "bodyHtml": "<p>Hello, I have a question about your pricing plans.</p>",
      "bodyMarkdown": "Hello, I have a question about your pricing plans.",
      "author": {
        "type": "customer",
        "id": "676f0f6765bdaa7d7d760f88",
        "name": "John Doe",
        "email": "john@example.com"
      },
      "channel": "desktop",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    },
    {
      "object": "conversation_part",
      "id": "2",
      "partType": "admin_msg",
      "bodyHtml": "<p>Hi John! I'd be happy to help you with pricing information.</p>",
      "bodyMarkdown": "Hi John! I'd be happy to help you with pricing information.",
      "author": {
        "type": "admin",
        "id": "507f1f77bcf86cd799439011",
        "name": "Support Agent"
      },
      "channel": "desktop",
      "createdAt": "2025-01-15T10:35:00.000Z",
      "updatedAt": "2025-01-15T10:35:00.000Z"
    }
  ],
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:35:00.000Z"
}

Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Path Parameters

idstringrequired

Conversation ID (short ID)

Required string length: 1 - 16
Pattern: ^[a-zA-Z0-9]+$
Example: 12345

Query Parameters

includestring | string[]query

Comma-separated optional expansions. Use customAttributeDefinitions to return customAttributeValues with names and types alongside ID-keyed customAttributes.

Example: customAttributeDefinitions

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover
Example: 2026-08-19.orbit

Response

application/json

Success

adminAssigneeIdstring | nullrequired

ID of the assigned admin

Example: 507f1f77bcf86cd799439011
awaitingCustomerReplyboolean

Whether we are awaiting a customer reply

Example: true
botConversationStateenum<string>

State of AI agent handling for this conversation

Available options: active, handed_off_to_human, resolved
Example: active
botConversationStateLastUpdatedAtstring | nullrequired

ISO timestamp when bot state last changed

Example: 2025-01-15T10:30:00.000Z
brandIdstring | nullrequired

ID of the brand associated with this conversation

Example: 507f1f77bcf86cd799439011
conversationPartsobject[]

Array of conversation parts (messages). Only included when fetching a single conversation by ID.

createdAtstringrequired

ISO timestamp when conversation was created

Example: 2025-01-15T10:30:00.000Z
csatDebugobject

Minimal CSAT diagnostics for the current effective request.

csatHistoryobject[]

Historical CSAT requests for this conversation, ordered newest first.

csatSummaryobject

Derived CSAT summary for this conversation when a rating request or rating exists.

customAttributeValuesobject[]

Custom conversation attribute values expanded with definition metadata. Returned only when include=customAttributeDefinitions is provided.

customAttributesobject

Custom conversation attributes keyed by custom attribute ID. Only org-defined, non-archived conversation attributes are returned; internal workflow metadata is omitted.

disableCustomerReplyboolean

Whether customer replies are disabled

Example: false
hasAdminOverriddenLanguagebooleanrequired

Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled.

Example: false
idstringrequired

Unique conversation identifier

Example: 12345
isBlockedbooleanrequired

Whether the user is blocked

Example: false
lastActivityAtstring | nullrequired

ISO timestamp of last activity

Example: 2025-01-15T12:30:00.000Z
objectenum<string>required

Object type identifier

Available options: conversation
Example: conversation
participantsobject[]required

Participants in this conversation

prioritybooleanrequired

Whether this conversation is marked as priority

Example: false
prioritySetAtstring | nullrequired

ISO timestamp when priority was set

Example: 2025-01-15T10:30:00.000Z
readReceiptsobject[]

Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access.

snoozedUntilstring | nullrequired

ISO timestamp until which conversation is snoozed

Example: 2025-01-16T09:00:00.000Z
sourceobject
stateenum<string>required

Current state of the conversation

Available options: open, closed, snoozed
Example: open
tagsobject[]required

Current tags applied anywhere in this conversation

teamAssigneeIdstring | nullrequired

ID of the assigned team

Example: 507f1f77bcf86cd799439012
titlestring

Conversation title

Example: Question about pricing
updatedAtstringrequired

ISO timestamp when conversation was last updated

Example: 2025-01-15T12:30:00.000Z
userPreferredLanguagestringrequired

User's preferred language

Example: en
waitingSincestring | nullrequired

ISO timestamp when conversation started waiting

Example: 2025-01-15T10:30:00.000Z

Still need help? Ask the team