Skip to main content
These endpoints use session authentication. All data is scoped to your organization.

​
List conversations

GET /api/v1/conversations?chatbotId=<chatbot_id>&page=1&limit=20

​
Query parameters

ParameterTypeDefaultDescription
chatbotIdstring—Filter to a specific chatbot
pagenumber1Page number
limitnumber20Items per page (max 100)

​
Response

{
  "conversations": [
    {
      "id": "uuid",
      "chatbot_id": "uuid",
      "external_conversation_id": "conv_123",
      "external_user_id": "user_456",
      "message_count": 8,
      "first_message_at": "2024-01-15T10:00:00Z",
      "last_message_at": "2024-01-15T10:15:00Z",
      "created_at": "2024-01-15T10:00:00Z",
      "chatbots": { "name": "Support Bot" }
    }
  ],
  "total": 142,
  "page": 1,
  "limit": 20
}

​
Response fields

FieldTypeDescription
conversationsarrayPaginated list of conversation objects
conversations[].idstringOpenBat internal ID
conversations[].chatbot_idstringID of the chatbot this conversation belongs to
conversations[].external_conversation_idstringThe conversation ID you passed via the SDK
conversations[].external_user_idstringThe user ID you passed via the SDK
conversations[].message_countnumberTotal messages in the conversation
conversations[].first_message_atstringISO 8601 timestamp of the first message
conversations[].last_message_atstringISO 8601 timestamp of the most recent message
conversations[].created_atstringISO 8601 timestamp when the conversation was created
conversations[].chatbots.namestringName of the chatbot
totalnumberTotal number of matching conversations
pagenumberCurrent page number
limitnumberItems per page

​
Get a conversation

Retrieve a single conversation with its full message history and sentiment analysis. 
GET /api/v1/conversations/:id

​
Response

{
  "id": "uuid",
  "external_conversation_id": "conv_123",
  "message_count": 4,
  "first_message_at": "2024-01-15T10:00:00Z",
  "last_message_at": "2024-01-15T10:05:00Z",
  "messages": [
    {
      "id": "uuid",
      "role": "user",
      "content": "How do I cancel my subscription?",
      "external_message_id": "msg_001",
      "created_at": "2024-01-15T10:00:00Z",
      "user_sentiments": [
        {
          "score": -0.4,
          "text_chunk": "cancel my subscription",
          "reasoning": "User expressing intent to discontinue service"
        }
      ]
    },
    {
      "id": "uuid",
      "role": "assistant",
      "content": "You can cancel by going to Settings...",
      "created_at": "2024-01-15T10:01:00Z"
    }
  ]
}

​
Message fields

FieldTypeDescription
idstringOpenBat internal message ID
rolestringuser, assistant, or system
contentstringMessage text
external_message_idstringThe message ID you passed via the SDK
created_atstringISO 8601 timestamp
user_sentimentsarraySentiment analysis results (present on user messages only)

​
Sentiment object fields

FieldTypeDescription
scorenumberSentiment score ranging from -1 (very negative) to 1 (very positive)
text_chunkstringThe portion of the message this score applies to
reasoningstringExplanation of why this score was assigned

​
Analytics overview

Get aggregate metrics across all your chatbots, or scope to a specific one. 
GET /api/v1/analytics/overview?chatbotId=<chatbot_id>

​
Query parameters

ParameterTypeDefaultDescription
chatbotIdstring—Scope metrics to a specific chatbot

​
Response

{
  "totalConversations": 1247,
  "totalMessages": 8932,
  "avgSentiment": 0.23,
  "sentimentDistribution": {
    "Very Positive": 312,
    "Positive": 445,
    "Neutral": 298,
    "Negative": 142,
    "Very Negative": 50
  },
  "messagesToday": 83
}

​
Response fields

FieldTypeDescription
totalConversationsnumberTotal number of conversations
totalMessagesnumberTotal number of messages across all conversations
avgSentimentnumberAverage sentiment score (-1 to 1)
sentimentDistributionobjectCounts grouped by sentiment label
messagesTodaynumberNumber of messages received today
The sentimentDistribution object contains five keys: Very Positive, Positive, Neutral, Negative, and Very Negative. Each value is an integer count.
Get sentiment data over time for charting and trend analysis. 
GET /api/v1/analytics/sentiment?chatbotId=<chatbot_id>&days=30

​
Query parameters

ParameterTypeDefaultDescription
chatbotIdstring—Required. Filter to a specific chatbot.
daysnumber30Lookback period in days (max 365)

​
Response

{
  "sentimentOverTime": [
    { "date": "2024-01-15", "avgScore": 0.18, "count": 42 },
    { "date": "2024-01-16", "avgScore": 0.24, "count": 38 }
  ],
  "distribution": {
    "Positive": 145,
    "Neutral": 89,
    "Negative": 43
  },
  "total": 277
}

​
Response fields

FieldTypeDescription
sentimentOverTimearrayOne entry per day within the lookback period
sentimentOverTime[].datestringDate in YYYY-MM-DD format
sentimentOverTime[].avgScorenumberAverage sentiment score for that day (-1 to 1)
sentimentOverTime[].countnumberNumber of sentiment-analyzed messages that day
distributionobjectCounts grouped by sentiment label for the period
totalnumberTotal number of analyzed messages in the period