Skip to main content

​
Overview

Tag conversations with a userId to track per-user chat history. Once a conversation is associated with a user, you can list all of that user’s conversations and continue any of them by passing the conversationId.

​
Setting a User ID

Pass userId when creating a new conversation. The ID must follow these constraints:
ConstraintValue
Max length128 characters
Allowed charactersa-z, A-Z, 0-9, ., _, -
When appliedOnly on conversation creation (no conversationId in request)
MutabilityImmutable — cannot be changed or removed after creation
A conversation’s userId is set once at creation and cannot be changed. If you send userId with a conversationId, the userId field is ignored.
const response = await fetch(
  "https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message: "Hello!",
      stream: true,
      userId: "user_abc123",
    }),
  }
);
The response metadata includes the userId: 
{
  "type": "finish",
  "finishReason": "stop",
  "metadata": {
    "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "userId": "user_abc123",
    "usage": { "credits": 2 }
  }
}

​
Continuing a Conversation

To send follow-up messages in the same conversation, pass the conversationId from a previous response: 
const response = await fetch(
  "https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message: "Tell me more about that.",
      stream: true,
      conversationId: "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    }),
  }
);
The conversationId is returned in the streaming finish event’s metadata or in the non-streaming response’s metadata object. See Streaming for details.
If the conversation has ended (e.g. after a human takeover), the API returns a CHAT_CONVERSATION_NOT_ONGOING error. Start a new conversation instead.

​
Listing a User’s Conversations

Retrieve all conversations for a specific user with GET /api/v2/agents/{agentId}/users/{userId}/conversations.

​
Path Parameters

ParameterTypeDescription
agentIdstringThe agent ID.
userIdstringThe user ID to list conversations for.

​
Query Parameters

ParameterTypeDefaultDescription
cursorstring—Opaque cursor from a previous response. Omit to start from the beginning.
limitinteger20Number of items per page. Range: 1–100.

​
Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "title": "Quantum computing basics",
      "createdAt": 1770681600,
      "updatedAt": 1770681900,
      "userId": "user_abc123",
      "status": "ongoing"
    },
    {
      "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "title": "Pricing questions",
      "createdAt": 1770595200,
      "updatedAt": 1770595500,
      "userId": "user_abc123",
      "status": "ended"
    }
  ],
  "pagination": {
    "cursor": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMC4wMDBaIiwiaWQiOiJhYmMxMjMifQ==",
    "hasMore": true,
    "total": 42
  }
}

​
Response Fields

FieldTypeDescription
idstringConversation ID.
titlestring | nullConversation title.
createdAtnumberUnix epoch timestamp (seconds).
updatedAtnumberUnix epoch timestamp (seconds) of last activity.
userIdstring | nullThe user ID associated with this conversation.
statusstringConversation status: ongoing, ended, or taken_over.

​
Pagination Examples

async function fetchUserConversations(agentId, userId, apiKey) {
  const conversations = [];
  let cursor = undefined;

  do {
    const params = new URLSearchParams({ limit: "100" });
    if (cursor) params.set("cursor", cursor);

    const response = await fetch(
      `https://www.chatbase.co/api/v2/agents/${agentId}/users/${userId}/conversations?${params}`,
      {
        headers: { Authorization: `Bearer ${apiKey}` },
      }
    );

    const { data, pagination } = await response.json();
    conversations.push(...data);
    cursor = pagination.cursor;
  } while (cursor);

  return conversations;
}

​
Full Example

1

Start a conversation with a user ID

Send the first message with a userId to associate the conversation:
curl -N -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "What is quantum computing?",
    "stream": true,
    "userId": "user_abc123"
  }'
Save the conversationId from the finish event.
2

Send a follow-up message

Continue the conversation by passing the conversationId:
curl -N -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "How does it differ from classical computing?",
    "stream": true,
    "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  }'
3

List the user's conversations

Retrieve all conversations for the user:
curl 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/users/user_abc123/conversations?limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Streaming

Learn about streaming responses and event types.

Pagination

How cursor-based pagination works across all list endpoints.