Get conversations

gethttps://api.chat-data.com/api/v2/get-conversations/{chatbotId}/get-conversations/{chatbotId}

Any keyWorkspace or chatbot key

Get conversations from a chatbot, most recently active first. Only conversations with at least one user message are returned. Results are paginated.

Parameters

Sending 1 of 10 fields

Required

chatbotIdstring

The unique identifier allocated to the chatbot.

Try it · GET /get-conversations/{chatbotId}

curl 'https://api.chat-data.com/api/v2/get-conversations/6650f1c2a9e4b83d2c7a1f05' \  -H "Authorization: Bearer $CHAT_DATA_API_KEY"

Loading…

{  "status": "success",  "conversations": [    {      "conversationId": "3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c",      "createdAt": 1791970200000,      "messages": [        {          "role": "user",          "content": "What are your opening hours?",          "timestamp": "2026-10-14T09:30:00.000Z",          "read": true        },        {          "role": "assistant",          "content": "We're open Monday to Friday, 9am to 6pm EST. Outside those hours you can email [email protected].",          "timestamp": "2026-10-14T09:30:03.000Z",          "score": 0.87,          "upvote": true,          "read": true        },        {          "role": "user",          "content": "Thanks! Can I talk to someone about a refund?",          "timestamp": "2026-10-14T09:31:00.000Z",          "read": true        },        {          "role": "human",          "content": "Hi Jane, I'm Alex from the support team. I can help with your refund.",          "name": "Alex Chen",          "avatar": "https://example.blob.core.windows.net/chatfiles/6650f1c2a9e4b83d2c7a1f05/agent-avatar.png",          "timestamp": "2026-10-14T09:32:00.000Z",          "read": true        }      ],      "source": "widget",      "requestedLiveChat": true,      "liveChatEnded": false,      "chatbotId": "6650f1c2a9e4b83d2c7a1f05",      "ipAddress": "203.0.113.42",      "userCountry": "US",      "customer": {        "leadId": "8d0c2b6e-4f1a-4b7c-9e3d-2a5f6b7c8d9e",        "name": "Jane Doe",        "email": "[email protected]",        "phone": "+14155550123",        "createdAt": 1791970230000      },      "overalRating": 5,      "browserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0 Safari/537.36",      "urlPath": "/pricing"    }  ],  "total": 10}

Responses

Successful response.

Content type: application/json

Field	Type	Description
statusstring	string	One of: `success`.
conversationsarray of object	array of object	The conversations, most recently active first. Only conversations with at least one user message are included.
conversations[].conversationIdstring	string	ID of the conversation.
conversations[].createdAtnumber	number	When the conversation was created, in milliseconds since the Unix epoch.
conversations[].lastMessageAtstring	string	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.
conversations[].messagesarray of object	array of object	The messages of the conversation, oldest first.
conversations[].messages[].rolestring	string	The role of the message sender (`user`, `assistant`, or `human` for a live chat agent).
conversations[].messages[].contentstring	string	The text content of the message.
conversations[].messages[].isTranscriptboolean	boolean	Indicates whether the message is a transcript of the realtime voice-to-voice interaction.
conversations[].messages[].upvoteboolean	boolean	Indicates whether the message is upvoted by the user.
conversations[].messages[].namestring	string	The name of the agent who sent the message, if the role is `human`.
conversations[].messages[].avatarstring	string	The avatar image URL of the agent who sent the message, if the role is `human`.
conversations[].messages[].timestampstring	string	When the message was sent (ISO 8601).
conversations[].messages[].midstring	string	The ID of the message.
conversations[].messages[].reasoningstring	string	The model's reasoning for an assistant message, when it was recorded.
conversations[].messages[].downvoteFeedbackstring	string	The user's feedback when they downvoted the message.
conversations[].messages[].readboolean	boolean	Indicates whether the message has been read by the user or the agent.
conversations[].messages[].filesarray of object	array of object	The files attached to the message.
conversations[].messages[].files[].namestring	string	The name of the file.
conversations[].messages[].files[].typestring	string	The MIME type of the file.
conversations[].messages[].files[].urlstring	string	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.
conversations[].messages[].audioUrlstring	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.
conversations[].messages[].scorenumber	number	The level of confidence in the generated answer. If no score is present, the answer was not derived from search results.
conversations[].sourcestring	string	Where the conversation took place. One of: `widget`, `iframe`, `site`, `api`, `Whatsapp`, `WhatsappWebAPI`, `Messenger`, `Instagram`, `Telegram`, `Line`, `Slack`, `Discord`, `Workflow Studio`, `cron-trigger`.
conversations[].requestedLiveChatboolean	boolean	Whether live chat support was requested in this conversation.
conversations[].liveChatEndedboolean	boolean	Whether live chat has ended in this conversation.
conversations[].chatbotIdstring	string	The ID of the chatbot.
conversations[].ipAddressstring	string	The IP address of the user.
conversations[].userCountrystring	string	The 2-letter ISO country code of the user, based on an IP address lookup (`Unknown` when it could not be resolved).
conversations[].customerobject	object	The lead attached to the conversation, if any. In conversations, `source`, `ipAddress` and `userCountry` are not included in it.
conversations[].customer.leadIdstring	string	The unique identifier of the lead (UUID).
conversations[].customer.namestring	string	The name provided by the customer.
conversations[].customer.emailstring	string	The email address provided by the customer.
conversations[].customer.phonestring	string	The phone number provided by the customer.
conversations[].customer.psidstring	string	The page-scoped user ID of the customer, if the customer is from Messenger.
conversations[].customer.ig_usernamestring	string	The Instagram username of the customer, if the customer is from Instagram.
conversations[].customer.usernamestring	string	Slack or Telegram username. A platform-specific identifier, distinct from `ig_username` (Instagram) and `psid` (Messenger).
conversations[].customer.infostring	string	Additional information stored on the lead.
conversations[].customer.sourcestring	string	The source the customer was acquired from. Only returned by get-customers. One of: `widget`, `iframe`, `site`, `api`, `Whatsapp`, `WhatsappWebAPI`, `Messenger`, `Instagram`, `Telegram`, `Line`, `Slack`, `Discord`, `Workflow Studio`, `cron-trigger`.
conversations[].customer.ipAddressstring	string	The IP address of the customer. Only returned by get-customers.
conversations[].customer.userCountrystring	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.
conversations[].customer.createdAtnumber	number	When the customer's information was submitted, in milliseconds since the Unix epoch.
conversations[].overalRatingnumber	number	The overall rating the user gave the conversation (1-5), if any.
conversations[].browserAgentstring	string	The user agent string of the browser used in the conversation.
conversations[].urlPathstring	string	The URL path where the conversation started, when the source is `widget`.
totalnumber	number	Total number of matching conversations, ignoring pagination.

Example

{  "status": "success",  "conversations": [    {      "conversationId": "3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c",      "createdAt": 1791970200000,      "messages": [        {          "role": "user",          "content": "What are your opening hours?",          "timestamp": "2026-10-14T09:30:00.000Z",          "read": true        },        {          "role": "assistant",          "content": "We're open Monday to Friday, 9am to 6pm EST. Outside those hours you can email [email protected].",          "timestamp": "2026-10-14T09:30:03.000Z",          "score": 0.87,          "upvote": true,          "read": true        },        {          "role": "user",          "content": "Thanks! Can I talk to someone about a refund?",          "timestamp": "2026-10-14T09:31:00.000Z",          "read": true        },        {          "role": "human",          "content": "Hi Jane, I'm Alex from the support team. I can help with your refund.",          "name": "Alex Chen",          "avatar": "https://example.blob.core.windows.net/chatfiles/6650f1c2a9e4b83d2c7a1f05/agent-avatar.png",          "timestamp": "2026-10-14T09:32:00.000Z",          "read": true        }      ],      "source": "widget",      "requestedLiveChat": true,      "liveChatEnded": false,      "chatbotId": "6650f1c2a9e4b83d2c7a1f05",      "ipAddress": "203.0.113.42",      "userCountry": "US",      "customer": {        "leadId": "8d0c2b6e-4f1a-4b7c-9e3d-2a5f6b7c8d9e",        "name": "Jane Doe",        "email": "[email protected]",        "phone": "+14155550123",        "createdAt": 1791970230000      },      "overalRating": 5,      "browserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0 Safari/537.36",      "urlPath": "/pricing"    }  ],  "total": 10}

Last updated October 14, 2026