curl --request POST \
  --url https://api.flow.engineer/v0/test/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "channel": "sms"
}
'

{
  "id": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
  "app": "app_01JB8Z0A1C3E5G7J9K1M3P5R7T",
  "channel": "telegram",
  "sender": "snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T",
  "livemode": true,
  "opted_in": true,
  "created_at": "2023-11-07T05:31:56Z",
  "type": "direct",
  "contact": "ct_01JB8ZB2J4K6N8Q0S2V4W6Y8A0",
  "group": {
    "participants": [
      {
        "contact": "ct_01JB8ZB2J4K6N8Q0S2V4W6Y8A0",
        "address": {
          "phone": "<string>",
          "username": "<string>",
          "telegram_user_id": "<string>",
          "handle": "<string>"
        },
        "name": "<string>"
      }
    ],
    "name": "<string>"
  },
  "last_inbound_at": "2023-11-07T05:31:56Z",
  "window_open_until": "2023-11-07T05:31:56Z",
  "simulated": true,
  "metadata": {}
}

{
  "id": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
  "app": "app_01JB8Z0A1C3E5G7J9K1M3P5R7T",
  "channel": "telegram",
  "sender": "snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T",
  "livemode": true,
  "opted_in": true,
  "created_at": "2023-11-07T05:31:56Z",
  "type": "direct",
  "contact": "ct_01JB8ZB2J4K6N8Q0S2V4W6Y8A0",
  "group": {
    "participants": [
      {
        "contact": "ct_01JB8ZB2J4K6N8Q0S2V4W6Y8A0",
        "address": {
          "phone": "<string>",
          "username": "<string>",
          "telegram_user_id": "<string>",
          "handle": "<string>"
        },
        "name": "<string>"
      }
    ],
    "name": "<string>"
  },
  "last_inbound_at": "2023-11-07T05:31:56Z",
  "window_open_until": "2023-11-07T05:31:56Z",
  "simulated": true,
  "metadata": {}
}

{
  "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": "channel",
    "channel_code": "hipaa_channel_not_covered"
  }
}

{
  "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": "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

Create a simulated conversation

Test keys only. Creates a conversation with a simulated contact, an end user that exists only inside Flow, so an agent or a test suite can play the person’s side with no phone and no real channel. Write as the contact with POST /v0/test/conversations/{conversation_id}/inbound; your agent receives each turn exactly like a real message.received and replies with its normal send. Read both sides with GET /v0/test/conversations/{conversation_id}/transcript.

The conversation is on your app’s simulated sender for the channel (kind simulated), which Flow creates on first use. It never touches a network: sends to the simulated contact pass the real send gate and end sent. Simulated channels: telegram, whatsapp, imessage and sms. The channel’s rules hold as on a real sender: a simulated iMessage line, like Flow’s lines today, only replies, so the contact writes first; a simulated Telegram bot, like a real one, cannot write to a contact who has not written to it, so a send before the contact’s first turn is accepted (202) and then fails as it does on real Telegram (message.failed, channel_error, channel_code 403); on SMS and iMessage a buttons message answers 422 unsupported_content, as on a real line.

On WhatsApp, the contact’s turns go through the real WhatsApp inbound path, so each turn opens the 24-hour window. Outside it, including before the contact’s first turn, only a template can be sent (409 outside_window). Buttons take up to 3 reply buttons (a list up to 10 rows); reactions and reply_to work; edits and unsends answer 422 unsupported_content.

On SMS, the rules that concern the contact hold too. Before the contact’s first turn, a send to them is a start that needs their recorded consent: without consent (on POST /v0/messages with to.contact), it answers 403 permission with channel_code consent_required, as a real SMS start does. A turn with the text STOP opts the contact out and START lifts it (see POST /v0/test/conversations/{conversation_id}/inbound). A simulated SMS sender keeps no quiet hours, so a test’s outcome never depends on the time of day, and it sends media and voice as MMS.

Creating the conversation sends no event. The conversation starts with its first message: the contact’s first turn (via inbound), or your first send to the contact, such as a WhatsApp template or an SMS send with consent (via outbound). conversation.started comes before that message’s message.received or message.sent.

On iMessage, group makes a simulated group conversation instead (type group, with the participants as simulated contacts), so you can test how your agent handles groups: each turn names its writer in from, and the gate applies the group rules (reactions refused with channel_code group_unsupported, as are typing and read receipts). Each call with group makes a new group.

Give contact to choose the simulated contact’s address; giving an address that already has a simulated conversation returns that conversation (200). Without contact, Flow makes a new contact with a made-up address (phone numbers start +1555), so each call is a fresh conversation, for example one per test case. Simulated contacts never match real ones, even with the same address.

Simulated traffic is free: it does not count against the sandbox allowance. An app has at most 500 simulated conversations: past that, a new one answers 403 permission with channel_code simulated_conversation_limit (an address that has one still returns it with 200), so reuse conversations across test runs. The /v0/test/ endpoints take at most 120 requests a minute per key (429 rate_limited), on top of the plan’s request rate limit. A live key answers 403 permission with channel_code test_mode_only.

A HIPAA account (Account.hipaa) can simulate only the channels its business associate agreement covers (SMS), as it can connect senders only there: telegram, whatsapp or imessage answers 403 permission with channel_code hipaa_channel_not_covered (param channel).

POST

test

conversations

curl --request POST \
  --url https://api.flow.engineer/v0/test/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "channel": "sms"
}
'

{
  "id": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
  "app": "app_01JB8Z0A1C3E5G7J9K1M3P5R7T",
  "channel": "telegram",
  "sender": "snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T",
  "livemode": true,
  "opted_in": true,
  "created_at": "2023-11-07T05:31:56Z",
  "type": "direct",
  "contact": "ct_01JB8ZB2J4K6N8Q0S2V4W6Y8A0",
  "group": {
    "participants": [
      {
        "contact": "ct_01JB8ZB2J4K6N8Q0S2V4W6Y8A0",
        "address": {
          "phone": "<string>",
          "username": "<string>",
          "telegram_user_id": "<string>",
          "handle": "<string>"
        },
        "name": "<string>"
      }
    ],
    "name": "<string>"
  },
  "last_inbound_at": "2023-11-07T05:31:56Z",
  "window_open_until": "2023-11-07T05:31:56Z",
  "simulated": true,
  "metadata": {}
}

{
  "id": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
  "app": "app_01JB8Z0A1C3E5G7J9K1M3P5R7T",
  "channel": "telegram",
  "sender": "snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T",
  "livemode": true,
  "opted_in": true,
  "created_at": "2023-11-07T05:31:56Z",
  "type": "direct",
  "contact": "ct_01JB8ZB2J4K6N8Q0S2V4W6Y8A0",
  "group": {
    "participants": [
      {
        "contact": "ct_01JB8ZB2J4K6N8Q0S2V4W6Y8A0",
        "address": {
          "phone": "<string>",
          "username": "<string>",
          "telegram_user_id": "<string>",
          "handle": "<string>"
        },
        "name": "<string>"
      }
    ],
    "name": "<string>"
  },
  "last_inbound_at": "2023-11-07T05:31:56Z",
  "window_open_until": "2023-11-07T05:31:56Z",
  "simulated": true,
  "metadata": {}
}

{
  "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": "channel",
    "channel_code": "hipaa_channel_not_covered"
  }
}

{
  "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": "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"

Body

application/json

A simulated conversation to create (test keys only).

channel

enum<string>

required

The channel to simulate. telegram, whatsapp, imessage or sms.

Available options:

telegram,

whatsapp,

imessage,

sms

contact

object

The simulated contact's address on the channel. Give one field that fits the channel: phone on SMS, iMessage and WhatsApp, handle on iMessage, telegram_user_id on Telegram. Omit contact to get a new contact with a made-up address.

Show child attributes

name

string

The simulated contact's display name, as a channel would report it. Not with group.

Required string length: 1 - 64

group

object

imessage only: make a simulated group conversation (type group) instead of a one-to-one one, with these participants. Not with contact or name. Each turn names the participant who writes (from on POST /v0/test/conversations/{conversation_id}/inbound). Another channel answers 400 invalid_request with param group.

Show child attributes

Response

The contact's simulated conversation already existed; it is returned as is.

One sender talking with one contact (type direct), or with an iMessage group chat (type group). Holds the window state and whether the contact opted in.

string

required

A conversation ID, conv_ and a ULID.

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

Example:

"conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1"

app

string

required

An app ID, app_ and a ULID.

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

Example:

"app_01JB8Z0A1C3E5G7J9K1M3P5R7T"

channel

enum<string>

required

A messaging channel. sms is US SMS and MMS (in pilot), from dedicated numbers only.

Available options:

telegram,

whatsapp,

imessage,

sms

sender

string

required

A sender ID, snd_ and a ULID.

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

Example:

"snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T"

livemode

boolean

required

Whether the conversation belongs to live mode.

opted_in

boolean

required

Whether the contact has agreed to receive messages (wrote first, joined the sandbox, or you recorded consent). Always true on group conversations, which begin with the group writing.

created_at

string<date-time>

required

When the conversation began.

type

enum<string>

default:direct

Flow always sends it; read a missing one as direct (answers from before groups existed). direct: one sender and one contact (every channel). group: a group chat one of your dedicated iMessage lines was added to; it has group and no contact. Flow's shared iMessage line ignores group chats, so they never reach your app from it.

Available options:

direct,

group

contact

string

The contact the conversation is with. Always set when type is direct; absent on group conversations (each message's from says who wrote).

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

Example:

"ct_01JB8ZB2J4K6N8Q0S2V4W6Y8A0"

group

object

read-only

Group conversations only (iMessage): the group chat as Flow saw it last. People who join or leave change participants without an event; Flow updates the list when the group next writes. The channel's own group ID is never exposed: use the conversation's ID.

Show child attributes

last_inbound_at

string<date-time>

When the contact last wrote. Absent if they never have.

window_open_until

string<date-time>

WhatsApp only. Until when free-form messages may be sent; after it, only templates. Absent when the window is closed or the channel has none.

simulated

boolean

read-only

true for a simulated conversation, whose contact exists only inside Flow (test mode only, from POST /v0/test/conversations); absent otherwise.

metadata

object

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

Show child attributes

Get started

Observe

Test before you ship

Concepts

Channel guides

Agent frameworks

Compare

HTTP API

Create a simulated conversation

Authorizations

Headers

Body

Response