Skip to main content

Start a streaming message

POST 
/chat.startStream

Open a streaming message and post its first content. Streaming lets a bot deliver a message incrementally — recipients see the text fill in live (with a "typing…" indicator) instead of waiting for the full response. This is useful for AI agents that produce text token-by-token.

A stream has three steps, each its own request:

  1. /chat.startStream — open the stream and pick the destination. Returns a streamId.
  2. /chat.appendStream — append chunks of text (call as many times as needed).
  3. /chat.stopStream — finalize the stream into a single persisted message.

Pass the streamId returned here to every subsequent appendStream and stopStream. The sender, destination, and thread are fixed for the lifetime of the stream.

Custom sender (optional): same semantics as /chat.post — sender.name / sender.imageUrl apply a per-message display override to the finalized message, and sender.id authors the stream as a configured bot persona (unknown ids are accepted and ignored). The typing indicator shown while streaming uses the override name when given, otherwise the persona's or app's configured name. See the Sender Profiles guide.

Access: Organization and Personal. Organization tokens follow the same public-group carveout as /chat.post: the bot may stream into a public group in its roam without joining. Personal tokens can stream only where the owner is a member (403 not_in_chat for an unjoined public group) and reject the sender field.

Required scope: chat:send_message or chat:write

Destination​

Provide exactly one of chatId, groupId, or userIds. If text is empty, the destination is recorded but message creation is deferred until the first non-empty appendStream or the stopStream call.

Thinking streams​

Set kind to thinking to finalize the message as a thought-bubble; clients show a "thinking…" indicator instead of "typing…". The default kind is text.

Limits​

  • Up to 10 concurrent streams per API client.
  • Only one active stream per chat at a time.
  • Accumulated text may not exceed the regular message size limit.

OpenAPI Spec: chat-v1.json

Request​

Responses​

Stream started.