Skip to main content
POST
Request a dedicated sender

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 request for a dedicated sender.

channel
enum<string>
required

A messaging channel.

Available options:
telegram,
whatsapp,
imessage
display_name
string

The name contacts should see.

Maximum string length: 64
country
string

WhatsApp and iMessage. ISO 3166-1 alpha-2 country for the number, for example IN.

Pattern: ^[A-Z]{2}$
telegram_bot_token
string
write-only

Telegram only, and required there. The bot token from BotFather. Stored encrypted; never returned.

Maximum string length: 128
Pattern: ^[0-9]{1,20}:[A-Za-z0-9_-]{20,100}$

Response

The sender is connected and active (Telegram bots), or an already connected bot's token was updated in place.

What your agent talks from: a Telegram bot, a WhatsApp number or an iMessage line. shared senders are Flow's sandbox, used by many apps in test mode; dedicated senders are yours alone. Each sender has its own limits and warm-up state.

id
string
required

A sender ID, snd_ and a ULID.

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

"snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T"

channel
enum<string>
required

A messaging channel.

Available options:
telegram,
whatsapp,
imessage
kind
enum<string>
required

shared (the sandbox) or dedicated (yours).

Available options:
shared,
dedicated
livemode
boolean
required

false for sandbox senders, true for dedicated senders used in live mode.

status
enum<string>
required
  • pending: requested, being provisioned.
  • active: sending normally.
  • warming_up: active, with a new-contact budget that grows day by day.
  • throttled: the gate slowed it after an abuse signal; it recovers by itself.
  • flagged: the channel or Flow flagged it; starts are paused. A Telegram bot is also flagged when Telegram rejects its token (revoked in @BotFather): it then sends nothing, new sends answer 403 permission, and queued messages wait until you connect the bot again with its new token (POST /v1/senders). They wait at most 72 hours after Flow accepted them; older ones fail with outside_window (channel_code queued_too_long) in message.failed instead of going out late.
  • banned: it cannot send or receive: the channel banned it, you disconnected it (DELETE /v1/senders/{sender_id}), or its bot or line was connected to another app.
Available options:
pending,
active,
warming_up,
throttled,
flagged,
banned
address
object
required

How contacts reach the sender. Which fields are set depends on the channel.

limits
object
required

The sender's current budget for starting conversations.

created_at
string<date-time>
required

When the sender was created.

display_name
string

The name contacts see, where the channel shows one.

throttled_until
string<date-time>

With status throttled, when starts are allowed again. Recovery is automatic.

quality_rating
enum<string>

WhatsApp only. Meta's quality rating for the number.

Available options:
green,
yellow,
red,
unknown
join_code
string

Shared senders only. The whole message a contact sends to this sender to join your app: join , a space, then the app's sandbox_join_code (from GET /v1/app), for example join brave-otter-40718263. Show it to testers as is.

Example:

"join brave-otter-40718263"