Send text with buttons

POST https://api.flow.engineer/v0/conversations/{conversation_id}/buttons Try it

Channel	Works	Limits
Telegram	Yes	1 to 10 buttons, reply and URL buttons mixed; `text` 4096 UTF-16 code units, 1024 with a media `header`
WhatsApp	Yes	1 to 3 reply buttons, or exactly one URL button (a call-to-action link); `text` 1024 characters
iMessage	No
SMS (US, pilot)	No

On iMessage and SMS, send instead: a basic message whose text lists the choices; the contact answers in words, as a basic message.

Sends text with buttons under it, optionally with a header (an image, video, document or a short title) above the text. A tap on a reply button arrives as a message.received event with a button_reply message carrying the button's id; a URL button opens its link and sends nothing back.

On WhatsApp, more than 3 buttons answer 422 unsupported_content with param buttons (send a list instead, up to 10 rows), and so does a mix of reply and URL buttons or more than one URL button. A message whose only button is one URL button goes as WhatsApp's call-to-action URL message: the text, the header if given, and one button that opens the link. Footers are not supported.

On Telegram, a media header makes one message: the photo, video or document with text as its caption and the buttons under it, so text must fit Telegram's caption limit of 1024 UTF-16 code units. A text header is the message's first line, in bold. On WhatsApp the header is the top of the same message bubble.

iMessage and SMS answer 422 unsupported_content with param kind. Sends to one conversation go out in the order they were accepted (see "Order and duplicates").

Authorizations

Authorizationstringheaderrequired

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-Versionstring<date>

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

Idempotency-Keystring

A unique string (up to 255 characters) that makes this request safe to retry. A repeat with the same key within 24 hours returns the first answer instead of acting again. See "Idempotency" in the introduction.

Length: 1 to 255

Path Parameters

conversation_idstringrequired

The conversation's ID.

Body application/json

kind string

Always buttons. Optional on its endpoint; required where no URL names the kind.

Default: "buttons"

header ContentHeader

What is shown above a buttons message's text, or a carousel card's image or video: an image, a video, a document or a short title. A media header takes exactly one of url (an HTTPS URL Flow fetches) or file_id (from POST /v0/files), and is fetched and checked for the channel like a basic message's media (so WebP and other formats work); a text header takes text. Anything else, or a value over a limit, is refused with 400 invalid_request naming the field in param.

WhatsApp shows the header at the top of the same message bubble. Telegram sends one message: the media with the text as its caption and the buttons under it; a text header is the message's first line, in bold.

Show child attributes

type enum<string> required

What the header holds.

Available options: image, video, document, text

url string<uri>

Media headers only. An HTTPS URL of the media, which Flow fetches.

file_id string

A file ID, file_ and a ULID.

Pattern: ^file_[0-9A-HJKMNP-TV-Z]{26}$

text string

text headers only. The title, 1 to 60 characters (WhatsApp's header limit).

Length: 1 to 60

filename string

document headers only. The file's name, shown with the document.

Length: 0 to 255

text string required

The text above the buttons, sent exactly as written: at most 4096 UTF-16 code units on Telegram, or 1024 when the message has a media header (Telegram's caption limit), and 1024 characters on WhatsApp (its limit for messages with buttons). Longer text is refused with 400 invalid_request.

Length: 1 to 4096

buttons Button[] required

The buttons, in order: 1 to 10 on Telegram; on WhatsApp 1 to 3 reply buttons or exactly one URL button (anything else answers 422 unsupported_content with param buttons; send a list for more choices).

Items: 1 to 10

Show child attributes

One of 2 options:

ReplyButton

A button that sends its id back as a button_reply when tapped.

id string required

Your ID for the button, returned in button_reply as button_id: 1 to 64 bytes (Telegram's limit for a button's data), so at most 64 ASCII characters and fewer for other characters. Labels may repeat; the ID is what tells the taps apart, so buttons that share a label (a "Details" on every card) get their own IDs, such as details:listing-17.

Length: 1 to 64

label string required

The button's text. WhatsApp shows at most 20 characters.

Length: 1 to 20

UrlButton

A button that opens a link.

url string<uri> required

The HTTPS link to open.

label string required

The button's text.

Length: 1 to 20

reply_to string

Send this as an inline reply to an earlier message in the same conversation (Telegram, WhatsApp and iMessage show it quoted). SMS has no inline replies: there it answers 422 unsupported_content with param reply_to. Refused with 404 not_found (param reply_to) when the target is not a message in this conversation, and with 400 invalid_request (param reply_to) when the target never reached the channel (for example, it failed). If the target fails after the send was accepted, the reply goes out as a normal message.

Pattern: ^msg_[0-9A-HJKMNP-TV-Z]{26}$

telegram ButtonsTelegramOptions

Telegram only: how the message looks and notifies on Telegram. On another channel the block answers 422 unsupported_content with param telegram; an unknown key 400 invalid_request.

Show child attributes

parse_mode enum<string>

How Telegram reads the text: HTML or MarkdownV2, Telegram's own formatting (see Telegram's Bot API, "Formatting options"). Without it the text is plain. Text that Telegram cannot parse is refused by Telegram: the message fails (message.failed, channel_error).

Available options: HTML, MarkdownV2

disable_notification boolean

Deliver silently, with no sound.

protect_content boolean

Stop the contact forwarding or saving the message.

metadata Metadata

Up to 20 string pairs of your own, kept with the object and returned unchanged. Keys up to 40 characters, values up to 500.

Response

202 application/json

The message passed the gate and is queued for the channel.

id string required

A message ID, msg_ and a ULID.

Pattern: ^msg_[0-9A-HJKMNP-TV-Z]{26}$

conversation string required

A conversation ID, conv_ and a ULID.

Pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$

direction enum<string> required

in from the contact, out from your app.

Available options: in, out

from string read-only

Inbound messages only, on every channel. The contact who wrote it; in a group conversation, which participant. Absent on your own messages.

Pattern: ^ct_[0-9A-HJKMNP-TV-Z]{26}$

status enum<string> required

received: inbound from the contact.
queued: accepted by the gate, waiting for its turn in the conversation.
sent: the channel accepted it.
delivered: it reached the contact's device, where the channel reports this.
read: the contact read it, where the channel reports this.
failed: it could not be sent; see error.
unsent: you unsent it.

Available options: received, queued, sent, delivered, read, failed, unsent

content MessageContent required

A message's content: one kind object, in either direction, with kind (always present here) saying which. It is exactly what was sent or received, except metadata, which is kept once, at the message's own metadata, and not repeated here.

Show child attributes

kind enum<string> required

The kinds of message. A closed list: a new kind arrives only with a new API version. Each kind has its own schema (BasicMessage, VoiceMessage, ...) and, where it can be sent over HTTP, its own endpoint of the same name (POST /v0/conversations/{conversation_id}/<kind>, with contact-card for contact_card). edit and unsend are sent over HTTP with PATCH and DELETE /v0/messages/{message_id}, and are kinds in webhook replies, on the stream and in a message's content. button_reply and file_blocked are inbound only.

Received from a contact: basic, voice, button_reply, reaction, location, contact_card and file_blocked. Sent: every kind but button_reply and file_blocked.

Available options: basic, voice, buttons, list, carousel, template, contact_card, location, effect, reaction, typing, read, edit, unsend, button_reply, file_blocked

One of 16 options, chosen by `kind`:

kind: basic

A basic message with kind given, as in a message's content, a webhook reply or a stream frame (BasicMessage with kind required).

kind string required

Always basic. Optional on POST /v0/conversations/{conversation_id}/basic; required where no URL names the kind (webhook replies, the stream, starts, a message's content).

Default: "basic"

text string

The text, sent exactly as written: no markdown, no stripping. At most 4096 UTF-16 code units on Telegram (an emoji such as 😀 counts as 2), 4096 characters on WhatsApp, 9999 on iMessage, and 10 segments on SMS (see SmsSegments). With media it is the caption, at most 1024 (UTF-16 code units on Telegram). Optional when media is given. Longer text is refused with 400 invalid_request.

Length: 1 to 9999

media Media

One image, video, document or audio file. When sending, give exactly one of url (an HTTPS URL Flow fetches; Flow neither stores nor scans it, and on Telegram a document by URL works for PDF and ZIP files) or file_id (from POST /v0/files). Each channel takes files up to its own size: Telegram 50 MB, WhatsApp and iMessage 100 MB, SMS (MMS) 5 MB; a larger file answers 422 unsupported_content with param media. SMS carries images, audio and video, never documents (param media.type), and only from numbers with MMS (channel_code no_mms).

Show child attributes

type enum<string> required

What kind of file it is.

Available options: image, video, document, audio

url string<uri>

Where the bytes are. Sending, an HTTPS URL Flow can fetch; inbound, a Flow file URL.

file_id string

A file ID, file_ and a ULID.

Pattern: ^file_[0-9A-HJKMNP-TV-Z]{26}$

filename string

The file's name, shown for documents and taken only with type document (on another type it answers 422 unsupported_content with param media.filename). On Telegram it works only with file_id: Telegram names a document sent by url itself, so filename with url answers 422 unsupported_content with param media.filename.

Length: 0 to 255

mime_type string read-only

Inbound only. The real type, checked from the file's first bytes.

size_bytes integer read-only

Inbound only. The file's size.

reply_to string

Pattern: ^msg_[0-9A-HJKMNP-TV-Z]{26}$

link_preview boolean

Whether links in the text show a rich preview. Left out, the channel's default applies (Telegram, WhatsApp and iMessage show previews). false sends links as plain text. SMS never shows previews, and no channel shows one on a media message: false is accepted there, and true on SMS or with media answers 422 unsupported_content with param link_preview.

telegram BasicTelegramOptions

Telegram only: how the message looks and notifies on Telegram. On another channel the block answers 422 unsupported_content with param telegram; an unknown key 400 invalid_request.

Show child attributes

parse_mode enum<string>

Available options: HTML, MarkdownV2

disable_notification boolean

Deliver silently, with no sound.

protect_content boolean

Stop the contact forwarding or saving the message.

show_caption_above_media boolean

Media only. Show the caption above the photo or video instead of below it.

has_spoiler boolean

Media only (photos and videos). Cover it with a spoiler animation until tapped.

imessage BasicImessageOptions

iMessage only: styles and a subject line. On another channel the block answers 422 unsupported_content with param imessage; an unknown key 400 invalid_request. A message that goes by SMS or RCS (see Message.network) shows neither.

Show child attributes

styles ImessageStyle[]

Styled ranges of text (see ImessageStyle). Each range must lie within text; one that does not answers 400 invalid_request naming it (imessage.styles[0]).

Show child attributes

start integer required

Where the range starts, in UTF-16 code units from the start of text.

Range: 0 to any

length integer required

How long the range is, in UTF-16 code units.

Range: 1 to any

style enum<string> required

The style. big and small set the text's size; shake, nod, explode, ripple, bloom and jitter animate it.

Available options: bold, italic, underline, strikethrough, big, small, shake, nod, explode, ripple, bloom, jitter

subject string

iMessage's subject line, shown in bold above the text.

Length: 1 to 200

metadata Metadata

Up to 20 string pairs of your own, kept with the object and returned unchanged. Keys up to 40 characters, values up to 500.

kind: voice

A voice message with kind given, as in a message's content, a webhook reply or a stream frame (VoiceMessage with kind required).

kind string required

Always voice. Optional on its endpoint; required where no URL names the kind.

Default: "voice"

url string<uri>

Where the audio is. Sending, an HTTPS URL Flow can fetch; inbound, a Flow file URL.

file_id string

A file ID, file_ and a ULID.

Pattern: ^file_[0-9A-HJKMNP-TV-Z]{26}$

reply_to string

Pattern: ^msg_[0-9A-HJKMNP-TV-Z]{26}$

metadata Metadata

Up to 20 string pairs of your own, kept with the object and returned unchanged. Keys up to 40 characters, values up to 500.

duration_seconds number read-only

Inbound only. The voice note's length.

transcript string read-only

Inbound only, on iMessage, when iMessage made a transcript of the voice note. What was said.

kind: buttons

A buttons message with kind given, as in a message's content, a webhook reply or a stream frame (ButtonsMessage with kind required).

kind string required

Always buttons. Optional on its endpoint; required where no URL names the kind.

Default: "buttons"

header ContentHeader

Show child attributes

type enum<string> required

What the header holds.

Available options: image, video, document, text

url string<uri>

Media headers only. An HTTPS URL of the media, which Flow fetches.

file_id string

A file ID, file_ and a ULID.

Pattern: ^file_[0-9A-HJKMNP-TV-Z]{26}$

text string

text headers only. The title, 1 to 60 characters (WhatsApp's header limit).

Length: 1 to 60

filename string

document headers only. The file's name, shown with the document.

Length: 0 to 255

text string required

Length: 1 to 4096

buttons Button[] required

Items: 1 to 10

Show child attributes

One of 2 options:

ReplyButton

A button that sends its id back as a button_reply when tapped.

id string required

Length: 1 to 64

label string required

The button's text. WhatsApp shows at most 20 characters.

Length: 1 to 20

UrlButton

A button that opens a link.

url string<uri> required

The HTTPS link to open.

label string required

The button's text.

Length: 1 to 20

reply_to string

Pattern: ^msg_[0-9A-HJKMNP-TV-Z]{26}$

telegram ButtonsTelegramOptions

Telegram only: how the message looks and notifies on Telegram. On another channel the block answers 422 unsupported_content with param telegram; an unknown key 400 invalid_request.

Show child attributes

parse_mode enum<string>

Available options: HTML, MarkdownV2

disable_notification boolean

Deliver silently, with no sound.

protect_content boolean

Stop the contact forwarding or saving the message.

metadata Metadata

Up to 20 string pairs of your own, kept with the object and returned unchanged. Keys up to 40 characters, values up to 500.

kind: list

A list message with kind given, as in a message's content, a webhook reply or a stream frame (ListMessage with kind required).

kind string required

Always list. Optional on its endpoint; required where no URL names the kind.

Default: "list"

header string

A title shown above the text, 1 to 60 characters.

Length: 1 to 60

text string required

The message's text, sent exactly as written, 1 to 4096 characters.

Length: 1 to 4096

button string required

The label of the button that opens the list, 1 to 20 characters.

Length: 1 to 20

sections ListSection[] required

1 to 10 sections, in order, with at most 10 rows in all.

Items: 1 to 10

Show child attributes

title string

The section's title, 1 to 24 characters. Required when the list has more than one section.

Length: 1 to 24

rows ListRow[] required

The section's rows, in order.

Items: 1 to 10

Show child attributes

id string required

Your ID for the row, returned in button_reply as button_id. 1 to 200 characters, unique across the list.

Length: 1 to 200

title string required

The row's title, 1 to 24 characters, returned in button_reply as label.

Length: 1 to 24

description string

A line under the title, at most 72 characters.

Length: 1 to 72

reply_to string

Pattern: ^msg_[0-9A-HJKMNP-TV-Z]{26}$

metadata Metadata

Up to 20 string pairs of your own, kept with the object and returned unchanged. Keys up to 40 characters, values up to 500.

kind: carousel

A carousel message with kind given, as in a message's content, a webhook reply or a stream frame (CarouselMessage with kind required).

kind string required

Always carousel. Optional on its endpoint; required where no URL names the kind.

Default: "carousel"

text string required

The message text shown above the cards, 1 to 1024 characters. Longer text is refused with 400 invalid_request.

Length: 1 to 1024

cards CarouselCard[] required

2 to 10 cards, in the order shown (left to right).

Items: 2 to 10

Show child attributes

header ContentHeader required

The card's image or video, a ContentHeader of type image or video only (by url or file_id); any other type is refused with 400 invalid_request at cards[i].header.type.

Show child attributes

type enum<string> required

What the header holds.

Available options: image, video, document, text

url string<uri>

Media headers only. An HTTPS URL of the media, which Flow fetches.

file_id string

A file ID, file_ and a ULID.

Pattern: ^file_[0-9A-HJKMNP-TV-Z]{26}$

text string

text headers only. The title, 1 to 60 characters (WhatsApp's header limit).

Length: 1 to 60

filename string

document headers only. The file's name, shown with the document.

Length: 0 to 255

text string

The card's text, at most 160 characters and 2 line breaks.

Length: 1 to 160

buttons Button[] required

Exactly one URL button, or 1 to 2 reply buttons; the same number and kind on every card. Labels are at most 20 characters.

Items: 1 to 2

Show child attributes

One of 2 options:

ReplyButton

A button that sends its id back as a button_reply when tapped.

id string required

Length: 1 to 64

label string required

The button's text. WhatsApp shows at most 20 characters.

Length: 1 to 20

UrlButton

A button that opens a link.

url string<uri> required

The HTTPS link to open.

label string required

The button's text.

Length: 1 to 20

metadata Metadata

Up to 20 string pairs of your own, kept with the object and returned unchanged. Keys up to 40 characters, values up to 500.

kind: template

A template message with kind given, as in a message's content, a webhook reply or a stream frame (TemplateMessage with kind required).

kind string required

Always template. Optional on its endpoint; required where no URL names the kind (and on POST /v0/messages).

Default: "template"

template_id string required

A template ID, tpl_ and a ULID.

Pattern: ^tpl_[0-9A-HJKMNP-TV-Z]{26}$

language string required

The template language to use, as Meta names it (en, en_US, hi).

params TemplateParams

Values for the template's placeholders.

Show child attributes

header TemplateHeaderParam

The value of a template's header, when it has a placeholder or media.

Show child attributes

kind enum<string> required

What the header holds.

Available options: text, image, video, document

text string

For text headers, the placeholder's value.

url string<uri>

For media headers, an HTTPS URL of the media.

file_id string

A file ID, file_ and a ULID.

Pattern: ^file_[0-9A-HJKMNP-TV-Z]{26}$

body string[]

Values for the body's {{1}}, {{2}}, ... in order.

buttons TemplateButtonParam[]

Values for buttons that take one (URL suffixes, quick-reply payloads).

Show child attributes

index integer required

The button's position in the template, from 0.

Range: 0 to 9

value string required

The URL suffix or the quick-reply payload.

cards TemplateCardParams[]

Carousel templates only. Values for each card's header, body placeholders and buttons.

Items: 0 to 10

Show child attributes

card_index integer required

The card's position in the template, from 0.

Range: 0 to 9

header TemplateHeaderParam

The card's image or video (kind image or video, by url or file_id).

Show child attributes

kind enum<string> required

What the header holds.

Available options: text, image, video, document

text string

For text headers, the placeholder's value.

url string<uri>

For media headers, an HTTPS URL of the media.

file_id string

A file ID, file_ and a ULID.

Pattern: ^file_[0-9A-HJKMNP-TV-Z]{26}$

body string[]

Values for the card body's {{1}}, {{2}}, ... in order.

buttons TemplateButtonParam[]

Values for the card's buttons that take one (URL suffixes, quick-reply payloads).

Show child attributes

index integer required

The button's position in the template, from 0.

Range: 0 to 9

value string required

The URL suffix or the quick-reply payload.

reply_to string

Pattern: ^msg_[0-9A-HJKMNP-TV-Z]{26}$

metadata Metadata

Up to 20 string pairs of your own, kept with the object and returned unchanged. Keys up to 40 characters, values up to 500.

kind: contact_card

A contact_card message with kind given, as in a message's content, a webhook reply or a stream frame (ContactCardMessage with kind required).

kind string required

Always contact_card. Optional on its endpoint; required where no URL names the kind.

Default: "contact_card"

name string required

The person's or business's name.

Length: 1 to any

phones string[]

Phone numbers, E.164 where known. Telegram needs at least one (else 422 unsupported_content, param phones).

emails string<email>[]

Email addresses.

reply_to string

Pattern: ^msg_[0-9A-HJKMNP-TV-Z]{26}$

metadata Metadata

Up to 20 string pairs of your own, kept with the object and returned unchanged. Keys up to 40 characters, values up to 500.

kind: location

A location message with kind given, as in a message's content, a webhook reply or a stream frame (LocationMessage with kind required).

kind string required

Always location. Optional on its endpoint; required where no URL names the kind.

Default: "location"

lat number required

Latitude in degrees.

Range: -90 to 90

lng number required

Longitude in degrees.

Range: -180 to 180

name string

The place's name.

address string

The place's address.

reply_to string

Pattern: ^msg_[0-9A-HJKMNP-TV-Z]{26}$

metadata Metadata

Up to 20 string pairs of your own, kept with the object and returned unchanged. Keys up to 40 characters, values up to 500.

kind: effect

An effect message with kind given, as in a message's content, a webhook reply or a stream frame (EffectMessage with kind required).

kind string required

Always effect. Optional on its endpoint; required where no URL names the kind.

Default: "effect"

text string required

The text, sent exactly as written, at most 9999 characters. Longer text is refused with 400 invalid_request.

Length: 1 to 9999

effect enum<string> required

The effect.

Available options: slam, loud, gentle, invisible_ink, echo, spotlight, balloons, confetti, love, lasers, fireworks, celebration

reply_to string

Pattern: ^msg_[0-9A-HJKMNP-TV-Z]{26}$

metadata Metadata

Up to 20 string pairs of your own, kept with the object and returned unchanged. Keys up to 40 characters, values up to 500.

kind: reaction

A reaction message with kind given, as in a message's content, a webhook reply or a stream frame (ReactionMessage with kind required).

kind string required

Always reaction. Optional on its endpoint; required where no URL names the kind.

Default: "reaction"

message_id string required

A message ID, msg_ and a ULID.

Pattern: ^msg_[0-9A-HJKMNP-TV-Z]{26}$

emoji string | null required

One emoji, or null to remove the reaction. On Telegram only its reaction emoji (listed on the endpoint); any other answers 422 unsupported_content with param emoji.

Length: 0 to 16

telegram ReactionTelegramOptions

Telegram only. On another channel the block answers 422 unsupported_content with param telegram; an unknown key 400 invalid_request.

Show child attributes

is_big boolean

Show the reaction with a large animation.

kind: typing

A typing message with kind given, as in a message's content, a webhook reply or a stream frame (TypingMessage with kind required).

kind string required

Always typing. Optional on its endpoint; required where no URL names the kind.

Default: "typing"

imessage TypingImessageOptions

iMessage only. On another channel the block answers 422 unsupported_content with param imessage; an unknown key 400 invalid_request.

Show child attributes

duration_seconds integer

How long to show the indicator, 1 to 60 seconds, unless a message goes first.

Range: 1 to 60

kind: read

A read message with kind given, as in a message's content, a webhook reply or a stream frame (ReadMessage with kind required).

kind string required

Always read. Optional on its endpoint; required where no URL names the kind.

Default: "read"

up_to string

WhatsApp only. The latest inbound message to mark read (default the latest inbound message). iMessage marks the whole conversation read, so up_to there answers 422 unsupported_content with param up_to.

Pattern: ^msg_[0-9A-HJKMNP-TV-Z]{26}$

kind: edit

A change to the text of one of your sent messages, as a kind: a piece of a webhook reply or on the stream, and the content of the message that carries an edit (PATCH /v0/messages/{message_id} over HTTP, whose rules apply). message_id names the message to change.

text string required

The new text: at most 4096 UTF-16 code units on Telegram (1024 when it replaces a media message's caption) and 9999 characters on iMessage. Longer text is refused with 400 invalid_request.

Length: 1 to 9999

telegram EditTelegramOptions

Telegram only. How Telegram reads the new text. An unknown key is refused with 400 invalid_request.

Show child attributes

parse_mode enum<string>

Available options: HTML, MarkdownV2

imessage EditImessageOptions

iMessage only. Styles for the new text. An unknown key is refused with 400 invalid_request.

Show child attributes

styles ImessageStyle[]

Styled ranges of the new text (see ImessageStyle).

Show child attributes

start integer required

Where the range starts, in UTF-16 code units from the start of text.

Range: 0 to any

length integer required

How long the range is, in UTF-16 code units.

Range: 1 to any

style enum<string> required

The style. big and small set the text's size; shake, nod, explode, ripple, bloom and jitter animate it.

Available options: bold, italic, underline, strikethrough, big, small, shake, nod, explode, ripple, bloom, jitter

kind string required

Always edit.

message_id string required

A message ID, msg_ and a ULID.

Pattern: ^msg_[0-9A-HJKMNP-TV-Z]{26}$

kind: unsend

Removes one of your sent messages from the contact's chat, as a kind: a piece of a webhook reply or on the stream, and the content of the message that carries an unsend (DELETE /v0/messages/{message_id} over HTTP, whose rules apply).

kind string required

Always unsend.

message_id string required

A message ID, msg_ and a ULID.

Pattern: ^msg_[0-9A-HJKMNP-TV-Z]{26}$

kind: button_reply

Inbound only. The contact tapped a reply button of a buttons or carousel message, or a row of a list.

kind string required

Always button_reply.

button_id string required

The id of the tapped button or list row.

label string required

The tapped button's label, or the list row's title.

message_id string

A message ID, msg_ and a ULID.

Pattern: ^msg_[0-9A-HJKMNP-TV-Z]{26}$

kind: file_blocked

Inbound only. The contact sent a file that Flow did not keep: it failed the malware scan, its real type is one Flow does not pass on (programs, web pages), it could not be scanned, or it is larger than the channel lets Flow download. The file is not stored and has no url; what is known about it is here. Images, audio and video are not scanned; documents (PDF, Office, archives) are, and one Flow could not scan arrives with reason scan_failed.

kind string required

Always file_blocked.

reason enum<string> required

Why the file was not kept: malware (the scan found something), type_not_allowed, scan_failed (the scanner could not check it; ask the contact to send it again), or too_large.

Available options: malware, type_not_allowed, scan_failed, too_large

media_type enum<string>

What kind of file the channel said it was.

Available options: image, video, document, audio

filename string

The file's name, if it had one.

mime_type string

The real type, read from the file's first bytes, when Flow read them.

size_bytes integer

The file's size, when known.

caption string

Text the contact sent with the file.

network enum<string> read-only

iMessage channel only: the network that carried the message. imessage, or sms or rcs when the line has the SMS/RCS add-on (Sender.imessage.fallback) and the contact could not get iMessage. The network is chosen for each message when it is sent, never by your app. Set on inbound messages, and on your messages once the channel reports it (in message.sent, message.delivered or message.failed, as data.message.network); absent before that and on other channels. A message that went by sms or rcs showed no imessage.styles, no imessage.subject and no effect, and edits and unsends of it answer 422 unsupported_content with channel_code not_on_sms.

Available options: imessage, sms, rcs

error ErrorBody

The details of an error.

Show child attributes

type enum<string> required

What went wrong. A closed list: new types arrive only with a new API version. Each type has a page at https://api.flow.engineer/docs/errors/<type>, given in the error's doc_url; the error's hint says what to change for the case.

invalid_request (400, or 413 for a request body over the size limit): the request is malformed or a parameter is invalid. Fix the parameter named in param; the hint says what it must look like. Every endpoint answers it for a Flow-Version header that is not a version this API serves.
authentication (401): the API key is missing, malformed, unknown, revoked or expired. An Authorization: Bearer header with nothing after it usually means the environment variable holding the key was empty when the header was built (for an MCP client, when the server was added): the hint says so. Send Authorization: Bearer fk_test_... or fk_live_... with a current key; with no key at all, get a test key with POST /v0/sandbox/keys. A sandbox key past its expires_at has channel_code sandbox_key_expired: sign in to claim the app, or get a new key.
permission (403): the key may not do this, for example a test key using a live sender, a sandbox contact who joined another app, a new conversation from an iMessage line that may only reply, or a send past the app's sandbox allowance (channel_code sandbox_allowance_used, sandbox_contact_limit or sandbox_channel_not_included). Use the key of the right mode, have the contact send your join message, wait for the contact to message the line first, or sign in through the device flow to lift the allowance. On SMS: contact_opted_out (the contact texted STOP; nothing more goes to them until they text START), consent_required (a start to someone who never texted your numbers: record their consent with consent on the start). In a HIPAA account: hipaa_channel_not_covered (the channel has no business associate agreement; use SMS). Simulated conversations: simulated_contact (a real sender was pointed at a simulated contact; reply in the contact's simulated conversation), not_simulated (a simulated sender or test endpoint was pointed at a real contact), test_mode_only, simulated_conversation_limit. In message.failed: sandbox_contact_left (the contact joined another app on the sandbox sender while the message was queued; have them send your join message again).
not_found (404): no such object for this app and mode. Check the ID's prefix and that it was made with a key of the same mode (test and live data are separate).
idempotency_conflict (409): the idempotency key was used for a different request (channel_code body_mismatch: use a new key), or that request is still running (in_progress: wait retry_after seconds and repeat it with the same key), or it already created a secret that is shown only once (secret_not_kept: creating a webhook endpoint, rotating its secret, connecting a WhatsApp number; a secret that was lost must be rotated again, and a WhatsApp number connected again to see its verify token).
outside_window (409, or in message.failed): the channel will not deliver outside its conversation window. On WhatsApp the 24-hour window is closed: send a template (POST /v0/conversations/{conversation_id}/template, or POST /v0/messages with kind template to start), or wait for the contact to write. On iMessage the contact has not messaged the line (or opted in) yet, or not recently, so the failure arrives as a message.failed event: wait for the contact to write, then reply in that conversation. Typing and read receipts answer 409 outside_window directly when the channel's window for them is closed (iMessage typing works only within 5 minutes of the contact's last message; WhatsApp read receipts go at any time); ignore it and send your reply. On SMS, channel_code quiet_hours: the contact has not texted in the last hour and it is inside the sender's quiet hours in their time zone; retry after retry_after seconds, or wait for them to text. In message.failed: window_closed (WhatsApp's 24-hour window closed while the message was queued; send a template) and queued_too_long (the message waited in the queue longer than its sender allows, for example while the sender was paused; send it again if it still applies).
unsupported_content (422): the conversation's channel does not take this kind, field, block or value, and nothing was sent; Flow never converts a message. param names what was refused: kind (the endpoint's kind is not on this channel, such as a carousel on Telegram), a field or block (reply_to on SMS, telegram on WhatsApp, telegram.is_big), or the field whose value is not taken (emoji outside Telegram's reaction emoji, buttons for more than 3 WhatsApp buttons). channel is the conversation's channel and hint says what to send instead over plain HTTP; each endpoint's page lists its channels. In an iMessage group conversation, a reaction, typing or a read receipt answers it with param kind and channel_code group_unsupported: leave it out. Media to an SMS number without MMS answers it with param media and channel_code no_mms. An edit or unsend of an iMessage message that went by SMS or RCS (its network) answers it with channel_code not_on_sms: send a new message instead. An edit or unsend past the channel's time limit answers it with channel_code edit_window_closed or unsend_window_closed (iMessage: edits within 15 minutes of sending, unsends within 2 minutes; Telegram: unsends within 48 hours), and an iMessage edit of the message that started the conversation with first_message_not_editable; message states the limit and how long ago the message was sent. Send a new message instead. POST /v0/files answers it for a type Flow does not take (programs, web pages, unknown types). A send by file_id of a document a contact sent before Flow malware-scanned documents answers it too: Flow sends only documents it scanned.
new_contact_limit (429): the sender has used its budget for starting conversations. Wait retry_after seconds; replies into existing conversations still go.
sender_throttled (429): abuse signals tripped (the same text to many new contacts, many starts with no reply, blocks), so the sender may not start conversations until retry_after; replies into existing conversations still go. Personalise first messages and start only conversations people expect.
file_blocked (422): the file failed the malware scan and was not stored. Send a different file. (When the scan cannot run at all, the upload answers a retryable 500 api_error with Retry-After instead.)
rate_limited (429): either too many requests for this key (the per-key request limit, reported in the RateLimit-* headers) or sends faster than the sender's sending rate (pacing). Wait Retry-After (retry_after) seconds and retry with the same Idempotency-Key.
channel_error (502, or in message.failed): the channel refused or failed the message, or timed out; channel_code carries its own code. Read message, change what the channel objected to, and send again. From typing and read receipts, which call the channel at once, it is safe to ignore. SMS codes are Flow's, the same whichever carrier network carries the message: carrier_filtered (a carrier's spam filter blocked it: make it read like a person's message, no shortened links), unreachable, invalid_number, landline, registration_required (the number's 10DLC or toll-free registration is not approved yet), carrier_error, and provider_not_configured (the SMS sender is not fully set up on Flow's side, so nothing was sent; contact the Flow team). Flow's own codes on every channel: channel_timeout_unknown_outcome (in message.failed: the channel did not answer after the message was sent, and the resends its policy allows did not settle it, so the message may have arrived or not; check with the contact before sending it again) and unknown_outcome (from typing and read receipts: the call timed out after it was sent).
not_implemented (501): this endpoint or channel is not live yet during the beta. Use a channel that is live (Telegram, iMessage), or check the changelog.
api_error (500, 503): something went wrong on Flow's side. Retry with the same idempotency key after retry_after seconds, and quote request_id if it persists.

Available options: invalid_request, authentication, permission, not_found, idempotency_conflict, outside_window, unsupported_content, new_contact_limit, sender_throttled, file_blocked, rate_limited, channel_error, not_implemented, api_error

message string required

A sentence for a developer saying what went wrong. Do not parse it; switch on type.

hint string required

One sentence saying what to change to make the request succeed, specific to this case, for example "Send a template instead: POST /v0/conversations/{conversation_id}/template." For unsupported_content it says what to send instead over plain HTTP. Written for developers and coding agents alike. Do not parse it; it may be reworded at any time.

doc_url string<uri> required

The documentation page for this error's type, https://api.flow.engineer/docs/errors/<type>. It says what the error means, why it happens and how to fix it, with code.

param string

The request parameter the error is about, as a dotted path (kind, telegram.is_big, buttons, cards[1].header.type, limit).

retry_after integer

Seconds to wait before retrying, for errors that clear by themselves.

Range: 0 to any

channel enum<string>

The conversation's channel, on errors about what it takes (unsupported_content) and its windows (outside_window).

Available options: telegram, whatsapp, imessage, sms

conversation string

A conversation ID, conv_ and a ULID.

Pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$

sender string

A sender ID, snd_ and a ULID.

Pattern: ^snd_[0-9A-HJKMNP-TV-Z]{26}$

channel_code string

For channel_error, the channel's own error code, as given by the channel. For some other errors, Flow's own code naming the case, for example sandbox_allowance_used (permission: the sandbox allowance is used up), sandbox_contact_limit (permission: the allowance has no room for another contact), sandbox_channel_not_included (permission: the allowance does not cover this sandbox channel), sign_in_required (permission: an app made without an account cannot do this) or sandbox_key_expired (authentication: a key from POST /v0/sandbox/keys passed its expires_at; permission, for a send that carries no key, such as a reply in a webhook answer, from such an app). For idempotency_conflict, always one of body_mismatch (the key was used for a different request), in_progress (the first request is still running; retry_after says when to repeat it) or secret_not_kept (its answer carried a secret shown only once). SMS: contact_opted_out and consent_required (permission), quiet_hours (outside_window, with retry_after), and carrier_filtered, unreachable, invalid_number, landline, registration_required, carrier_error and provider_not_configured (channel_error). HIPAA accounts: hipaa_channel_not_covered (permission). Connecting your own WhatsApp number (POST /v0/senders): whatsapp_token_malformed, whatsapp_token_rejected, whatsapp_app_secret_malformed and whatsapp_number_not_in_account (invalid_request), and whatsapp_number_taken, whatsapp_account_taken and whatsapp_number_managed (permission). Simulated conversations (permission): test_mode_only, not_simulated, simulated_contact and simulated_conversation_limit. For a message that failed after it was queued (message.failed): sandbox_contact_left (permission), window_closed and queued_too_long (outside_window), and channel_timeout_unknown_outcome (channel_error: the channel never confirmed the send, so it may or may not have arrived). iMessage (unsupported_content): group_unsupported (a reaction, typing or a read receipt in a group conversation; param kind) and not_on_sms (an edit or unsend of a message that went by SMS or RCS; param kind). SMS (unsupported_content): no_mms (media to a number without MMS; param media). Edits and unsends (unsupported_content): edit_window_closed and unsend_window_closed (the message is older than the channel allows for the change) and first_message_not_editable (iMessage: the message that started the conversation). From typing and read receipts, unknown_outcome (channel_error: the call timed out after it was sent).

request_id string

Flow's ID for this request. Quote it when asking for help.

channel_message_id string

The channel's own ID for the message, once the channel accepted it.

sms SmsSegments read-only

SMS text messages only: how the text travels as SMS. Carriers bill and deliver SMS in segments: 160 GSM-7 characters fit one segment (153 each when split), but a single character outside GSM-7 (an emoji, curly quotes, most non-Latin letters) makes the whole text UCS-2, 70 characters in one segment (67 each when split). An SMS send may use at most 10 segments: 1530 GSM-7 characters (fewer when it uses GSM-7's two-unit characters such as { or €), or 670 when it holds an emoji or other character outside GSM-7; a longer text is refused with 400 invalid_request. Absent on MMS and on other channels.

Show child attributes

segments integer required

How many SMS segments the text takes.

Range: 1 to any

encoding enum<string> required

gsm7 or ucs2.

Available options: gsm7, ucs2

reply_to string read-only

The Flow ID of the message this one replies to. For a sent message, the message the send named in reply_to. For a received message, the message it replies to inline (a Telegram or WhatsApp reply; on iMessage, the thread's root message). Absent when the message is not a reply or the quoted message is not known to Flow.

Pattern: ^msg_[0-9A-HJKMNP-TV-Z]{26}$

livemode boolean required

Whether the message belongs to live mode.

metadata Metadata

Up to 20 string pairs of your own, kept with the object and returned unchanged. Keys up to 40 characters, values up to 500.

created_at string<date-time> required

When Flow received (inbound) or accepted (outbound) the message.

updated_at string<date-time>

When the status last changed.

400 application/json

The request is malformed or a parameter is invalid (invalid_request). error.param names the parameter. Every endpoint answers this for a Flow-Version header that is not a date this API serves (param Flow-Version), and every POST that takes an Idempotency-Key for a key over 255 characters (param Idempotency-Key).

error ErrorBody required

The details of an error.

Show child attributes

type enum<string> required

invalid_request (400, or 413 for a request body over the size limit): the request is malformed or a parameter is invalid. Fix the parameter named in param; the hint says what it must look like. Every endpoint answers it for a Flow-Version header that is not a version this API serves.
authentication (401): the API key is missing, malformed, unknown, revoked or expired. An Authorization: Bearer header with nothing after it usually means the environment variable holding the key was empty when the header was built (for an MCP client, when the server was added): the hint says so. Send Authorization: Bearer fk_test_... or fk_live_... with a current key; with no key at all, get a test key with POST /v0/sandbox/keys. A sandbox key past its expires_at has channel_code sandbox_key_expired: sign in to claim the app, or get a new key.
permission (403): the key may not do this, for example a test key using a live sender, a sandbox contact who joined another app, a new conversation from an iMessage line that may only reply, or a send past the app's sandbox allowance (channel_code sandbox_allowance_used, sandbox_contact_limit or sandbox_channel_not_included). Use the key of the right mode, have the contact send your join message, wait for the contact to message the line first, or sign in through the device flow to lift the allowance. On SMS: contact_opted_out (the contact texted STOP; nothing more goes to them until they text START), consent_required (a start to someone who never texted your numbers: record their consent with consent on the start). In a HIPAA account: hipaa_channel_not_covered (the channel has no business associate agreement; use SMS). Simulated conversations: simulated_contact (a real sender was pointed at a simulated contact; reply in the contact's simulated conversation), not_simulated (a simulated sender or test endpoint was pointed at a real contact), test_mode_only, simulated_conversation_limit. In message.failed: sandbox_contact_left (the contact joined another app on the sandbox sender while the message was queued; have them send your join message again).
not_found (404): no such object for this app and mode. Check the ID's prefix and that it was made with a key of the same mode (test and live data are separate).
idempotency_conflict (409): the idempotency key was used for a different request (channel_code body_mismatch: use a new key), or that request is still running (in_progress: wait retry_after seconds and repeat it with the same key), or it already created a secret that is shown only once (secret_not_kept: creating a webhook endpoint, rotating its secret, connecting a WhatsApp number; a secret that was lost must be rotated again, and a WhatsApp number connected again to see its verify token).
outside_window (409, or in message.failed): the channel will not deliver outside its conversation window. On WhatsApp the 24-hour window is closed: send a template (POST /v0/conversations/{conversation_id}/template, or POST /v0/messages with kind template to start), or wait for the contact to write. On iMessage the contact has not messaged the line (or opted in) yet, or not recently, so the failure arrives as a message.failed event: wait for the contact to write, then reply in that conversation. Typing and read receipts answer 409 outside_window directly when the channel's window for them is closed (iMessage typing works only within 5 minutes of the contact's last message; WhatsApp read receipts go at any time); ignore it and send your reply. On SMS, channel_code quiet_hours: the contact has not texted in the last hour and it is inside the sender's quiet hours in their time zone; retry after retry_after seconds, or wait for them to text. In message.failed: window_closed (WhatsApp's 24-hour window closed while the message was queued; send a template) and queued_too_long (the message waited in the queue longer than its sender allows, for example while the sender was paused; send it again if it still applies).
unsupported_content (422): the conversation's channel does not take this kind, field, block or value, and nothing was sent; Flow never converts a message. param names what was refused: kind (the endpoint's kind is not on this channel, such as a carousel on Telegram), a field or block (reply_to on SMS, telegram on WhatsApp, telegram.is_big), or the field whose value is not taken (emoji outside Telegram's reaction emoji, buttons for more than 3 WhatsApp buttons). channel is the conversation's channel and hint says what to send instead over plain HTTP; each endpoint's page lists its channels. In an iMessage group conversation, a reaction, typing or a read receipt answers it with param kind and channel_code group_unsupported: leave it out. Media to an SMS number without MMS answers it with param media and channel_code no_mms. An edit or unsend of an iMessage message that went by SMS or RCS (its network) answers it with channel_code not_on_sms: send a new message instead. An edit or unsend past the channel's time limit answers it with channel_code edit_window_closed or unsend_window_closed (iMessage: edits within 15 minutes of sending, unsends within 2 minutes; Telegram: unsends within 48 hours), and an iMessage edit of the message that started the conversation with first_message_not_editable; message states the limit and how long ago the message was sent. Send a new message instead. POST /v0/files answers it for a type Flow does not take (programs, web pages, unknown types). A send by file_id of a document a contact sent before Flow malware-scanned documents answers it too: Flow sends only documents it scanned.
new_contact_limit (429): the sender has used its budget for starting conversations. Wait retry_after seconds; replies into existing conversations still go.
sender_throttled (429): abuse signals tripped (the same text to many new contacts, many starts with no reply, blocks), so the sender may not start conversations until retry_after; replies into existing conversations still go. Personalise first messages and start only conversations people expect.
file_blocked (422): the file failed the malware scan and was not stored. Send a different file. (When the scan cannot run at all, the upload answers a retryable 500 api_error with Retry-After instead.)
rate_limited (429): either too many requests for this key (the per-key request limit, reported in the RateLimit-* headers) or sends faster than the sender's sending rate (pacing). Wait Retry-After (retry_after) seconds and retry with the same Idempotency-Key.
channel_error (502, or in message.failed): the channel refused or failed the message, or timed out; channel_code carries its own code. Read message, change what the channel objected to, and send again. From typing and read receipts, which call the channel at once, it is safe to ignore. SMS codes are Flow's, the same whichever carrier network carries the message: carrier_filtered (a carrier's spam filter blocked it: make it read like a person's message, no shortened links), unreachable, invalid_number, landline, registration_required (the number's 10DLC or toll-free registration is not approved yet), carrier_error, and provider_not_configured (the SMS sender is not fully set up on Flow's side, so nothing was sent; contact the Flow team). Flow's own codes on every channel: channel_timeout_unknown_outcome (in message.failed: the channel did not answer after the message was sent, and the resends its policy allows did not settle it, so the message may have arrived or not; check with the contact before sending it again) and unknown_outcome (from typing and read receipts: the call timed out after it was sent).
not_implemented (501): this endpoint or channel is not live yet during the beta. Use a channel that is live (Telegram, iMessage), or check the changelog.
api_error (500, 503): something went wrong on Flow's side. Retry with the same idempotency key after retry_after seconds, and quote request_id if it persists.

message string required

A sentence for a developer saying what went wrong. Do not parse it; switch on type.

hint string required

doc_url string<uri> required

The documentation page for this error's type, https://api.flow.engineer/docs/errors/<type>. It says what the error means, why it happens and how to fix it, with code.

param string

The request parameter the error is about, as a dotted path (kind, telegram.is_big, buttons, cards[1].header.type, limit).

retry_after integer

Seconds to wait before retrying, for errors that clear by themselves.

Range: 0 to any

channel enum<string>

The conversation's channel, on errors about what it takes (unsupported_content) and its windows (outside_window).

Available options: telegram, whatsapp, imessage, sms

conversation string

A conversation ID, conv_ and a ULID.

Pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$

sender string

A sender ID, snd_ and a ULID.

Pattern: ^snd_[0-9A-HJKMNP-TV-Z]{26}$

channel_code string

request_id string

Flow's ID for this request. Quote it when asking for help.

401 application/json

The API key is missing, malformed, unknown, revoked or expired (authentication).

error ErrorBody required

The details of an error.

Show child attributes

type enum<string> required

invalid_request (400, or 413 for a request body over the size limit): the request is malformed or a parameter is invalid. Fix the parameter named in param; the hint says what it must look like. Every endpoint answers it for a Flow-Version header that is not a version this API serves.
authentication (401): the API key is missing, malformed, unknown, revoked or expired. An Authorization: Bearer header with nothing after it usually means the environment variable holding the key was empty when the header was built (for an MCP client, when the server was added): the hint says so. Send Authorization: Bearer fk_test_... or fk_live_... with a current key; with no key at all, get a test key with POST /v0/sandbox/keys. A sandbox key past its expires_at has channel_code sandbox_key_expired: sign in to claim the app, or get a new key.
permission (403): the key may not do this, for example a test key using a live sender, a sandbox contact who joined another app, a new conversation from an iMessage line that may only reply, or a send past the app's sandbox allowance (channel_code sandbox_allowance_used, sandbox_contact_limit or sandbox_channel_not_included). Use the key of the right mode, have the contact send your join message, wait for the contact to message the line first, or sign in through the device flow to lift the allowance. On SMS: contact_opted_out (the contact texted STOP; nothing more goes to them until they text START), consent_required (a start to someone who never texted your numbers: record their consent with consent on the start). In a HIPAA account: hipaa_channel_not_covered (the channel has no business associate agreement; use SMS). Simulated conversations: simulated_contact (a real sender was pointed at a simulated contact; reply in the contact's simulated conversation), not_simulated (a simulated sender or test endpoint was pointed at a real contact), test_mode_only, simulated_conversation_limit. In message.failed: sandbox_contact_left (the contact joined another app on the sandbox sender while the message was queued; have them send your join message again).
not_found (404): no such object for this app and mode. Check the ID's prefix and that it was made with a key of the same mode (test and live data are separate).
idempotency_conflict (409): the idempotency key was used for a different request (channel_code body_mismatch: use a new key), or that request is still running (in_progress: wait retry_after seconds and repeat it with the same key), or it already created a secret that is shown only once (secret_not_kept: creating a webhook endpoint, rotating its secret, connecting a WhatsApp number; a secret that was lost must be rotated again, and a WhatsApp number connected again to see its verify token).
outside_window (409, or in message.failed): the channel will not deliver outside its conversation window. On WhatsApp the 24-hour window is closed: send a template (POST /v0/conversations/{conversation_id}/template, or POST /v0/messages with kind template to start), or wait for the contact to write. On iMessage the contact has not messaged the line (or opted in) yet, or not recently, so the failure arrives as a message.failed event: wait for the contact to write, then reply in that conversation. Typing and read receipts answer 409 outside_window directly when the channel's window for them is closed (iMessage typing works only within 5 minutes of the contact's last message; WhatsApp read receipts go at any time); ignore it and send your reply. On SMS, channel_code quiet_hours: the contact has not texted in the last hour and it is inside the sender's quiet hours in their time zone; retry after retry_after seconds, or wait for them to text. In message.failed: window_closed (WhatsApp's 24-hour window closed while the message was queued; send a template) and queued_too_long (the message waited in the queue longer than its sender allows, for example while the sender was paused; send it again if it still applies).
unsupported_content (422): the conversation's channel does not take this kind, field, block or value, and nothing was sent; Flow never converts a message. param names what was refused: kind (the endpoint's kind is not on this channel, such as a carousel on Telegram), a field or block (reply_to on SMS, telegram on WhatsApp, telegram.is_big), or the field whose value is not taken (emoji outside Telegram's reaction emoji, buttons for more than 3 WhatsApp buttons). channel is the conversation's channel and hint says what to send instead over plain HTTP; each endpoint's page lists its channels. In an iMessage group conversation, a reaction, typing or a read receipt answers it with param kind and channel_code group_unsupported: leave it out. Media to an SMS number without MMS answers it with param media and channel_code no_mms. An edit or unsend of an iMessage message that went by SMS or RCS (its network) answers it with channel_code not_on_sms: send a new message instead. An edit or unsend past the channel's time limit answers it with channel_code edit_window_closed or unsend_window_closed (iMessage: edits within 15 minutes of sending, unsends within 2 minutes; Telegram: unsends within 48 hours), and an iMessage edit of the message that started the conversation with first_message_not_editable; message states the limit and how long ago the message was sent. Send a new message instead. POST /v0/files answers it for a type Flow does not take (programs, web pages, unknown types). A send by file_id of a document a contact sent before Flow malware-scanned documents answers it too: Flow sends only documents it scanned.
new_contact_limit (429): the sender has used its budget for starting conversations. Wait retry_after seconds; replies into existing conversations still go.
sender_throttled (429): abuse signals tripped (the same text to many new contacts, many starts with no reply, blocks), so the sender may not start conversations until retry_after; replies into existing conversations still go. Personalise first messages and start only conversations people expect.
file_blocked (422): the file failed the malware scan and was not stored. Send a different file. (When the scan cannot run at all, the upload answers a retryable 500 api_error with Retry-After instead.)
rate_limited (429): either too many requests for this key (the per-key request limit, reported in the RateLimit-* headers) or sends faster than the sender's sending rate (pacing). Wait Retry-After (retry_after) seconds and retry with the same Idempotency-Key.
channel_error (502, or in message.failed): the channel refused or failed the message, or timed out; channel_code carries its own code. Read message, change what the channel objected to, and send again. From typing and read receipts, which call the channel at once, it is safe to ignore. SMS codes are Flow's, the same whichever carrier network carries the message: carrier_filtered (a carrier's spam filter blocked it: make it read like a person's message, no shortened links), unreachable, invalid_number, landline, registration_required (the number's 10DLC or toll-free registration is not approved yet), carrier_error, and provider_not_configured (the SMS sender is not fully set up on Flow's side, so nothing was sent; contact the Flow team). Flow's own codes on every channel: channel_timeout_unknown_outcome (in message.failed: the channel did not answer after the message was sent, and the resends its policy allows did not settle it, so the message may have arrived or not; check with the contact before sending it again) and unknown_outcome (from typing and read receipts: the call timed out after it was sent).
not_implemented (501): this endpoint or channel is not live yet during the beta. Use a channel that is live (Telegram, iMessage), or check the changelog.
api_error (500, 503): something went wrong on Flow's side. Retry with the same idempotency key after retry_after seconds, and quote request_id if it persists.

message string required

A sentence for a developer saying what went wrong. Do not parse it; switch on type.

hint string required

doc_url string<uri> required

The documentation page for this error's type, https://api.flow.engineer/docs/errors/<type>. It says what the error means, why it happens and how to fix it, with code.

param string

The request parameter the error is about, as a dotted path (kind, telegram.is_big, buttons, cards[1].header.type, limit).

retry_after integer

Seconds to wait before retrying, for errors that clear by themselves.

Range: 0 to any

channel enum<string>

The conversation's channel, on errors about what it takes (unsupported_content) and its windows (outside_window).

Available options: telegram, whatsapp, imessage, sms

conversation string

A conversation ID, conv_ and a ULID.

Pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$

sender string

A sender ID, snd_ and a ULID.

Pattern: ^snd_[0-9A-HJKMNP-TV-Z]{26}$

channel_code string

request_id string

Flow's ID for this request. Quote it when asking for help.

403 application/json

The key may not do this, for example a test key using a live sender (permission).

error ErrorBody required

The details of an error.

Show child attributes

type enum<string> required

invalid_request (400, or 413 for a request body over the size limit): the request is malformed or a parameter is invalid. Fix the parameter named in param; the hint says what it must look like. Every endpoint answers it for a Flow-Version header that is not a version this API serves.
authentication (401): the API key is missing, malformed, unknown, revoked or expired. An Authorization: Bearer header with nothing after it usually means the environment variable holding the key was empty when the header was built (for an MCP client, when the server was added): the hint says so. Send Authorization: Bearer fk_test_... or fk_live_... with a current key; with no key at all, get a test key with POST /v0/sandbox/keys. A sandbox key past its expires_at has channel_code sandbox_key_expired: sign in to claim the app, or get a new key.
permission (403): the key may not do this, for example a test key using a live sender, a sandbox contact who joined another app, a new conversation from an iMessage line that may only reply, or a send past the app's sandbox allowance (channel_code sandbox_allowance_used, sandbox_contact_limit or sandbox_channel_not_included). Use the key of the right mode, have the contact send your join message, wait for the contact to message the line first, or sign in through the device flow to lift the allowance. On SMS: contact_opted_out (the contact texted STOP; nothing more goes to them until they text START), consent_required (a start to someone who never texted your numbers: record their consent with consent on the start). In a HIPAA account: hipaa_channel_not_covered (the channel has no business associate agreement; use SMS). Simulated conversations: simulated_contact (a real sender was pointed at a simulated contact; reply in the contact's simulated conversation), not_simulated (a simulated sender or test endpoint was pointed at a real contact), test_mode_only, simulated_conversation_limit. In message.failed: sandbox_contact_left (the contact joined another app on the sandbox sender while the message was queued; have them send your join message again).
not_found (404): no such object for this app and mode. Check the ID's prefix and that it was made with a key of the same mode (test and live data are separate).
idempotency_conflict (409): the idempotency key was used for a different request (channel_code body_mismatch: use a new key), or that request is still running (in_progress: wait retry_after seconds and repeat it with the same key), or it already created a secret that is shown only once (secret_not_kept: creating a webhook endpoint, rotating its secret, connecting a WhatsApp number; a secret that was lost must be rotated again, and a WhatsApp number connected again to see its verify token).
outside_window (409, or in message.failed): the channel will not deliver outside its conversation window. On WhatsApp the 24-hour window is closed: send a template (POST /v0/conversations/{conversation_id}/template, or POST /v0/messages with kind template to start), or wait for the contact to write. On iMessage the contact has not messaged the line (or opted in) yet, or not recently, so the failure arrives as a message.failed event: wait for the contact to write, then reply in that conversation. Typing and read receipts answer 409 outside_window directly when the channel's window for them is closed (iMessage typing works only within 5 minutes of the contact's last message; WhatsApp read receipts go at any time); ignore it and send your reply. On SMS, channel_code quiet_hours: the contact has not texted in the last hour and it is inside the sender's quiet hours in their time zone; retry after retry_after seconds, or wait for them to text. In message.failed: window_closed (WhatsApp's 24-hour window closed while the message was queued; send a template) and queued_too_long (the message waited in the queue longer than its sender allows, for example while the sender was paused; send it again if it still applies).
unsupported_content (422): the conversation's channel does not take this kind, field, block or value, and nothing was sent; Flow never converts a message. param names what was refused: kind (the endpoint's kind is not on this channel, such as a carousel on Telegram), a field or block (reply_to on SMS, telegram on WhatsApp, telegram.is_big), or the field whose value is not taken (emoji outside Telegram's reaction emoji, buttons for more than 3 WhatsApp buttons). channel is the conversation's channel and hint says what to send instead over plain HTTP; each endpoint's page lists its channels. In an iMessage group conversation, a reaction, typing or a read receipt answers it with param kind and channel_code group_unsupported: leave it out. Media to an SMS number without MMS answers it with param media and channel_code no_mms. An edit or unsend of an iMessage message that went by SMS or RCS (its network) answers it with channel_code not_on_sms: send a new message instead. An edit or unsend past the channel's time limit answers it with channel_code edit_window_closed or unsend_window_closed (iMessage: edits within 15 minutes of sending, unsends within 2 minutes; Telegram: unsends within 48 hours), and an iMessage edit of the message that started the conversation with first_message_not_editable; message states the limit and how long ago the message was sent. Send a new message instead. POST /v0/files answers it for a type Flow does not take (programs, web pages, unknown types). A send by file_id of a document a contact sent before Flow malware-scanned documents answers it too: Flow sends only documents it scanned.
new_contact_limit (429): the sender has used its budget for starting conversations. Wait retry_after seconds; replies into existing conversations still go.
sender_throttled (429): abuse signals tripped (the same text to many new contacts, many starts with no reply, blocks), so the sender may not start conversations until retry_after; replies into existing conversations still go. Personalise first messages and start only conversations people expect.
file_blocked (422): the file failed the malware scan and was not stored. Send a different file. (When the scan cannot run at all, the upload answers a retryable 500 api_error with Retry-After instead.)
rate_limited (429): either too many requests for this key (the per-key request limit, reported in the RateLimit-* headers) or sends faster than the sender's sending rate (pacing). Wait Retry-After (retry_after) seconds and retry with the same Idempotency-Key.
channel_error (502, or in message.failed): the channel refused or failed the message, or timed out; channel_code carries its own code. Read message, change what the channel objected to, and send again. From typing and read receipts, which call the channel at once, it is safe to ignore. SMS codes are Flow's, the same whichever carrier network carries the message: carrier_filtered (a carrier's spam filter blocked it: make it read like a person's message, no shortened links), unreachable, invalid_number, landline, registration_required (the number's 10DLC or toll-free registration is not approved yet), carrier_error, and provider_not_configured (the SMS sender is not fully set up on Flow's side, so nothing was sent; contact the Flow team). Flow's own codes on every channel: channel_timeout_unknown_outcome (in message.failed: the channel did not answer after the message was sent, and the resends its policy allows did not settle it, so the message may have arrived or not; check with the contact before sending it again) and unknown_outcome (from typing and read receipts: the call timed out after it was sent).
not_implemented (501): this endpoint or channel is not live yet during the beta. Use a channel that is live (Telegram, iMessage), or check the changelog.
api_error (500, 503): something went wrong on Flow's side. Retry with the same idempotency key after retry_after seconds, and quote request_id if it persists.

message string required

A sentence for a developer saying what went wrong. Do not parse it; switch on type.

hint string required

doc_url string<uri> required

The documentation page for this error's type, https://api.flow.engineer/docs/errors/<type>. It says what the error means, why it happens and how to fix it, with code.

param string

The request parameter the error is about, as a dotted path (kind, telegram.is_big, buttons, cards[1].header.type, limit).

retry_after integer

Seconds to wait before retrying, for errors that clear by themselves.

Range: 0 to any

channel enum<string>

The conversation's channel, on errors about what it takes (unsupported_content) and its windows (outside_window).

Available options: telegram, whatsapp, imessage, sms

conversation string

A conversation ID, conv_ and a ULID.

Pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$

sender string

A sender ID, snd_ and a ULID.

Pattern: ^snd_[0-9A-HJKMNP-TV-Z]{26}$

channel_code string

request_id string

Flow's ID for this request. Quote it when asking for help.

404 application/json

No such object for this app and mode (not_found).

error ErrorBody required

The details of an error.

Show child attributes

type enum<string> required

invalid_request (400, or 413 for a request body over the size limit): the request is malformed or a parameter is invalid. Fix the parameter named in param; the hint says what it must look like. Every endpoint answers it for a Flow-Version header that is not a version this API serves.
authentication (401): the API key is missing, malformed, unknown, revoked or expired. An Authorization: Bearer header with nothing after it usually means the environment variable holding the key was empty when the header was built (for an MCP client, when the server was added): the hint says so. Send Authorization: Bearer fk_test_... or fk_live_... with a current key; with no key at all, get a test key with POST /v0/sandbox/keys. A sandbox key past its expires_at has channel_code sandbox_key_expired: sign in to claim the app, or get a new key.
permission (403): the key may not do this, for example a test key using a live sender, a sandbox contact who joined another app, a new conversation from an iMessage line that may only reply, or a send past the app's sandbox allowance (channel_code sandbox_allowance_used, sandbox_contact_limit or sandbox_channel_not_included). Use the key of the right mode, have the contact send your join message, wait for the contact to message the line first, or sign in through the device flow to lift the allowance. On SMS: contact_opted_out (the contact texted STOP; nothing more goes to them until they text START), consent_required (a start to someone who never texted your numbers: record their consent with consent on the start). In a HIPAA account: hipaa_channel_not_covered (the channel has no business associate agreement; use SMS). Simulated conversations: simulated_contact (a real sender was pointed at a simulated contact; reply in the contact's simulated conversation), not_simulated (a simulated sender or test endpoint was pointed at a real contact), test_mode_only, simulated_conversation_limit. In message.failed: sandbox_contact_left (the contact joined another app on the sandbox sender while the message was queued; have them send your join message again).
not_found (404): no such object for this app and mode. Check the ID's prefix and that it was made with a key of the same mode (test and live data are separate).
idempotency_conflict (409): the idempotency key was used for a different request (channel_code body_mismatch: use a new key), or that request is still running (in_progress: wait retry_after seconds and repeat it with the same key), or it already created a secret that is shown only once (secret_not_kept: creating a webhook endpoint, rotating its secret, connecting a WhatsApp number; a secret that was lost must be rotated again, and a WhatsApp number connected again to see its verify token).
outside_window (409, or in message.failed): the channel will not deliver outside its conversation window. On WhatsApp the 24-hour window is closed: send a template (POST /v0/conversations/{conversation_id}/template, or POST /v0/messages with kind template to start), or wait for the contact to write. On iMessage the contact has not messaged the line (or opted in) yet, or not recently, so the failure arrives as a message.failed event: wait for the contact to write, then reply in that conversation. Typing and read receipts answer 409 outside_window directly when the channel's window for them is closed (iMessage typing works only within 5 minutes of the contact's last message; WhatsApp read receipts go at any time); ignore it and send your reply. On SMS, channel_code quiet_hours: the contact has not texted in the last hour and it is inside the sender's quiet hours in their time zone; retry after retry_after seconds, or wait for them to text. In message.failed: window_closed (WhatsApp's 24-hour window closed while the message was queued; send a template) and queued_too_long (the message waited in the queue longer than its sender allows, for example while the sender was paused; send it again if it still applies).
unsupported_content (422): the conversation's channel does not take this kind, field, block or value, and nothing was sent; Flow never converts a message. param names what was refused: kind (the endpoint's kind is not on this channel, such as a carousel on Telegram), a field or block (reply_to on SMS, telegram on WhatsApp, telegram.is_big), or the field whose value is not taken (emoji outside Telegram's reaction emoji, buttons for more than 3 WhatsApp buttons). channel is the conversation's channel and hint says what to send instead over plain HTTP; each endpoint's page lists its channels. In an iMessage group conversation, a reaction, typing or a read receipt answers it with param kind and channel_code group_unsupported: leave it out. Media to an SMS number without MMS answers it with param media and channel_code no_mms. An edit or unsend of an iMessage message that went by SMS or RCS (its network) answers it with channel_code not_on_sms: send a new message instead. An edit or unsend past the channel's time limit answers it with channel_code edit_window_closed or unsend_window_closed (iMessage: edits within 15 minutes of sending, unsends within 2 minutes; Telegram: unsends within 48 hours), and an iMessage edit of the message that started the conversation with first_message_not_editable; message states the limit and how long ago the message was sent. Send a new message instead. POST /v0/files answers it for a type Flow does not take (programs, web pages, unknown types). A send by file_id of a document a contact sent before Flow malware-scanned documents answers it too: Flow sends only documents it scanned.
new_contact_limit (429): the sender has used its budget for starting conversations. Wait retry_after seconds; replies into existing conversations still go.
sender_throttled (429): abuse signals tripped (the same text to many new contacts, many starts with no reply, blocks), so the sender may not start conversations until retry_after; replies into existing conversations still go. Personalise first messages and start only conversations people expect.
file_blocked (422): the file failed the malware scan and was not stored. Send a different file. (When the scan cannot run at all, the upload answers a retryable 500 api_error with Retry-After instead.)
rate_limited (429): either too many requests for this key (the per-key request limit, reported in the RateLimit-* headers) or sends faster than the sender's sending rate (pacing). Wait Retry-After (retry_after) seconds and retry with the same Idempotency-Key.
channel_error (502, or in message.failed): the channel refused or failed the message, or timed out; channel_code carries its own code. Read message, change what the channel objected to, and send again. From typing and read receipts, which call the channel at once, it is safe to ignore. SMS codes are Flow's, the same whichever carrier network carries the message: carrier_filtered (a carrier's spam filter blocked it: make it read like a person's message, no shortened links), unreachable, invalid_number, landline, registration_required (the number's 10DLC or toll-free registration is not approved yet), carrier_error, and provider_not_configured (the SMS sender is not fully set up on Flow's side, so nothing was sent; contact the Flow team). Flow's own codes on every channel: channel_timeout_unknown_outcome (in message.failed: the channel did not answer after the message was sent, and the resends its policy allows did not settle it, so the message may have arrived or not; check with the contact before sending it again) and unknown_outcome (from typing and read receipts: the call timed out after it was sent).
not_implemented (501): this endpoint or channel is not live yet during the beta. Use a channel that is live (Telegram, iMessage), or check the changelog.
api_error (500, 503): something went wrong on Flow's side. Retry with the same idempotency key after retry_after seconds, and quote request_id if it persists.

message string required

A sentence for a developer saying what went wrong. Do not parse it; switch on type.

hint string required

doc_url string<uri> required

The documentation page for this error's type, https://api.flow.engineer/docs/errors/<type>. It says what the error means, why it happens and how to fix it, with code.

param string

The request parameter the error is about, as a dotted path (kind, telegram.is_big, buttons, cards[1].header.type, limit).

retry_after integer

Seconds to wait before retrying, for errors that clear by themselves.

Range: 0 to any

channel enum<string>

The conversation's channel, on errors about what it takes (unsupported_content) and its windows (outside_window).

Available options: telegram, whatsapp, imessage, sms

conversation string

A conversation ID, conv_ and a ULID.

Pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$

sender string

A sender ID, snd_ and a ULID.

Pattern: ^snd_[0-9A-HJKMNP-TV-Z]{26}$

channel_code string

request_id string

Flow's ID for this request. Quote it when asking for help.

409 application/json

The request conflicts with the current state: the channel's window is closed (outside_window: WhatsApp's 24 hours for free-form messages, iMessage's 5 minutes after the contact's last message for typing), or the idempotency key was used for a different request or is still in use (idempotency_conflict).

error ErrorBody required

The details of an error.

Show child attributes

type enum<string> required

invalid_request (400, or 413 for a request body over the size limit): the request is malformed or a parameter is invalid. Fix the parameter named in param; the hint says what it must look like. Every endpoint answers it for a Flow-Version header that is not a version this API serves.
authentication (401): the API key is missing, malformed, unknown, revoked or expired. An Authorization: Bearer header with nothing after it usually means the environment variable holding the key was empty when the header was built (for an MCP client, when the server was added): the hint says so. Send Authorization: Bearer fk_test_... or fk_live_... with a current key; with no key at all, get a test key with POST /v0/sandbox/keys. A sandbox key past its expires_at has channel_code sandbox_key_expired: sign in to claim the app, or get a new key.
permission (403): the key may not do this, for example a test key using a live sender, a sandbox contact who joined another app, a new conversation from an iMessage line that may only reply, or a send past the app's sandbox allowance (channel_code sandbox_allowance_used, sandbox_contact_limit or sandbox_channel_not_included). Use the key of the right mode, have the contact send your join message, wait for the contact to message the line first, or sign in through the device flow to lift the allowance. On SMS: contact_opted_out (the contact texted STOP; nothing more goes to them until they text START), consent_required (a start to someone who never texted your numbers: record their consent with consent on the start). In a HIPAA account: hipaa_channel_not_covered (the channel has no business associate agreement; use SMS). Simulated conversations: simulated_contact (a real sender was pointed at a simulated contact; reply in the contact's simulated conversation), not_simulated (a simulated sender or test endpoint was pointed at a real contact), test_mode_only, simulated_conversation_limit. In message.failed: sandbox_contact_left (the contact joined another app on the sandbox sender while the message was queued; have them send your join message again).
not_found (404): no such object for this app and mode. Check the ID's prefix and that it was made with a key of the same mode (test and live data are separate).
idempotency_conflict (409): the idempotency key was used for a different request (channel_code body_mismatch: use a new key), or that request is still running (in_progress: wait retry_after seconds and repeat it with the same key), or it already created a secret that is shown only once (secret_not_kept: creating a webhook endpoint, rotating its secret, connecting a WhatsApp number; a secret that was lost must be rotated again, and a WhatsApp number connected again to see its verify token).
outside_window (409, or in message.failed): the channel will not deliver outside its conversation window. On WhatsApp the 24-hour window is closed: send a template (POST /v0/conversations/{conversation_id}/template, or POST /v0/messages with kind template to start), or wait for the contact to write. On iMessage the contact has not messaged the line (or opted in) yet, or not recently, so the failure arrives as a message.failed event: wait for the contact to write, then reply in that conversation. Typing and read receipts answer 409 outside_window directly when the channel's window for them is closed (iMessage typing works only within 5 minutes of the contact's last message; WhatsApp read receipts go at any time); ignore it and send your reply. On SMS, channel_code quiet_hours: the contact has not texted in the last hour and it is inside the sender's quiet hours in their time zone; retry after retry_after seconds, or wait for them to text. In message.failed: window_closed (WhatsApp's 24-hour window closed while the message was queued; send a template) and queued_too_long (the message waited in the queue longer than its sender allows, for example while the sender was paused; send it again if it still applies).
unsupported_content (422): the conversation's channel does not take this kind, field, block or value, and nothing was sent; Flow never converts a message. param names what was refused: kind (the endpoint's kind is not on this channel, such as a carousel on Telegram), a field or block (reply_to on SMS, telegram on WhatsApp, telegram.is_big), or the field whose value is not taken (emoji outside Telegram's reaction emoji, buttons for more than 3 WhatsApp buttons). channel is the conversation's channel and hint says what to send instead over plain HTTP; each endpoint's page lists its channels. In an iMessage group conversation, a reaction, typing or a read receipt answers it with param kind and channel_code group_unsupported: leave it out. Media to an SMS number without MMS answers it with param media and channel_code no_mms. An edit or unsend of an iMessage message that went by SMS or RCS (its network) answers it with channel_code not_on_sms: send a new message instead. An edit or unsend past the channel's time limit answers it with channel_code edit_window_closed or unsend_window_closed (iMessage: edits within 15 minutes of sending, unsends within 2 minutes; Telegram: unsends within 48 hours), and an iMessage edit of the message that started the conversation with first_message_not_editable; message states the limit and how long ago the message was sent. Send a new message instead. POST /v0/files answers it for a type Flow does not take (programs, web pages, unknown types). A send by file_id of a document a contact sent before Flow malware-scanned documents answers it too: Flow sends only documents it scanned.
new_contact_limit (429): the sender has used its budget for starting conversations. Wait retry_after seconds; replies into existing conversations still go.
sender_throttled (429): abuse signals tripped (the same text to many new contacts, many starts with no reply, blocks), so the sender may not start conversations until retry_after; replies into existing conversations still go. Personalise first messages and start only conversations people expect.
file_blocked (422): the file failed the malware scan and was not stored. Send a different file. (When the scan cannot run at all, the upload answers a retryable 500 api_error with Retry-After instead.)
rate_limited (429): either too many requests for this key (the per-key request limit, reported in the RateLimit-* headers) or sends faster than the sender's sending rate (pacing). Wait Retry-After (retry_after) seconds and retry with the same Idempotency-Key.
channel_error (502, or in message.failed): the channel refused or failed the message, or timed out; channel_code carries its own code. Read message, change what the channel objected to, and send again. From typing and read receipts, which call the channel at once, it is safe to ignore. SMS codes are Flow's, the same whichever carrier network carries the message: carrier_filtered (a carrier's spam filter blocked it: make it read like a person's message, no shortened links), unreachable, invalid_number, landline, registration_required (the number's 10DLC or toll-free registration is not approved yet), carrier_error, and provider_not_configured (the SMS sender is not fully set up on Flow's side, so nothing was sent; contact the Flow team). Flow's own codes on every channel: channel_timeout_unknown_outcome (in message.failed: the channel did not answer after the message was sent, and the resends its policy allows did not settle it, so the message may have arrived or not; check with the contact before sending it again) and unknown_outcome (from typing and read receipts: the call timed out after it was sent).
not_implemented (501): this endpoint or channel is not live yet during the beta. Use a channel that is live (Telegram, iMessage), or check the changelog.
api_error (500, 503): something went wrong on Flow's side. Retry with the same idempotency key after retry_after seconds, and quote request_id if it persists.

message string required

A sentence for a developer saying what went wrong. Do not parse it; switch on type.

hint string required

doc_url string<uri> required

The documentation page for this error's type, https://api.flow.engineer/docs/errors/<type>. It says what the error means, why it happens and how to fix it, with code.

param string

The request parameter the error is about, as a dotted path (kind, telegram.is_big, buttons, cards[1].header.type, limit).

retry_after integer

Seconds to wait before retrying, for errors that clear by themselves.

Range: 0 to any

channel enum<string>

The conversation's channel, on errors about what it takes (unsupported_content) and its windows (outside_window).

Available options: telegram, whatsapp, imessage, sms

conversation string

A conversation ID, conv_ and a ULID.

Pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$

sender string

A sender ID, snd_ and a ULID.

Pattern: ^snd_[0-9A-HJKMNP-TV-Z]{26}$

channel_code string

request_id string

Flow's ID for this request. Quote it when asking for help.

413 application/json

The request body is larger than Flow takes (invalid_request): 32 MB, or 101 MB for POST /v0/files (a 100 MB file and its multipart framing). A body that declares a larger Content-Length is refused before it is read. Send media as a file_id from POST /v0/files or by url instead of inlining it.

error ErrorBody required

The details of an error.

Show child attributes

type enum<string> required

invalid_request (400, or 413 for a request body over the size limit): the request is malformed or a parameter is invalid. Fix the parameter named in param; the hint says what it must look like. Every endpoint answers it for a Flow-Version header that is not a version this API serves.
authentication (401): the API key is missing, malformed, unknown, revoked or expired. An Authorization: Bearer header with nothing after it usually means the environment variable holding the key was empty when the header was built (for an MCP client, when the server was added): the hint says so. Send Authorization: Bearer fk_test_... or fk_live_... with a current key; with no key at all, get a test key with POST /v0/sandbox/keys. A sandbox key past its expires_at has channel_code sandbox_key_expired: sign in to claim the app, or get a new key.
permission (403): the key may not do this, for example a test key using a live sender, a sandbox contact who joined another app, a new conversation from an iMessage line that may only reply, or a send past the app's sandbox allowance (channel_code sandbox_allowance_used, sandbox_contact_limit or sandbox_channel_not_included). Use the key of the right mode, have the contact send your join message, wait for the contact to message the line first, or sign in through the device flow to lift the allowance. On SMS: contact_opted_out (the contact texted STOP; nothing more goes to them until they text START), consent_required (a start to someone who never texted your numbers: record their consent with consent on the start). In a HIPAA account: hipaa_channel_not_covered (the channel has no business associate agreement; use SMS). Simulated conversations: simulated_contact (a real sender was pointed at a simulated contact; reply in the contact's simulated conversation), not_simulated (a simulated sender or test endpoint was pointed at a real contact), test_mode_only, simulated_conversation_limit. In message.failed: sandbox_contact_left (the contact joined another app on the sandbox sender while the message was queued; have them send your join message again).
not_found (404): no such object for this app and mode. Check the ID's prefix and that it was made with a key of the same mode (test and live data are separate).
idempotency_conflict (409): the idempotency key was used for a different request (channel_code body_mismatch: use a new key), or that request is still running (in_progress: wait retry_after seconds and repeat it with the same key), or it already created a secret that is shown only once (secret_not_kept: creating a webhook endpoint, rotating its secret, connecting a WhatsApp number; a secret that was lost must be rotated again, and a WhatsApp number connected again to see its verify token).
outside_window (409, or in message.failed): the channel will not deliver outside its conversation window. On WhatsApp the 24-hour window is closed: send a template (POST /v0/conversations/{conversation_id}/template, or POST /v0/messages with kind template to start), or wait for the contact to write. On iMessage the contact has not messaged the line (or opted in) yet, or not recently, so the failure arrives as a message.failed event: wait for the contact to write, then reply in that conversation. Typing and read receipts answer 409 outside_window directly when the channel's window for them is closed (iMessage typing works only within 5 minutes of the contact's last message; WhatsApp read receipts go at any time); ignore it and send your reply. On SMS, channel_code quiet_hours: the contact has not texted in the last hour and it is inside the sender's quiet hours in their time zone; retry after retry_after seconds, or wait for them to text. In message.failed: window_closed (WhatsApp's 24-hour window closed while the message was queued; send a template) and queued_too_long (the message waited in the queue longer than its sender allows, for example while the sender was paused; send it again if it still applies).
unsupported_content (422): the conversation's channel does not take this kind, field, block or value, and nothing was sent; Flow never converts a message. param names what was refused: kind (the endpoint's kind is not on this channel, such as a carousel on Telegram), a field or block (reply_to on SMS, telegram on WhatsApp, telegram.is_big), or the field whose value is not taken (emoji outside Telegram's reaction emoji, buttons for more than 3 WhatsApp buttons). channel is the conversation's channel and hint says what to send instead over plain HTTP; each endpoint's page lists its channels. In an iMessage group conversation, a reaction, typing or a read receipt answers it with param kind and channel_code group_unsupported: leave it out. Media to an SMS number without MMS answers it with param media and channel_code no_mms. An edit or unsend of an iMessage message that went by SMS or RCS (its network) answers it with channel_code not_on_sms: send a new message instead. An edit or unsend past the channel's time limit answers it with channel_code edit_window_closed or unsend_window_closed (iMessage: edits within 15 minutes of sending, unsends within 2 minutes; Telegram: unsends within 48 hours), and an iMessage edit of the message that started the conversation with first_message_not_editable; message states the limit and how long ago the message was sent. Send a new message instead. POST /v0/files answers it for a type Flow does not take (programs, web pages, unknown types). A send by file_id of a document a contact sent before Flow malware-scanned documents answers it too: Flow sends only documents it scanned.
new_contact_limit (429): the sender has used its budget for starting conversations. Wait retry_after seconds; replies into existing conversations still go.
sender_throttled (429): abuse signals tripped (the same text to many new contacts, many starts with no reply, blocks), so the sender may not start conversations until retry_after; replies into existing conversations still go. Personalise first messages and start only conversations people expect.
file_blocked (422): the file failed the malware scan and was not stored. Send a different file. (When the scan cannot run at all, the upload answers a retryable 500 api_error with Retry-After instead.)
rate_limited (429): either too many requests for this key (the per-key request limit, reported in the RateLimit-* headers) or sends faster than the sender's sending rate (pacing). Wait Retry-After (retry_after) seconds and retry with the same Idempotency-Key.
channel_error (502, or in message.failed): the channel refused or failed the message, or timed out; channel_code carries its own code. Read message, change what the channel objected to, and send again. From typing and read receipts, which call the channel at once, it is safe to ignore. SMS codes are Flow's, the same whichever carrier network carries the message: carrier_filtered (a carrier's spam filter blocked it: make it read like a person's message, no shortened links), unreachable, invalid_number, landline, registration_required (the number's 10DLC or toll-free registration is not approved yet), carrier_error, and provider_not_configured (the SMS sender is not fully set up on Flow's side, so nothing was sent; contact the Flow team). Flow's own codes on every channel: channel_timeout_unknown_outcome (in message.failed: the channel did not answer after the message was sent, and the resends its policy allows did not settle it, so the message may have arrived or not; check with the contact before sending it again) and unknown_outcome (from typing and read receipts: the call timed out after it was sent).
not_implemented (501): this endpoint or channel is not live yet during the beta. Use a channel that is live (Telegram, iMessage), or check the changelog.
api_error (500, 503): something went wrong on Flow's side. Retry with the same idempotency key after retry_after seconds, and quote request_id if it persists.

message string required

A sentence for a developer saying what went wrong. Do not parse it; switch on type.

hint string required

doc_url string<uri> required

The documentation page for this error's type, https://api.flow.engineer/docs/errors/<type>. It says what the error means, why it happens and how to fix it, with code.

param string

The request parameter the error is about, as a dotted path (kind, telegram.is_big, buttons, cards[1].header.type, limit).

retry_after integer

Seconds to wait before retrying, for errors that clear by themselves.

Range: 0 to any

channel enum<string>

The conversation's channel, on errors about what it takes (unsupported_content) and its windows (outside_window).

Available options: telegram, whatsapp, imessage, sms

conversation string

A conversation ID, conv_ and a ULID.

Pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$

sender string

A sender ID, snd_ and a ULID.

Pattern: ^snd_[0-9A-HJKMNP-TV-Z]{26}$

channel_code string

request_id string

Flow's ID for this request. Quote it when asking for help.

422 application/json

The conversation's channel does not take this kind, field, block or value, so nothing was sent (unsupported_content). param names what was refused, channel the channel, and hint what to send instead.

error ErrorBody required

The details of an error.

Show child attributes

type enum<string> required

invalid_request (400, or 413 for a request body over the size limit): the request is malformed or a parameter is invalid. Fix the parameter named in param; the hint says what it must look like. Every endpoint answers it for a Flow-Version header that is not a version this API serves.
authentication (401): the API key is missing, malformed, unknown, revoked or expired. An Authorization: Bearer header with nothing after it usually means the environment variable holding the key was empty when the header was built (for an MCP client, when the server was added): the hint says so. Send Authorization: Bearer fk_test_... or fk_live_... with a current key; with no key at all, get a test key with POST /v0/sandbox/keys. A sandbox key past its expires_at has channel_code sandbox_key_expired: sign in to claim the app, or get a new key.
permission (403): the key may not do this, for example a test key using a live sender, a sandbox contact who joined another app, a new conversation from an iMessage line that may only reply, or a send past the app's sandbox allowance (channel_code sandbox_allowance_used, sandbox_contact_limit or sandbox_channel_not_included). Use the key of the right mode, have the contact send your join message, wait for the contact to message the line first, or sign in through the device flow to lift the allowance. On SMS: contact_opted_out (the contact texted STOP; nothing more goes to them until they text START), consent_required (a start to someone who never texted your numbers: record their consent with consent on the start). In a HIPAA account: hipaa_channel_not_covered (the channel has no business associate agreement; use SMS). Simulated conversations: simulated_contact (a real sender was pointed at a simulated contact; reply in the contact's simulated conversation), not_simulated (a simulated sender or test endpoint was pointed at a real contact), test_mode_only, simulated_conversation_limit. In message.failed: sandbox_contact_left (the contact joined another app on the sandbox sender while the message was queued; have them send your join message again).
not_found (404): no such object for this app and mode. Check the ID's prefix and that it was made with a key of the same mode (test and live data are separate).
idempotency_conflict (409): the idempotency key was used for a different request (channel_code body_mismatch: use a new key), or that request is still running (in_progress: wait retry_after seconds and repeat it with the same key), or it already created a secret that is shown only once (secret_not_kept: creating a webhook endpoint, rotating its secret, connecting a WhatsApp number; a secret that was lost must be rotated again, and a WhatsApp number connected again to see its verify token).
outside_window (409, or in message.failed): the channel will not deliver outside its conversation window. On WhatsApp the 24-hour window is closed: send a template (POST /v0/conversations/{conversation_id}/template, or POST /v0/messages with kind template to start), or wait for the contact to write. On iMessage the contact has not messaged the line (or opted in) yet, or not recently, so the failure arrives as a message.failed event: wait for the contact to write, then reply in that conversation. Typing and read receipts answer 409 outside_window directly when the channel's window for them is closed (iMessage typing works only within 5 minutes of the contact's last message; WhatsApp read receipts go at any time); ignore it and send your reply. On SMS, channel_code quiet_hours: the contact has not texted in the last hour and it is inside the sender's quiet hours in their time zone; retry after retry_after seconds, or wait for them to text. In message.failed: window_closed (WhatsApp's 24-hour window closed while the message was queued; send a template) and queued_too_long (the message waited in the queue longer than its sender allows, for example while the sender was paused; send it again if it still applies).
unsupported_content (422): the conversation's channel does not take this kind, field, block or value, and nothing was sent; Flow never converts a message. param names what was refused: kind (the endpoint's kind is not on this channel, such as a carousel on Telegram), a field or block (reply_to on SMS, telegram on WhatsApp, telegram.is_big), or the field whose value is not taken (emoji outside Telegram's reaction emoji, buttons for more than 3 WhatsApp buttons). channel is the conversation's channel and hint says what to send instead over plain HTTP; each endpoint's page lists its channels. In an iMessage group conversation, a reaction, typing or a read receipt answers it with param kind and channel_code group_unsupported: leave it out. Media to an SMS number without MMS answers it with param media and channel_code no_mms. An edit or unsend of an iMessage message that went by SMS or RCS (its network) answers it with channel_code not_on_sms: send a new message instead. An edit or unsend past the channel's time limit answers it with channel_code edit_window_closed or unsend_window_closed (iMessage: edits within 15 minutes of sending, unsends within 2 minutes; Telegram: unsends within 48 hours), and an iMessage edit of the message that started the conversation with first_message_not_editable; message states the limit and how long ago the message was sent. Send a new message instead. POST /v0/files answers it for a type Flow does not take (programs, web pages, unknown types). A send by file_id of a document a contact sent before Flow malware-scanned documents answers it too: Flow sends only documents it scanned.
new_contact_limit (429): the sender has used its budget for starting conversations. Wait retry_after seconds; replies into existing conversations still go.
sender_throttled (429): abuse signals tripped (the same text to many new contacts, many starts with no reply, blocks), so the sender may not start conversations until retry_after; replies into existing conversations still go. Personalise first messages and start only conversations people expect.
file_blocked (422): the file failed the malware scan and was not stored. Send a different file. (When the scan cannot run at all, the upload answers a retryable 500 api_error with Retry-After instead.)
rate_limited (429): either too many requests for this key (the per-key request limit, reported in the RateLimit-* headers) or sends faster than the sender's sending rate (pacing). Wait Retry-After (retry_after) seconds and retry with the same Idempotency-Key.
channel_error (502, or in message.failed): the channel refused or failed the message, or timed out; channel_code carries its own code. Read message, change what the channel objected to, and send again. From typing and read receipts, which call the channel at once, it is safe to ignore. SMS codes are Flow's, the same whichever carrier network carries the message: carrier_filtered (a carrier's spam filter blocked it: make it read like a person's message, no shortened links), unreachable, invalid_number, landline, registration_required (the number's 10DLC or toll-free registration is not approved yet), carrier_error, and provider_not_configured (the SMS sender is not fully set up on Flow's side, so nothing was sent; contact the Flow team). Flow's own codes on every channel: channel_timeout_unknown_outcome (in message.failed: the channel did not answer after the message was sent, and the resends its policy allows did not settle it, so the message may have arrived or not; check with the contact before sending it again) and unknown_outcome (from typing and read receipts: the call timed out after it was sent).
not_implemented (501): this endpoint or channel is not live yet during the beta. Use a channel that is live (Telegram, iMessage), or check the changelog.
api_error (500, 503): something went wrong on Flow's side. Retry with the same idempotency key after retry_after seconds, and quote request_id if it persists.

message string required

A sentence for a developer saying what went wrong. Do not parse it; switch on type.

hint string required

doc_url string<uri> required

The documentation page for this error's type, https://api.flow.engineer/docs/errors/<type>. It says what the error means, why it happens and how to fix it, with code.

param string

The request parameter the error is about, as a dotted path (kind, telegram.is_big, buttons, cards[1].header.type, limit).

retry_after integer

Seconds to wait before retrying, for errors that clear by themselves.

Range: 0 to any

channel enum<string>

The conversation's channel, on errors about what it takes (unsupported_content) and its windows (outside_window).

Available options: telegram, whatsapp, imessage, sms

conversation string

A conversation ID, conv_ and a ULID.

Pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$

sender string

A sender ID, snd_ and a ULID.

Pattern: ^snd_[0-9A-HJKMNP-TV-Z]{26}$

channel_code string

request_id string

Flow's ID for this request. Quote it when asking for help.

429 application/json

Too many requests (rate_limited): either this key's request limit (see the RateLimit-* headers) or the sender's sending rate (pacing) was exceeded; retry after Retry-After seconds (also error.retry_after) with the same Idempotency-Key. Or the sender has used its budget for starting conversations (new_contact_limit), or the sender is throttled after abuse signals (sender_throttled); wait retry_after seconds.

error ErrorBody required

The details of an error.

Show child attributes

type enum<string> required

invalid_request (400, or 413 for a request body over the size limit): the request is malformed or a parameter is invalid. Fix the parameter named in param; the hint says what it must look like. Every endpoint answers it for a Flow-Version header that is not a version this API serves.
authentication (401): the API key is missing, malformed, unknown, revoked or expired. An Authorization: Bearer header with nothing after it usually means the environment variable holding the key was empty when the header was built (for an MCP client, when the server was added): the hint says so. Send Authorization: Bearer fk_test_... or fk_live_... with a current key; with no key at all, get a test key with POST /v0/sandbox/keys. A sandbox key past its expires_at has channel_code sandbox_key_expired: sign in to claim the app, or get a new key.
permission (403): the key may not do this, for example a test key using a live sender, a sandbox contact who joined another app, a new conversation from an iMessage line that may only reply, or a send past the app's sandbox allowance (channel_code sandbox_allowance_used, sandbox_contact_limit or sandbox_channel_not_included). Use the key of the right mode, have the contact send your join message, wait for the contact to message the line first, or sign in through the device flow to lift the allowance. On SMS: contact_opted_out (the contact texted STOP; nothing more goes to them until they text START), consent_required (a start to someone who never texted your numbers: record their consent with consent on the start). In a HIPAA account: hipaa_channel_not_covered (the channel has no business associate agreement; use SMS). Simulated conversations: simulated_contact (a real sender was pointed at a simulated contact; reply in the contact's simulated conversation), not_simulated (a simulated sender or test endpoint was pointed at a real contact), test_mode_only, simulated_conversation_limit. In message.failed: sandbox_contact_left (the contact joined another app on the sandbox sender while the message was queued; have them send your join message again).
not_found (404): no such object for this app and mode. Check the ID's prefix and that it was made with a key of the same mode (test and live data are separate).
idempotency_conflict (409): the idempotency key was used for a different request (channel_code body_mismatch: use a new key), or that request is still running (in_progress: wait retry_after seconds and repeat it with the same key), or it already created a secret that is shown only once (secret_not_kept: creating a webhook endpoint, rotating its secret, connecting a WhatsApp number; a secret that was lost must be rotated again, and a WhatsApp number connected again to see its verify token).
outside_window (409, or in message.failed): the channel will not deliver outside its conversation window. On WhatsApp the 24-hour window is closed: send a template (POST /v0/conversations/{conversation_id}/template, or POST /v0/messages with kind template to start), or wait for the contact to write. On iMessage the contact has not messaged the line (or opted in) yet, or not recently, so the failure arrives as a message.failed event: wait for the contact to write, then reply in that conversation. Typing and read receipts answer 409 outside_window directly when the channel's window for them is closed (iMessage typing works only within 5 minutes of the contact's last message; WhatsApp read receipts go at any time); ignore it and send your reply. On SMS, channel_code quiet_hours: the contact has not texted in the last hour and it is inside the sender's quiet hours in their time zone; retry after retry_after seconds, or wait for them to text. In message.failed: window_closed (WhatsApp's 24-hour window closed while the message was queued; send a template) and queued_too_long (the message waited in the queue longer than its sender allows, for example while the sender was paused; send it again if it still applies).
unsupported_content (422): the conversation's channel does not take this kind, field, block or value, and nothing was sent; Flow never converts a message. param names what was refused: kind (the endpoint's kind is not on this channel, such as a carousel on Telegram), a field or block (reply_to on SMS, telegram on WhatsApp, telegram.is_big), or the field whose value is not taken (emoji outside Telegram's reaction emoji, buttons for more than 3 WhatsApp buttons). channel is the conversation's channel and hint says what to send instead over plain HTTP; each endpoint's page lists its channels. In an iMessage group conversation, a reaction, typing or a read receipt answers it with param kind and channel_code group_unsupported: leave it out. Media to an SMS number without MMS answers it with param media and channel_code no_mms. An edit or unsend of an iMessage message that went by SMS or RCS (its network) answers it with channel_code not_on_sms: send a new message instead. An edit or unsend past the channel's time limit answers it with channel_code edit_window_closed or unsend_window_closed (iMessage: edits within 15 minutes of sending, unsends within 2 minutes; Telegram: unsends within 48 hours), and an iMessage edit of the message that started the conversation with first_message_not_editable; message states the limit and how long ago the message was sent. Send a new message instead. POST /v0/files answers it for a type Flow does not take (programs, web pages, unknown types). A send by file_id of a document a contact sent before Flow malware-scanned documents answers it too: Flow sends only documents it scanned.
new_contact_limit (429): the sender has used its budget for starting conversations. Wait retry_after seconds; replies into existing conversations still go.
sender_throttled (429): abuse signals tripped (the same text to many new contacts, many starts with no reply, blocks), so the sender may not start conversations until retry_after; replies into existing conversations still go. Personalise first messages and start only conversations people expect.
file_blocked (422): the file failed the malware scan and was not stored. Send a different file. (When the scan cannot run at all, the upload answers a retryable 500 api_error with Retry-After instead.)
rate_limited (429): either too many requests for this key (the per-key request limit, reported in the RateLimit-* headers) or sends faster than the sender's sending rate (pacing). Wait Retry-After (retry_after) seconds and retry with the same Idempotency-Key.
channel_error (502, or in message.failed): the channel refused or failed the message, or timed out; channel_code carries its own code. Read message, change what the channel objected to, and send again. From typing and read receipts, which call the channel at once, it is safe to ignore. SMS codes are Flow's, the same whichever carrier network carries the message: carrier_filtered (a carrier's spam filter blocked it: make it read like a person's message, no shortened links), unreachable, invalid_number, landline, registration_required (the number's 10DLC or toll-free registration is not approved yet), carrier_error, and provider_not_configured (the SMS sender is not fully set up on Flow's side, so nothing was sent; contact the Flow team). Flow's own codes on every channel: channel_timeout_unknown_outcome (in message.failed: the channel did not answer after the message was sent, and the resends its policy allows did not settle it, so the message may have arrived or not; check with the contact before sending it again) and unknown_outcome (from typing and read receipts: the call timed out after it was sent).
not_implemented (501): this endpoint or channel is not live yet during the beta. Use a channel that is live (Telegram, iMessage), or check the changelog.
api_error (500, 503): something went wrong on Flow's side. Retry with the same idempotency key after retry_after seconds, and quote request_id if it persists.

message string required

A sentence for a developer saying what went wrong. Do not parse it; switch on type.

hint string required

doc_url string<uri> required

The documentation page for this error's type, https://api.flow.engineer/docs/errors/<type>. It says what the error means, why it happens and how to fix it, with code.

param string

The request parameter the error is about, as a dotted path (kind, telegram.is_big, buttons, cards[1].header.type, limit).

retry_after integer

Seconds to wait before retrying, for errors that clear by themselves.

Range: 0 to any

channel enum<string>

The conversation's channel, on errors about what it takes (unsupported_content) and its windows (outside_window).

Available options: telegram, whatsapp, imessage, sms

conversation string

A conversation ID, conv_ and a ULID.

Pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$

sender string

A sender ID, snd_ and a ULID.

Pattern: ^snd_[0-9A-HJKMNP-TV-Z]{26}$

channel_code string

request_id string

Flow's ID for this request. Quote it when asking for help.

default application/json

An error. error.type says which (see ErrorType).

error ErrorBody required

The details of an error.

Show child attributes

type enum<string> required

invalid_request (400, or 413 for a request body over the size limit): the request is malformed or a parameter is invalid. Fix the parameter named in param; the hint says what it must look like. Every endpoint answers it for a Flow-Version header that is not a version this API serves.
authentication (401): the API key is missing, malformed, unknown, revoked or expired. An Authorization: Bearer header with nothing after it usually means the environment variable holding the key was empty when the header was built (for an MCP client, when the server was added): the hint says so. Send Authorization: Bearer fk_test_... or fk_live_... with a current key; with no key at all, get a test key with POST /v0/sandbox/keys. A sandbox key past its expires_at has channel_code sandbox_key_expired: sign in to claim the app, or get a new key.
permission (403): the key may not do this, for example a test key using a live sender, a sandbox contact who joined another app, a new conversation from an iMessage line that may only reply, or a send past the app's sandbox allowance (channel_code sandbox_allowance_used, sandbox_contact_limit or sandbox_channel_not_included). Use the key of the right mode, have the contact send your join message, wait for the contact to message the line first, or sign in through the device flow to lift the allowance. On SMS: contact_opted_out (the contact texted STOP; nothing more goes to them until they text START), consent_required (a start to someone who never texted your numbers: record their consent with consent on the start). In a HIPAA account: hipaa_channel_not_covered (the channel has no business associate agreement; use SMS). Simulated conversations: simulated_contact (a real sender was pointed at a simulated contact; reply in the contact's simulated conversation), not_simulated (a simulated sender or test endpoint was pointed at a real contact), test_mode_only, simulated_conversation_limit. In message.failed: sandbox_contact_left (the contact joined another app on the sandbox sender while the message was queued; have them send your join message again).
not_found (404): no such object for this app and mode. Check the ID's prefix and that it was made with a key of the same mode (test and live data are separate).
idempotency_conflict (409): the idempotency key was used for a different request (channel_code body_mismatch: use a new key), or that request is still running (in_progress: wait retry_after seconds and repeat it with the same key), or it already created a secret that is shown only once (secret_not_kept: creating a webhook endpoint, rotating its secret, connecting a WhatsApp number; a secret that was lost must be rotated again, and a WhatsApp number connected again to see its verify token).
outside_window (409, or in message.failed): the channel will not deliver outside its conversation window. On WhatsApp the 24-hour window is closed: send a template (POST /v0/conversations/{conversation_id}/template, or POST /v0/messages with kind template to start), or wait for the contact to write. On iMessage the contact has not messaged the line (or opted in) yet, or not recently, so the failure arrives as a message.failed event: wait for the contact to write, then reply in that conversation. Typing and read receipts answer 409 outside_window directly when the channel's window for them is closed (iMessage typing works only within 5 minutes of the contact's last message; WhatsApp read receipts go at any time); ignore it and send your reply. On SMS, channel_code quiet_hours: the contact has not texted in the last hour and it is inside the sender's quiet hours in their time zone; retry after retry_after seconds, or wait for them to text. In message.failed: window_closed (WhatsApp's 24-hour window closed while the message was queued; send a template) and queued_too_long (the message waited in the queue longer than its sender allows, for example while the sender was paused; send it again if it still applies).
unsupported_content (422): the conversation's channel does not take this kind, field, block or value, and nothing was sent; Flow never converts a message. param names what was refused: kind (the endpoint's kind is not on this channel, such as a carousel on Telegram), a field or block (reply_to on SMS, telegram on WhatsApp, telegram.is_big), or the field whose value is not taken (emoji outside Telegram's reaction emoji, buttons for more than 3 WhatsApp buttons). channel is the conversation's channel and hint says what to send instead over plain HTTP; each endpoint's page lists its channels. In an iMessage group conversation, a reaction, typing or a read receipt answers it with param kind and channel_code group_unsupported: leave it out. Media to an SMS number without MMS answers it with param media and channel_code no_mms. An edit or unsend of an iMessage message that went by SMS or RCS (its network) answers it with channel_code not_on_sms: send a new message instead. An edit or unsend past the channel's time limit answers it with channel_code edit_window_closed or unsend_window_closed (iMessage: edits within 15 minutes of sending, unsends within 2 minutes; Telegram: unsends within 48 hours), and an iMessage edit of the message that started the conversation with first_message_not_editable; message states the limit and how long ago the message was sent. Send a new message instead. POST /v0/files answers it for a type Flow does not take (programs, web pages, unknown types). A send by file_id of a document a contact sent before Flow malware-scanned documents answers it too: Flow sends only documents it scanned.
new_contact_limit (429): the sender has used its budget for starting conversations. Wait retry_after seconds; replies into existing conversations still go.
sender_throttled (429): abuse signals tripped (the same text to many new contacts, many starts with no reply, blocks), so the sender may not start conversations until retry_after; replies into existing conversations still go. Personalise first messages and start only conversations people expect.
file_blocked (422): the file failed the malware scan and was not stored. Send a different file. (When the scan cannot run at all, the upload answers a retryable 500 api_error with Retry-After instead.)
rate_limited (429): either too many requests for this key (the per-key request limit, reported in the RateLimit-* headers) or sends faster than the sender's sending rate (pacing). Wait Retry-After (retry_after) seconds and retry with the same Idempotency-Key.
channel_error (502, or in message.failed): the channel refused or failed the message, or timed out; channel_code carries its own code. Read message, change what the channel objected to, and send again. From typing and read receipts, which call the channel at once, it is safe to ignore. SMS codes are Flow's, the same whichever carrier network carries the message: carrier_filtered (a carrier's spam filter blocked it: make it read like a person's message, no shortened links), unreachable, invalid_number, landline, registration_required (the number's 10DLC or toll-free registration is not approved yet), carrier_error, and provider_not_configured (the SMS sender is not fully set up on Flow's side, so nothing was sent; contact the Flow team). Flow's own codes on every channel: channel_timeout_unknown_outcome (in message.failed: the channel did not answer after the message was sent, and the resends its policy allows did not settle it, so the message may have arrived or not; check with the contact before sending it again) and unknown_outcome (from typing and read receipts: the call timed out after it was sent).
not_implemented (501): this endpoint or channel is not live yet during the beta. Use a channel that is live (Telegram, iMessage), or check the changelog.
api_error (500, 503): something went wrong on Flow's side. Retry with the same idempotency key after retry_after seconds, and quote request_id if it persists.

message string required

A sentence for a developer saying what went wrong. Do not parse it; switch on type.

hint string required

doc_url string<uri> required

The documentation page for this error's type, https://api.flow.engineer/docs/errors/<type>. It says what the error means, why it happens and how to fix it, with code.

param string

The request parameter the error is about, as a dotted path (kind, telegram.is_big, buttons, cards[1].header.type, limit).

retry_after integer

Seconds to wait before retrying, for errors that clear by themselves.

Range: 0 to any

channel enum<string>

The conversation's channel, on errors about what it takes (unsupported_content) and its windows (outside_window).

Available options: telegram, whatsapp, imessage, sms

conversation string

A conversation ID, conv_ and a ULID.

Pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$

sender string

A sender ID, snd_ and a ULID.

Pattern: ^snd_[0-9A-HJKMNP-TV-Z]{26}$

channel_code string

request_id string

Flow's ID for this request. Quote it when asking for help.

curl --request POST \
  --url https://api.flow.engineer/v0/conversations/{conversation_id}/buttons \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "text": "Which size?",
  "buttons": [
    {
      "id": "size_s",
      "label": "Small"
    },
    {
      "id": "size_m",
      "label": "Medium"
    },
    {
      "id": "size_l",
      "label": "Large"
    }
  ]
}'

const response = await fetch("https://api.flow.engineer/v0/conversations/{conversation_id}/buttons", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "text": "Which size?",
    "buttons": [
      {
        "id": "size_s",
        "label": "Small"
      },
      {
        "id": "size_m",
        "label": "Medium"
      },
      {
        "id": "size_l",
        "label": "Large"
      }
    ]
  })
});

console.log(await response.json());

import requests

response = requests.post(
    "https://api.flow.engineer/v0/conversations/{conversation_id}/buttons",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json"
    },
    json={
        "text": "Which size?",
        "buttons": [
            {
                "id": "size_s",
                "label": "Small"
            },
            {
                "id": "size_m",
                "label": "Medium"
            },
            {
                "id": "size_l",
                "label": "Large"
            }
        ]
    },
)

print(response.json())

package main

import (
  "fmt"
  "io"
  "net/http"
  "strings"
)

func main() {
  payload := strings.NewReader(`{"text":"Which size?","buttons":[{"id":"size_s","label":"Small"},{"id":"size_m","label":"Medium"},{"id":"size_l","label":"Large"}]}`)
  req, _ := http.NewRequest("POST", "https://api.flow.engineer/v0/conversations/{conversation_id}/buttons", payload)
  req.Header.Add("Authorization", "Bearer <token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  fmt.Println(string(body))
}

Request examples

Three reply buttons
An image header and one reply button

{
  "text": "Which size?",
  "buttons": [
    {
      "id": "size_s",
      "label": "Small"
    },
    {
      "id": "size_m",
      "label": "Medium"
    },
    {
      "id": "size_l",
      "label": "Large"
    }
  ]
}

{
  "header": {
    "type": "image",
    "url": "https://example.com/a.jpg"
  },
  "text": "Linen shirt, 1,499",
  "buttons": [
    {
      "id": "buy_a",
      "label": "Buy"
    }
  ]
}

Response examples

{
  "id": "msg_01JB8ZD4M6P8R0T2V4X6Z8B0C2",
  "conversation": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
  "direction": "in",
  "from": "ct_01JB8ZB2J4K6N8Q0S2V4W6Y8A0",
  "status": "received",
  "content": {
    "kind": "basic",
    "text": "<string>",
    "media": {
      "type": "image",
      "url": "<string>",
      "file_id": "file_01JB8ZG7Q9S1V3X5Z7B9D1F3G5",
      "filename": "<string>",
      "mime_type": "<string>",
      "size_bytes": 0
    },
    "reply_to": "msg_01JB8ZD4M6P8R0T2V4X6Z8B0C2",
    "link_preview": true,
    "telegram": {
      "parse_mode": "HTML",
      "disable_notification": true,
      "protect_content": true,
      "show_caption_above_media": true,
      "has_spoiler": true
    },
    "imessage": {
      "styles": [
        {
          "start": 0,
          "length": 1,
          "style": "bold"
        }
      ],
      "subject": "<string>"
    },
    "metadata": {}
  },
  "network": "imessage",
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "hint": "Send a template instead: POST /v0/conversations/{conversation_id}/template.",
    "doc_url": "https://api.flow.engineer/docs/errors/outside_window",
    "param": "<string>",
    "retry_after": 0,
    "channel": "telegram",
    "conversation": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
    "sender": "snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T",
    "channel_code": "<string>",
    "request_id": "<string>"
  },
  "channel_message_id": "<string>",
  "sms": {
    "segments": 1,
    "encoding": "gsm7"
  },
  "reply_to": "msg_01JB8ZD4M6P8R0T2V4X6Z8B0C2",
  "livemode": true,
  "metadata": {},
  "created_at": "2026-11-01T12:00:00Z",
  "updated_at": "2026-11-01T12:00:00Z"
}

{
  "error": {
    "type": "invalid_request",
    "message": "limit must be between 1 and 100.",
    "hint": "Pass limit between 1 and 100 (default 20), and page with after or before.",
    "doc_url": "https://api.flow.engineer/docs/errors/invalid_request",
    "param": "limit"
  }
}

{
  "error": {
    "type": "authentication",
    "message": "No valid API key was given.",
    "hint": "Send the header Authorization: Bearer fk_test_... (or fk_live_...); no key yet? Get a test key with curl -X POST https://api.flow.engineer/v0/sandbox/keys",
    "doc_url": "https://api.flow.engineer/docs/errors/authentication"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "hint": "Send a template instead: POST /v0/conversations/{conversation_id}/template.",
    "doc_url": "https://api.flow.engineer/docs/errors/outside_window",
    "param": "<string>",
    "retry_after": 0,
    "channel": "telegram",
    "conversation": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
    "sender": "snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T",
    "channel_code": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "hint": "Send a template instead: POST /v0/conversations/{conversation_id}/template.",
    "doc_url": "https://api.flow.engineer/docs/errors/outside_window",
    "param": "<string>",
    "retry_after": 0,
    "channel": "telegram",
    "conversation": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
    "sender": "snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T",
    "channel_code": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "type": "outside_window",
    "message": "Last message from the contact was 31h ago; WhatsApp allows only templates now.",
    "hint": "Send a template instead: POST /v0/conversations/{conversation_id}/template.",
    "doc_url": "https://api.flow.engineer/docs/errors/outside_window",
    "channel": "whatsapp",
    "conversation": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "The request body is larger than 33554432 bytes.",
    "hint": "Send a smaller body; upload media with POST /v0/files and send its file_id instead of inlining it.",
    "doc_url": "https://api.flow.engineer/docs/errors/invalid_request"
  }
}

{
  "error": {
    "type": "unsupported_content",
    "channel": "telegram",
    "param": "kind",
    "message": "Carousels work on WhatsApp only.",
    "hint": "On Telegram, send a basic message, then one buttons message with an image header per card.",
    "doc_url": "https://api.flow.engineer/docs/errors/unsupported_content",
    "conversation": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1"
  }
}

{
  "error": {
    "type": "new_contact_limit",
    "message": "This sender has started its 15 new conversations for today.",
    "hint": "Retry after 3600 seconds; replies into existing conversations still go.",
    "doc_url": "https://api.flow.engineer/docs/errors/new_contact_limit",
    "retry_after": 3600,
    "sender": "snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "hint": "Send a template instead: POST /v0/conversations/{conversation_id}/template.",
    "doc_url": "https://api.flow.engineer/docs/errors/outside_window",
    "param": "<string>",
    "retry_after": 0,
    "channel": "telegram",
    "conversation": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
    "sender": "snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T",
    "channel_code": "<string>",
    "request_id": "<string>"
  }
}

Was this page helpful?