curl --request POST \
  --url https://api.flow.engineer/v0/test/conversations/{conversation_id}/inbound \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "content": {
    "kind": "basic",
    "text": "Do you deliver on Sundays?"
  }
}
'

{
  "message": "msg_01JB8ZD4M6P8R0T2V4X6Z8B0C2",
  "conversation": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
  "channel_message_id": "<string>",
  "status": "queued"
}

{
  "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": "permission",
    "message": "This account handles health information under a business associate agreement, and Telegram is not a channel Flow holds such an agreement for, so it cannot be simulated here either.",
    "hint": "Simulate an SMS conversation instead: POST /v0/test/conversations with {\"channel\":\"sms\"}.",
    "doc_url": "https://api.flow.engineer/docs/errors/permission",
    "param": "conversation_id",
    "channel_code": "hipaa_channel_not_covered"
  }
}

{
  "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": 1,
    "channel": "telegram",
    "conversation": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
    "sender": "snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T",
    "channel_code": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "type": "idempotency_conflict",
    "message": "This Idempotency-Key was already used for a different request (another method, path or body).",
    "hint": "Use a new Idempotency-Key for this request; reuse a key only to repeat the identical request.",
    "doc_url": "https://api.flow.engineer/docs/errors/idempotency_conflict",
    "param": "Idempotency-Key",
    "channel_code": "body_mismatch"
  }
}

{
  "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": 1,
    "channel": "telegram",
    "conversation": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
    "sender": "snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T",
    "channel_code": "<string>",
    "request_id": "<string>"
  }
}

Simulated conversations

Write as the simulated contact

Test keys only. Posts one inbound turn from the simulated contact of a simulated conversation. It goes through the same inbound path as a real channel’s message: Flow stores it, then delivers it as a message.received event by webhook, on the stream and in the event log, in order with the conversation’s other events. A webhook answer’s reply works as usual. The answer comes before delivery; the message.received event carries the message ID given here.

content is what the contact sends, as a kind object with kind: basic (text and/or media), voice, location, contact_card or button_reply (a tap on a reply button of a buttons or carousel message your agent sent, or on a row of a list, given as its message_id and button_id: Flow fills in the label). Media and voice take the file_id of a file uploaded with POST /v0/files (no url); the contact’s message refers to that same file (its file_id, url, mime_type and size_bytes): Flow does not copy it again. The channel’s rules apply: what it cannot carry from a person (a document over SMS, a location over SMS, a file larger than the channel fetches from a person) answers 422 unsupported_content, and text over the channel’s limit answers 400 invalid_request.

On SMS, the keywords work as from a real phone, matched against the whole text. STOP (or STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, REVOKE, OPT OUT, OPTOUT) opts the simulated contact out against the simulated sender: the contact’s opted_out_at is set and opted_out_via is keyword, and sends to them answer 403 permission with channel_code contact_opted_out. START (or UNSTOP, YES) lifts it. The turn is still delivered as message.received. A keyword reply is never recorded as a message, so the transcript shows no automatic reply to STOP, START or HELP.

On WhatsApp, each turn opens the conversation’s 24-hour window, as a real contact’s message does.

A conversation that is not simulated answers 403 permission with channel_code not_simulated; a live key answers 403 permission with channel_code test_mode_only. In a HIPAA account (Account.hipaa), a turn on a simulated telegram, whatsapp or imessage conversation (one made before the flag was set) answers 403 permission with channel_code hipaa_channel_not_covered (param conversation_id).

POST

test

conversations

{conversation_id}

inbound

curl --request POST \
  --url https://api.flow.engineer/v0/test/conversations/{conversation_id}/inbound \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "content": {
    "kind": "basic",
    "text": "Do you deliver on Sundays?"
  }
}
'

{
  "message": "msg_01JB8ZD4M6P8R0T2V4X6Z8B0C2",
  "conversation": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
  "channel_message_id": "<string>",
  "status": "queued"
}

{
  "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": "permission",
    "message": "This account handles health information under a business associate agreement, and Telegram is not a channel Flow holds such an agreement for, so it cannot be simulated here either.",
    "hint": "Simulate an SMS conversation instead: POST /v0/test/conversations with {\"channel\":\"sms\"}.",
    "doc_url": "https://api.flow.engineer/docs/errors/permission",
    "param": "conversation_id",
    "channel_code": "hipaa_channel_not_covered"
  }
}

{
  "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": 1,
    "channel": "telegram",
    "conversation": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
    "sender": "snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T",
    "channel_code": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "type": "idempotency_conflict",
    "message": "This Idempotency-Key was already used for a different request (another method, path or body).",
    "hint": "Use a new Idempotency-Key for this request; reuse a key only to repeat the identical request.",
    "doc_url": "https://api.flow.engineer/docs/errors/idempotency_conflict",
    "param": "Idempotency-Key",
    "channel_code": "body_mismatch"
  }
}

{
  "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": 1,
    "channel": "telegram",
    "conversation": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
    "sender": "snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T",
    "channel_code": "<string>",
    "request_id": "<string>"
  }
}

Authorizations

Authorization

string

header

required

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

Headers

Idempotency-Key

string

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.

Required string length: 1 - 255

Flow-Version

string<date>

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

Example:

"2026-11-01"

Path Parameters

conversation_id

string

required

The conversation's ID. A conversation ID, conv_ and a ULID.

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

Example:

"conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1"

Body

application/json

One turn from a simulated contact (test keys only).

content

object

required

What a simulated contact sends in one turn, as a message kind with kind (required): basic (text and/or media by file_id), voice (by file_id), location, contact_card, or button_reply (a tap on a reply button, or on a list row, of a message your app sent). Fields a contact cannot send (reply_to and metadata inside the kind, channel blocks, link_preview, url) and other kinds answer 400 invalid_request.

Option 1
Option 2
Option 3
Option 4
Option 5

Show child attributes

from

string

Simulated group conversations only, and required there. The participant who writes this turn (a contact in the conversation's group.participants); another contact answers 400 invalid_request with param from. Refused the same way on one-to-one conversations.

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

Example:

"ct_01JB8ZB2J4K6N8Q0S2V4W6Y8A0"

reply_to

string

A message of this conversation the contact replies to inline, on channels with inline replies (Telegram, WhatsApp, iMessage; on SMS it answers 400 invalid_request). The received message shows it in reply_to.

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

Example:

"msg_01JB8ZD4M6P8R0T2V4X6Z8B0C2"

Response

The turn was accepted; message.received follows.

A simulated turn Flow accepted. Its message.received event follows.

message

string

required

The ID the received message will have, in its message.received event and in the transcript.

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

Example:

"msg_01JB8ZD4M6P8R0T2V4X6Z8B0C2"

conversation

string

required

A conversation ID, conv_ and a ULID.

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

Example:

"conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1"

channel_message_id

string

required

The simulated channel's ID for the message (the received message's channel_message_id).

status

enum<string>

required

Always queued; the message is stored and delivered right after.

Available options:

queued

Get started

Observe

Test before you ship

Concepts

Channel guides

Agent frameworks

Compare

HTTP API

Write as the simulated contact

Authorizations

Headers

Path Parameters

Body

Response