Run Multi-Turn Conversations with a Feather Assistant

The Feather conversation API is built around conversations — stateful sessions that track the full message history, context variables, and lifecycle for a single end-user interaction. Within a conversation you can send synchronous turns, stream tokens over SSE for real-time UIs, poll for operator replies during a human handoff, and retrieve a paginated transcript at any time. This guide walks through each operation with working examples.

Create a conversation

Open a conversation by binding an assistant and identifying the end user. Creating a conversation over the API always produces a chat, live session — channel and surface are assigned by Feather, not set by you.

curl -X POST https://api-sandbox.featherhq.com/v1/conversations \
  -H "x-api-key: $FEATHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "agt_01hx3k2mz9vbqwerty123456",
    "org_external_end_user_id": "customer-42"
  }'

{
  "id": "ses_01hxabc987654321fedcba00",
  "end_user_id": "usr_01hvbp4nrtemk6wjq8xcgdfy2s",
  "channel": "chat",
  "surface": "direct_api",
  "assistant_id": "agt_01hx3k2mz9vbqwerty123456",
  "assistant_revision_id": "rev_01hx3k9pq7rstuv234567890",
  "status": "active",
  "session_type": "live",
  "created_at": "2026-05-14T12:00:00Z"
}

Field	Notes
`assistant_id`	The assistant to run. Bind a team instead with `team_id` + `team_revision_id` — never both.
`org_external_end_user_id`	Your own stable identifier for the user. Feather get-or-creates an end user for it. Pass an existing `end_user_id` instead if you have one.
`external_id`	Optional thread key — reuse it to resume a thread, or send a new value to open a concurrent one.

Pass a context_variables object in the request body to seed the conversation with pre-known data — for example, {"customer_name": "Alex", "account_tier": "premium"}. These values are available to the assistant’s prompt and tools.

Send turns (synchronous)

For standard request/response flows, post a turn and wait for the full reply.

curl -X POST https://api-sandbox.featherhq.com/v1/conversations/ses_01hxabc987654321fedcba00/turns \
  -H "x-api-key: $FEATHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_message": "I need help with my order #12345"
  }'

{
  "turn_id": "trn_01hxbcd111222333444aaaa",
  "conversation_id": "ses_01hxabc987654321fedcba00",
  "text": "I'd be happy to help with order #12345! Let me look that up for you right now.",
  "session_status": "active",
  "message_seqs": [2, 3],
  "ended": false
}

Field	Description
`turn_id`	Unique identifier for this turn
`text`	The assistant’s final reply
`session_status`	Current status (`active`, `awaiting_approval`, `waiting_for_human`, `closed`, …)
`message_seqs`	Sequence numbers of the messages written this turn — order by `seq`, not timestamp
`ended`	`true` if the assistant closed the conversation this turn

If session_status becomes waiting_for_human or awaiting_approval, stop sending turns and poll for messages (below) until it returns to active or the conversation closes. Set include_evidence: true on the request to receive the knowledge-base chunks used to generate the reply.

Stream turns (SSE)

For chat UIs where you want to render tokens as they arrive, use the streaming endpoint. It returns a Server-Sent Events stream with the same request body as the synchronous turn endpoint.

curl -X POST https://api-sandbox.featherhq.com/v1/conversations/ses_01hxabc987654321fedcba00/turns/stream \
  -H "x-api-key: $FEATHER_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "user_message": "What is the status of my order?"
  }'

const response = await fetch(
  'https://api-sandbox.featherhq.com/v1/conversations/ses_01hxabc987654321fedcba00/turns/stream',
  {
    method: 'POST',
    headers: {
      'x-api-key': `${process.env.FEATHER_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ user_message: 'What is the status of my order?' }),
  }
);

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

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

  buffer += decoder.decode(value, { stream: true });

  // SSE frames are separated by a blank line; each frame has an
  // `event:` line and a `data:` line.
  let sep;
  while ((sep = buffer.indexOf('\n\n')) !== -1) {
    const frame = buffer.slice(0, sep);
    buffer = buffer.slice(sep + 2);

    let eventName = 'message';
    let data = '';
    for (const line of frame.split('\n')) {
      if (line.startsWith('event:')) eventName = line.slice(6).trim();
      else if (line.startsWith('data:')) data += line.slice(5).trim();
    }
    if (!data) continue;
    const payload = JSON.parse(data);

    if (eventName === 'delta') {
      process.stdout.write(payload.text); // stream tokens to UI
    } else if (eventName === 'complete') {
      console.log('\n\nFull turn:', payload); // final turn object (inline fields)
    } else if (eventName === 'error') {
      console.error('Stream error:', payload.error);
    }
  }
}

Example SSE stream:

event: delta
data: {"text":"Your order "}

event: delta
data: {"text":"#12345 was "}

event: delta
data: {"text":"shipped on May 13th and is expected to arrive by May 16th."}

event: complete
data: {"turn_id":"trn_01hxbcd111222333444bbbb","conversation_id":"ses_01hxabc987654321fedcba00","text":"Your order #12345 was shipped on May 13th and is expected to arrive by May 16th.","active_assistant_id":"agt_01hx3k2mz9vbqwerty123456","session_status":"active","message_seqs":[4,5],"turn_ttft_ms":312,"ended":false}

Event types — branch on the SSE event: name, not on any field inside the payload:

SSE `event:`	Data payload
`delta`	`{"text": "..."}` — an incremental token to append to the UI
`member`	`{member_id, arrival_source, index}` — a team member became active
`complete`	The final turn object with fields inline — treat this as the source of truth
`error`	`{"error": "...", "retryable": true｜false}` — a fatal error; the stream closes after this event

Always handle the error event explicitly. If the stream closes without a complete event, assume the turn failed and surface an appropriate message.

Poll messages (for async channels and handoffs)

When your assistant is connected to an asynchronous channel (email, SMS) or the conversation is in a human handoff, poll for new messages rather than holding an open HTTP connection.

curl "https://api-sandbox.featherhq.com/v1/conversations/ses_01hxabc987654321fedcba00/messages?since_seq=-1" \
  -H "x-api-key: $FEATHER_API_KEY"

{
  "session_status": "waiting_for_human",
  "next_seq": 7,
  "messages": [
    {
      "seq": 6,
      "role": "assistant",
      "content": "I'm connecting you with a support specialist now. Please hold on.",
      "created_at": "2026-05-14T12:05:00Z"
    },
    {
      "seq": 7,
      "role": "assistant",
      "content": "Hi, this is Jamie from support. How can I help you today?",
      "created_at": "2026-05-14T12:06:45Z"
    }
  ]
}

Pass since_seq=-1 on the first request to retrieve every message. On subsequent polls, pass the previous response’s next_seq to receive only new messages. Both AI replies and human-operator relays arrive on this stream during a handoff.

During a handoff, poll every 2–5 seconds while session_status is waiting_for_human. Once it returns to active, the operator has handed control back and you can resume turn-based messaging.

Close a conversation

Signal that the conversation is resolved by closing it. This finalizes the session for memory sync, extraction, and analytics.

curl -X POST https://api-sandbox.featherhq.com/v1/conversations/ses_01hxabc987654321fedcba00/close \
  -H "x-api-key: $FEATHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "resolved"
  }'

A conversation must be closed before it can be deleted. Attempting to delete a live conversation returns a 409 Conflict.

Retrieve the transcript

Fetch a paginated list of messages in a conversation — useful for post-session review, debugging, or exporting logs.

curl "https://api-sandbox.featherhq.com/v1/conversations/ses_01hxabc987654321fedcba00/turns?limit=20" \
  -H "x-api-key: $FEATHER_API_KEY"

{
  "turns": [
    {
      "seq": 0,
      "role": "user",
      "content": "I need help with my order #12345",
      "created_at": "2026-05-14T12:01:00Z"
    },
    {
      "seq": 1,
      "role": "assistant",
      "content": "I'd be happy to help with order #12345! Let me look that up for you right now.",
      "created_at": "2026-05-14T12:01:02Z"
    }
  ],
  "next_cursor": "dHVybl8wMWh4YmNkMTExMjIyMzMzNDQ0YmJiYg==",
  "has_more": false
}

Paginate by passing cursor=<next_cursor> and limit=<n>. When has_more is false, you’ve reached the end of the transcript. For a bulk, encrypted export across many conversations, use Export Conversations.

Get Started

Core Concepts

Guides

Channels

Run Multi-Turn Conversations with a Feather Assistant

Create a conversation

Send turns (synchronous)

Stream turns (SSE)

Poll messages (for async channels and handoffs)

Close a conversation

Retrieve the transcript

What’s next?

Conversations concept

Human-in-the-loop

​Create a conversation

​Send turns (synchronous)

​Stream turns (SSE)

​Poll messages (for async channels and handoffs)

​Close a conversation

​Retrieve the transcript

​What’s next?

Conversations concept

Human-in-the-loop

Create a conversation

Send turns (synchronous)

Stream turns (SSE)

Poll messages (for async channels and handoffs)

Close a conversation

Retrieve the transcript

What’s next?