Skip to main content
GET
Open the live event stream (WebSocket)

Authorizations

Authorization
string
header
required

An API key of one app, sent as Authorization: Bearer <key>. Keys start with fk_test_ (test mode: sandbox senders and test data only) or fk_live_ (live mode). Keep live keys on your server; never ship them in an app or page.

Headers

Flow-Version
string<date>

The API version to use, as a date. Without it, the version pinned to your app when it was created is used.

Example:

"2026-11-01"

Query Parameters

after
string

An item ID. Returns the items that come after it in the list's order.

Maximum string length: 64
type
enum<string>[]

Only events of these types. Repeat the parameter for several.

Maximum array length: 20
  • message.received: the contact sent something with content (a button tap arrives as button_reply content).
  • message.sent, message.delivered, message.read, message.failed: the status of your outbound messages. message.failed carries the error in data.message.error.
  • reaction.added, reaction.removed: the contact reacted to a message.
  • typing.started, typing.stopped: the contact is typing, where the channel reports it.
  • conversation.started: the first inbound message from a new contact, or a sandbox join (Flow itself answers the join; the join message is not a message.received).
  • conversation.window_closing: WhatsApp only, opt-in. The 24-hour window closes in 1 hour.
  • sender.status_changed: a sender was throttled, flagged, banned or restored, or its WhatsApp quality rating changed.
  • template.status_changed: Meta approved, rejected or paused a template.
Available options:
message.received,
message.sent,
message.delivered,
message.read,
message.failed,
reaction.added,
reaction.removed,
typing.started,
typing.stopped,
conversation.started,
conversation.window_closing,
sender.status_changed,
template.status_changed

Response

Switching to the WebSocket protocol. The schema below describes each JSON frame on the socket, in either direction. A refused WebSocket request is upgraded too, then answered with one error frame and a 4000-range close code (see the description); the 4xx answers below are what a request without an upgrade gets.

One JSON frame on the /v1/stream WebSocket. The server sends event, ack, error and reconnect; the client sends send and start.

type
enum<string>
required

Always event.

Available options:
event
event
object
required

One entry in your app's log. type says what happened and selects the shape of data. conversation is set for every event that happened in a conversation (all but sender.status_changed and template.status_changed).