Conversational Flow Chat API

Overview

Deployed conversational Flows expose a chat session API on the automation URL. Instead of a single /kickoff run, you create a session, send user messages as turns, optionally stream tokens and runtime events, and resume HITL pauses when a turn needs human feedback.

Conversational Flow chat is experimental. Endpoints are available only when the deployed Flow reports both conversational: true and handle_turn: true from GET /inspect.

For building the Flow itself (conversational = True, handle_turn, routers, tracing), see the open-source Conversational Flows guide.

Prerequisites

Deploy a Flow automation that implements conversational turns (handle_turn).
Copy the bearer token from the automation Status tab (same token used for /kickoff).
Confirm chat is enabled via /inspect (below).

All requests use:

Authorization: Bearer YOUR_FLOW_TOKEN

Base URL examples in this guide use https://your-flow-url.crewai.com.

Discover chat capability

curl -X GET \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  https://your-flow-url.crewai.com/inspect

Look for flow.chat:

{
  "flow": {
    "chat": {
      "conversational": true,
      "handle_turn": true,
      "transports": ["webhook"],
      "experimental": true
    }
  }
}

If either flag is false, chat endpoints return 404 with "Conversational flow chat is not available".

End-to-end chat loop

Start a session

Create a chat session. Optionally register a completed-turn webhook and event webhooks for the session lifetime.

curl -X POST \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "completedTurnWebhookUrl": "https://your-server.com/webhooks/completed-turn",
    "webhooks": {
      "url": "https://your-server.com/webhooks/events",
      "events": ["*"],
      "realtime": false,
      "authentication": {
        "strategy": "bearer",
        "token": "my-secret-token"
      }
    }
  }' \
  https://your-flow-url.crewai.com/chat/start

Response:

{ "session_id": "11111111-2222-3333-4444-555555555555" }

An empty body ({} or no body) is valid when you do not need webhooks.

Send a user message

Queue one turn for the session:

curl -X POST \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Where is my order?",
    "stream": true
  }' \
  https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/message

Response:

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "queued"
}

Field	Description
`message`	Required. Current user line for this turn.
`stream`	Default `true`. When `true`, token/event frames are published for WebSocket/SSE clients.
`messageHistory`	Optional fallback transcript (`[{ "role", "content" }, ...]`). Server-side session history is authoritative; this is used only when stored history is empty.

Roles accepted in messageHistory: user, assistant, system, tool.

Wait for the turn to finish

Poll the turn with the returned kickoff_id (same status API as a normal Flow kickoff):

curl -X GET \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  https://your-flow-url.crewai.com/status/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Only one turn can be active per session. A second /message while active_kickoff_id is set returns 409:

{
  "detail": {
    "code": "session_busy",
    "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

Wait until history shows active_kickoff_id: null (or the turn reaches a terminal status / pause) before sending the next message.

Read session history

curl -X GET \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/history

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "messages": [
    { "role": "user", "content": "Where is my order?" },
    { "role": "assistant", "content": "Your order is on the way." }
  ],
  "active_kickoff_id": null
}

Streaming a turn

Streaming is optional. Use it when a UI needs tokens or runtime events as the turn runs. Frames always include lifecycle types (turn_started, turn_completed, turn_failed, token, error). Additional event frames can be filtered with the events query parameter (* or a comma-separated list).

Option A: HTTP message + SSE attach

POST /chat/{session_id}/message with "stream": true.
Attach to the active turn:

curl -N \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  "https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/stream/events?events=*&last_event_id=0-0"

SSE returns text/event-stream JSON frames (data: {...}), plus keepalive comments. The stream ends on turn_completed or turn_failed. If there is no active turn, this endpoint returns 409 (No active chat turn).

Option B: WebSocket (attach or send)

wss://your-flow-url.crewai.com/chat/{session_id}/stream?token=YOUR_FLOW_TOKEN&events=*&last_event_id=0-0

Auth: pass the bearer token as the token query param, or as an Authorization: Bearer ... header when your client supports WebSocket headers. Behavior:

Active turn already running — the socket attaches and first emits turn_started with data.status: "attached", then streams frames until a terminal type.
No active turn — send a JSON message to queue a turn, then consume the stream:

{
  "message": "Where is my order?",
  "messageHistory": [],
  "events": "*",
  "lastEventId": "0-0"
}

The server responds with turn_started (status: "queued") and then stream frames for that kickoff_id. Use last_event_id / lastEventId to resume after disconnects.

Example stream frames

{
  "type": "turn_started",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": { "status": "queued" }
}

{
  "type": "token",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": { "content": "Your order" }
}

{
  "type": "turn_completed",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": {}
}

HITL inside a chat session

If a turn pauses for human feedback (status / state PAUSED), resume with the same Flow resume endpoint used for non-chat runs:

curl -X POST \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "FLOW_OR_SESSION_ID",
    "feedback": "approved"
  }' \
  https://your-flow-url.crewai.com/resume_feedback

Then poll the resume kickoff_id from the response. Wait until /history shows active_kickoff_id: null before sending the next chat message. See HITL Workflows and Flow HITL Management for platform review UX.

API reference

Method	Path	Purpose
`GET`	`/inspect`	Discover whether conversational chat is enabled
`POST`	`/chat/start`	Create a chat session
`POST`	`/chat/{session_id}/message`	Queue a user turn
`GET`	`/chat/{session_id}/history`	Read messages and active turn id
`GET`	`/chat/{session_id}/stream/events`	SSE stream for the active turn
`WS`	`/chat/{session_id}/stream`	WebSocket stream (attach or send + stream)
`GET`	`/status/{kickoff_id}`	Poll turn (or resume) execution status
`POST`	`/resume_feedback`	Resume a paused HITL turn

Common errors

Status	When
`400`	Empty `message`
`404`	Chat not enabled on this deployment, or unknown `session_id`
`409`	Session already has an active turn (`session_busy`), or SSE attach with no active turn
`422`	`session_id` is not a valid UUID
`503`	Chat session or stream storage unavailable

Conversational Flows

Build multi-turn Flows with handle_turn, routers, and tracing.

Kickoff Crew / Flow

Single-run kickoff and status polling on a deployment URL.

Webhook Streaming

Event webhook payload shape and authentication options.

Flow HITL Management

Email-first human review for paused Flow steps.

Getting Started

Build

Operate

Manage

Integration Docs

Triggers

How-To Guides

Resources

Conversational Flow Chat API

Overview

Prerequisites

Discover chat capability

End-to-end chat loop

Streaming a turn

Option A: HTTP message + SSE attach

Option B: WebSocket (attach or send)

Example stream frames

HITL inside a chat session

API reference

Common errors

Conversational Flows

Kickoff Crew / Flow

Webhook Streaming

Flow HITL Management

​Overview

​Prerequisites

​Discover chat capability

​End-to-end chat loop

​Streaming a turn

​Option A: HTTP message + SSE attach

​Option B: WebSocket (attach or send)

​Example stream frames

​HITL inside a chat session

​API reference

​Common errors

​Related

Conversational Flows

Kickoff Crew / Flow

Webhook Streaming

Flow HITL Management

Overview

Prerequisites

Discover chat capability

End-to-end chat loop

Streaming a turn

Option A: HTTP message + SSE attach

Option B: WebSocket (attach or send)

Example stream frames

HITL inside a chat session

API reference

Common errors

Related