Send Message (Streaming)

Send Message (Streaming) allows a client application to send a user message to an AI agent and receive an AI-generated response as a stream.

This endpoint is designed for real-time chat experiences where the response should appear progressively while the AI agent is generating it. It is commonly used for web chat widgets, support bots, messaging interfaces, customer support automation, and conversational AI applications.

The client sends the user query along with the project ID, chatbot ID, and user context. The AI agent processes the request and streams response events back to the client.

Endpoint

Request Body

{
  "query": "Hello",
  "pid": "3..",
  "chatbot_id": "DKDvwn...",
  "user_context": {
    "session_id": "6ff922ed-9884-4430-83c9-7ac83a7b0574",
    "platform": "web"
  }
}

Request Parameters

Field	Type	Required	Description
`query`	string	Yes	User message or question sent to the chatbot.
`pid`	string	Yes	Project ID associated with the chatbot.
`chatbot_id`	string	Yes	Unique chatbot identifier that should process the message.
`user_context`	object	Yes	Additional context about the user, session, platform, or client application.
`user_context.session_id`	string	No	Unique session identifier used to continue or group messages in the same conversation.
`user_context.platform`	string	Yes	Platform or channel where the message originated. Example: `web`.

Success Response

The response is returned as a streaming response using server-sent event style chunks.

Each event is sent using the following format:

data: {...}

The stream ends with:

data: [DONE]

Example Streaming Response

data: {"type":"start","messageId":"zUqbj2SylMki95Be"}

data: {"type":"start-step"}

data: {"type":"text-start","id":"0"}

data: {"type":"text-delta","id":"0","delta":"Hello"}

data: {"type":"text-delta","id":"0","delta":"! How can I help you today?"}

data: {"type":"text-end","id":"0"}

data: {"type":"finish-step"}

data: {"type":"finish","finishReason":"stop"}

data: {"type":"data-session","data":"6ff922ed-9884-4430-83c9-7ac83a7b0574"}

data: {"type":"data-finish-reason","data":{"finishReason":"stop","rawFinishReason":"STOP"}}

data: [DONE]

Stream Event Types

Event Type	Description
`start`	Indicates that the streaming response has started. Usually includes the generated message ID.
`start-step`	Indicates that the agent has started a processing step.
`tool-input-start`	Indicates that the agent is preparing to call an available tool.
`tool-input-delta`	Streams partial tool input as it is being generated.
`tool-input-available`	Indicates that the complete tool input is available.
`tool-output-available`	Indicates that the tool has returned output.
`finish-step`	Indicates that a processing step has completed.
`text-start`	Indicates that the assistant text response has started.
`text-delta`	Streams a partial text token or text chunk from the assistant response.
`text-end`	Indicates that the assistant text response has completed.
`finish`	Indicates that the AI generation has completed.
`data-session`	Returns the conversation session ID associated with the response.
`data-finish-reason`	Returns the final completion reason for the response.
`[DONE]`	Indicates the end of the stream.

Important Stream Fields

`text-delta`

The text-delta event contains the AI-generated answer in small chunks.

{
  "type": "text-delta",
  "id": "0",
  "delta": "Hello! How can I help you today?"
}

Field	Type	Description
`type`	string	Event type. For streamed text chunks, the value is `text-delta`.
`id`	string	Identifier for the streamed text block.
`delta`	string	Partial text content generated by the AI agent.

`data-session`

The data-session event returns the conversation session ID.

{
  "type": "data-session",
  "data": "6ff922ed-9884-4430-83c9-7ac83a7b0574"
}

Field	Type	Description
`type`	string	Event type.
`data`	string	Session ID associated with the conversation.

`data-finish-reason`

The data-finish-reason event returns the completion reason.

{
  "type": "data-finish-reason",
  "data": {
    "finishReason": "stop",
    "rawFinishReason": "STOP"
  }
}

Field	Type	Description
`type`	string	Event type.
`data.finishReason`	string	Normalized reason why the response finished.
`data.rawFinishReason`	string	Raw finish reason returned by the underlying AI provider.

Error Responses

400 Bad Request

Returned when the request body is invalid or required fields are missing.

{
  "message": "Bad Request",
  "error": {
    "code": "BAD_REQUEST",
    "detail": "Invalid request body or missing required fields."
  }
}

401 Unauthorized

Returned when the request does not include a valid bearer token.

{
  "message": "Unauthorized",
  "error": {
    "code": "UNAUTHORIZED",
    "detail": "Authentication token is missing or invalid."
  }
}

Notes

Use this endpoint when you want the response to appear progressively in the client UI.

For a standard request where the full AI response is returned at once, use the non-streaming message API.

The client should listen for text-delta events and append each delta value to the visible chat response.

The stream is complete when the client receives data: [DONE].

Pass the same session_id in user_context to continue an existing conversation.

The final session ID is returned in the data-session event.

The response may include tool-related events when the chatbot uses configured tools or integrations during response generation.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Send Message (Streaming)

Endpoint#

Request Body#

Request Parameters#

Success Response#

Example Streaming Response#

Stream Event Types#

Important Stream Fields#

text-delta#

data-session#

data-finish-reason#

Error Responses#

400 Bad Request#

401 Unauthorized#

Notes#

Request

Responses