Skip to main content
Send conversation messages to OpenBat for storage and analysis. This endpoint upserts conversations — it creates a new conversation if the conversationId is new, or appends messages and updates metadata if the conversation already exists.

​
Endpoint

POST https://app.openbat.dev/api/v1/capture
Authorization: Bearer ob_live_...
Content-Type: application/json

​
Request body

​
Required fields

​
conversationId
string
required
Your unique identifier for this conversation. Used to group messages together across multiple capture calls.
​
messages
array
required
An array of 1 to 100 message objects to ingest.

​
Optional fields

​
user
object
Metadata about the end user in the conversation.
​
organization
object
Metadata about the organization the user belongs to.
​
session
object
Metadata about the current browsing session.
​
custom
Record<string, string | number | boolean>
Custom key-value fields. These are validated against the schema you define for your chatbot in the dashboard. Unknown fields produce a warning in the response but do not cause the request to fail.

​
Deprecated fields

The following fields are still accepted but deprecated. Use the recommended replacements instead.
​
userId
string
deprecated
Use user.id instead.
​
metadata
object
deprecated
Use custom instead.

​
Request example

{
  "conversationId": "conv_abc123",
  "messages": [
    {
      "role": "user",
      "content": "How do I cancel my subscription?",
      "id": "msg_001",
      "sentAt": "2025-03-15T14:30:00Z"
    },
    {
      "role": "assistant",
      "content": "You can cancel your subscription from Settings > Billing. Would you like me to walk you through it?",
      "id": "msg_002",
      "sentAt": "2025-03-15T14:30:02Z"
    }
  ],
  "user": {
    "id": "user_456",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "plan": "pro"
  },
  "session": {
    "pageUrl": "https://example.com/help",
    "device": "desktop"
  }
}

​
Response

​
Success (200 OK)

{
  "ok": true,
  "conversationId": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
  "messagesStored": 2,
  "analysisQueued": true,
  "warnings": []
}
​
ok
boolean
Always true on a successful response.
​
conversationId
string
OpenBat’s internal UUID for the conversation.
​
messagesStored
number
The number of new messages inserted. Duplicate messages (matched by id) are excluded from this count.
​
analysisQueued
boolean
Whether LLM analysis (sentiment scoring, topic extraction) was queued for this batch of messages.
​
warnings
string[]
Non-fatal validation issues. For example, if you send a custom field that is not defined in your chatbot schema, it appears here.

​
Response with warnings

{
  "ok": true,
  "conversationId": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
  "messagesStored": 2,
  "analysisQueued": true,
  "warnings": ["Custom field 'unknown_field' not in schema"]
}

​
Error responses

StatusMeaning
400Invalid request body — missing required fields or wrong types
401Missing or invalid API key
429Rate limit exceeded

​
Behavior

The capture endpoint returns immediately. Sentiment analysis and other LLM processing run asynchronously after the response is sent.
  • Upsert semantics — if the conversationId has been seen before, new messages are appended and user/organization/session metadata is updated. Otherwise a new conversation is created.
  • Message deduplication — messages are deduplicated by the id field. Sending the same message ID twice results in only one stored message.
  • Non-strict custom fields — custom fields that are not defined in your chatbot’s schema, or that have the wrong type, produce warnings but do not reject the request.
  • Message limit — each request must contain between 1 and 100 messages.