---
title: "Get a conversation"
method: GET
path: "/get-conversation/{conversationId}"
tags: ["Conversation Operations"]
---

# Get a conversation

`GET /get-conversation/{conversationId}`

## Request

- Base URL: `https://api.chat-data.com/api/v2`
- URL: `https://api.chat-data.com/api/v2/get-conversation/{conversationId}`
- Auth: HTTP bearer

Get detailed information about a specific conversation, including messages, customer details if available, and metadata.

If `chatbotId` is provided, the conversation is retrieved from that chatbot.
If `chatbotId` is not provided, the conversation is retrieved from any chatbot in your workspace (or, with a chatbot-scoped key, from that key's chatbot).

## Path parameters

- `conversationId` string, required

## Query parameters

- `chatbotId` string

## Response `200`

Successful response.

- object
  - `status` 'success', required
  - `conversation` Conversation, required
    - `conversationId` string, required: ID of the conversation.
    - `createdAt` number, required: When the conversation was created, in milliseconds since the Unix epoch.
    - `lastMessageAt` string, date-time: When the last message in the conversation was sent (ISO 8601), or when the conversation was created if that is not recorded. Only returned by get-conversation.
    - `messages` Message[], required: The messages of the conversation, oldest first.
      - `role` 'user' | 'assistant' | 'human', required: The role of the message sender (`user`, `assistant`, or `human` for a live chat agent).
      - `content` string, required: The text content of the message.
      - `isTranscript` boolean: Indicates whether the message is a transcript of the realtime voice-to-voice interaction.
      - `upvote` boolean: Indicates whether the message is upvoted by the user.
      - `name` string: The name of the agent who sent the message, if the role is `human`.
      - `avatar` string: The avatar image URL of the agent who sent the message, if the role is `human`.
      - `timestamp` string, date-time: When the message was sent (ISO 8601).
      - `mid` string: The ID of the message.
      - `reasoning` string: The model's reasoning for an assistant message, when it was recorded.
      - `downvoteFeedback` string: The user's feedback when they downvoted the message.
      - `read` boolean: Indicates whether the message has been read by the user or the agent.
      - `files` object[]: The files attached to the message.
        - `name` string, required: The name of the file.
        - `type` string, required: The MIME type of the file.
        - `url` string, uri, required: The URL of the file in Azure Blob Storage. Use the `/get-sas-token` endpoint to get a URL with a SAS token for public access.
      - `audioUrl` string: The URL of the audio file in Azure Blob Storage, when the message is a transcript of an audio input. Use the `/get-sas-token` endpoint to get a URL with a SAS token for public access.
      - `score` number: The level of confidence in the generated answer. If no score is present, the answer was not derived from search results.
    - `source` 'widget' | 'iframe' | 'site' | 'api' | 'Whatsapp' | 'WhatsappWebAPI' | 'Messenger' | 'Instagram' | 'Telegram' | 'Line' | 'Slack' | 'Discord' | 'Workflow Studio' | 'cron-trigger', required: Where the conversation took place.
    - `requestedLiveChat` boolean: Whether live chat support was requested in this conversation.
    - `liveChatEnded` boolean: Whether live chat has ended in this conversation.
    - `chatbotId` string, required: The ID of the chatbot.
    - `ipAddress` string: The IP address of the user.
    - `userCountry` string: The 2-letter ISO country code of the user, based on an IP address lookup (`Unknown` when it could not be resolved).
    - `customer` Customer: A lead. Fields that are not set are omitted, and the answers of a custom lead form are included as extra top-level fields.
      - `leadId` string: The unique identifier of the lead (UUID).
      - `name` string: The name provided by the customer.
      - `email` string: The email address provided by the customer.
      - `phone` string: The phone number provided by the customer.
      - `psid` string: The page-scoped user ID of the customer, if the customer is from Messenger.
      - `ig_username` string: The Instagram username of the customer, if the customer is from Instagram.
      - `username` string: Slack or Telegram username. A platform-specific identifier, distinct from `ig_username` (Instagram) and `psid` (Messenger).
      - `info` string: Additional information stored on the lead.
      - `source` 'widget' | 'iframe' | 'site' | 'api' | 'Whatsapp' | 'WhatsappWebAPI' | 'Messenger' | 'Instagram' | 'Telegram' | 'Line' | 'Slack' | 'Discord' | 'Workflow Studio' | 'cron-trigger': The source the customer was acquired from. Only returned by get-customers.
      - `ipAddress` string: The IP address of the customer. Only returned by get-customers.
      - `userCountry` string: The 2-letter ISO country code of the customer, based on an IP address lookup (`Unknown` when it could not be resolved). Only returned by get-customers.
      - `createdAt` number, required: When the customer's information was submitted, in milliseconds since the Unix epoch.
    - `overalRating` number: The overall rating the user gave the conversation (1-5), if any.
    - `browserAgent` string: The user agent string of the browser used in the conversation.
    - `urlPath` string: The URL path where the conversation started, when the source is `widget`.

## Other responses

- `400`: An unexpected error occurred while processing the request; `message` contains the error.
- `401`: Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.
- `403`: The API key cannot access this conversation. With a `chatbotId` query parameter, a chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`, and any key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when that chatbot does not exist or belongs to another workspace.
- `404`: No conversation with this ID was found in the key's workspace (or in the given or key's chatbot), including one that belongs to another chatbot or workspace.
- `429`: The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.

---

[API](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide.md) · [All operations](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide/llms.txt) · [OpenAPI document](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide/revisions/72871007f7f0?raw)