Chat

The chat endpoints power all agent interactions. Send messages, create conversations with welcome messages, and receive responses with optional streaming.

All API requests require a valid JWT token in the Authorization: Bearer <token> header. The API Gateway decodes the JWT and forwards auth context (user-id, organization-id, user-email, x-platform-role, x-org-role) as headers to downstream services.

This endpoint incurs provider cost and records a billing event via record_external_cost_event(). Credits are deducted from the organization’s wallet based on the configured margin multiplier.

Send Message

Send a message to an agent and receive a response. This is the core chat endpoint that orchestrates RAG context retrieval, prompt resolution, and LLM completion.

Path Parameters

string

required

Agent UUID.

Request Body

string

required

User message text. 1-10,000 characters.

string

Existing conversation UUID to continue. If omitted, a new conversation is created.

boolean

default:"false"

Enable streaming response via Server-Sent Events (SSE). Only works if the agent also has streamingEnabled: true.

object

Key-value pairs of template variables to merge into the conversation context. These are rendered into the system prompt.

object[]

File attachments to include with the message.

Show Attachment object

string

required

Attachment UUID (from upload endpoint).

string

required

Access token for the attachment.

boolean

default:"false"

Include a voice audio response (requires agent voice enabled).

string

Override system prompt for this message only. Max 10,000 characters.

Response (200) — Non-Streaming

string

The agent’s text response.

string

Conversation UUID (new or existing).

string

The response message UUID.

object[]

Knowledge base sources used to generate the response.

Show Source object

string

Chunk text content.

number

Relevance score (0-1).

string

Source document title.

string

Source KB UUID.

object

Token usage and cost information.

Show Usage object

number

Input tokens used.

number

Output tokens generated.

number

Total tokens.

number

Estimated cost in USD.

curl -X POST https://your-domain.com/api/bots/AGENT_ID/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is your return policy?",
    "conversationId": "conv-uuid-here",
    "stream": false
  }'

const response = await fetch(
  `https://your-domain.com/api/bots/${agentId}/chat`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message: "What is your return policy?",
      conversationId: "conv-uuid-here",
    }),
  }
);

const data = await response.json();
console.log(data.response);       // Agent's answer
console.log(data.sources);        // KB sources cited

Streaming Response (SSE)

When stream: true is set and the agent has streaming enabled, the response is delivered as Server-Sent Events:

const response = await fetch(`https://your-domain.com/api/bots/${agentId}/chat`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "Tell me about your product",
    stream: true,
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  // SSE format: "data: {\"token\":\"Hello\"}\n\n"
  const lines = chunk.split("\n");
  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const data = JSON.parse(line.slice(6));
      if (data.token) {
        process.stdout.write(data.token);
      }
      if (data.done) {
        // Final event includes sources and usage
        console.log(data.sources);
        console.log(data.usage);
      }
    }
  }
}

Chat Pipeline

The full processing pipeline for each message:

Validate input and extract attachment content (text, images from PDFs/DOCX)
Merge per-message variables into conversation variables
RAG retrieval across all linked knowledge bases:
- Build enhanced query from last 5 messages + attachment text
- Vector search (top 3 per KB, minimum score 0.35)
- Hybrid reranking: 60% vector similarity + 25% text relevance + 15% importance weight
- Deduplication: max 2 chunks per document
- Post-filter: minimum 0.25 combined score
Fetch KB document registry (document map) for agent awareness
Graph entity search for structured context
Resolve system prompt (agent config -> system default -> code fallback)
Render system prompt with conversation variables
Call LLM via LangChain with full context
Save messages, record billing, return response

Create Conversation

Create a new conversation with an agent. Optionally generates a welcome message based on the agent’s welcome prompt configuration.

Path Parameters

string

required

Agent UUID.

Request Body

object

Initial template variables for the conversation (e.g., user name, context).

string

Signed context token containing sensitive variables (generated via the context token endpoint).

Response (201)

boolean

Always true on success.

object

Show data object

string

New conversation UUID.

string

Welcome message content (if configured). May be a fixed string or LLM-generated.

Welcome Message Modes

The welcome message behavior depends on the agent’s welcome prompt config:

No config / disabled: Conversation created with no welcome message
Fixed mode: Returns the rendered content template directly
Generated mode: Sends the prompt to the LLM and returns the generated response (billable)

curl -X POST https://your-domain.com/api/bots/AGENT_ID/conversations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "userName": "Jane",
      "plan": "premium"
    }
  }'

const response = await fetch(
  `https://your-domain.com/api/bots/${agentId}/conversations`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      variables: { userName: "Jane", plan: "premium" },
    }),
  }
);

const { data } = await response.json();
const { conversationId, welcomeMessage } = data;

List Conversations

List conversations for the authenticated user, with optional filters.

Query Parameters

string

Filter by agent UUID.

string

Filter by user UUID. Defaults to current user.

string

Filter by platform (e.g., web, api).

number

default:"50"

Maximum results.

number

default:"0"

Pagination offset.

Response (200)

object[]

Array of conversation objects.

object

Show Pagination

number

boolean

Get Conversation

Get a single conversation by ID, including metadata.

Path Parameters

string

required

Conversation UUID.

Get Messages

Retrieve all messages in a conversation.

Path Parameters

string

required

Conversation UUID.

Preview Chat (Draft Config)

Test a chat interaction using the agent’s draft (unpublished) configuration. Useful for testing prompt changes before publishing.

Path Parameters

string

required

Agent UUID.

Request Body

Same as Send Message.

Preview chat uses the agent’s current draft prompt configurations rather than the published ones. This allows testing system prompt changes without affecting live users.

Conversation Variables

Set Variables

Set server-side or sensitive variables on an existing conversation. These are merged into the conversation’s variable store.

Get Variables

Get current conversation variables. Sensitive variables are excluded from the response.

Generate Context Token

Generate a signed context token for passing sensitive variables (e.g., user PII, auth context) that should not be exposed in client-side code. The token is passed when creating a conversation.

Getting Started

Agent Provisioning

Bot Service

Auth Service

Knowledge Service

Chat

Chat

Send Message

Path Parameters

Request Body

Response (200) — Non-Streaming

Streaming Response (SSE)

Chat Pipeline

Create Conversation

Path Parameters

Request Body

Response (201)

Welcome Message Modes

List Conversations

Query Parameters

Response (200)

Get Conversation

Path Parameters

Get Messages

Path Parameters

Preview Chat (Draft Config)

Path Parameters

Request Body

Conversation Variables

Set Variables

Get Variables

Generate Context Token

​Chat

​Send Message

​Path Parameters

​Request Body

​Response (200) — Non-Streaming

​Streaming Response (SSE)

​Chat Pipeline

​Create Conversation

​Path Parameters

​Request Body

​Response (201)

​Welcome Message Modes

​List Conversations

​Query Parameters

​Response (200)

​Get Conversation

​Path Parameters

​Get Messages

​Path Parameters

​Preview Chat (Draft Config)

​Path Parameters

​Request Body

​Conversation Variables

​Set Variables

​Get Variables

​Generate Context Token

Chat

Send Message

Path Parameters

Request Body

Response (200) — Non-Streaming

Streaming Response (SSE)

Chat Pipeline

Create Conversation

Path Parameters

Request Body

Response (201)

Welcome Message Modes

List Conversations

Query Parameters

Response (200)

Get Conversation

Path Parameters

Get Messages

Path Parameters

Preview Chat (Draft Config)

Path Parameters

Request Body

Conversation Variables

Set Variables

Get Variables

Generate Context Token