Conversation Operations

Get conversations

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

get/get-conversations/{chatbotId}

Request

  • Base URL: https://api.chat-data.com/api/v2
  • URL: https://api.chat-data.com/api/v2/get-conversations/{chatbotId}
  • Auth: HTTP bearer

Path parameters

chatbotIdstring required

The unique identifier allocated to the chatbot.

Query parameters

startTimestampnumber

Start of the time range (inclusive), in milliseconds since the Unix epoch. A conversation matches when it was created or last active within the range.

endTimestampnumber

End of the time range (exclusive), in milliseconds since the Unix epoch.

startnumber

The start position of the results, used for pagination.

sizenumber

The maximum number of results returned after the start position, used for pagination. A negative value returns all remaining results.

sourcestring[]

Filter conversations by source. Repeat the parameter to match several sources.

leadIdstring

The UUID of the lead, which can be obtained from the lead-submission webhook event.

requestedLiveChatboolean

true returns only conversations that requested live chat support, false only those that did not.

liveChatEndedboolean

true returns only conversations whose live chat has ended, false only those whose live chat has not ended.

overalRatingnumber

Filter conversations by their overall rating (1-5).

Response

Successful response.

status'success' required
totalnumber required

Total number of matching conversations, ignoring pagination.

Example response

{
  "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 support@example.com.",
          "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": "jane@chat-data.com",
        "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"
    }
  ]
}

Changes