Senders: the shared sandbox and dedicated numbers, bots and lines

A sender is what your agent talks from: a Telegram bot or an iMessage line (and a WhatsApp number once WhatsApp is available). Flow hosts every sender, so you never manage channel credentials.

Channel	Shared sandbox (test key)	Dedicated (live key)
Telegram	Flow’s sandbox bot	Your own bot: connect its token with `POST /v1/senders`
iMessage	None	A line the Flow team connects to your app; replies only
WhatsApp	Not available yet	Not available yet (waiting on Meta’s approval)

curl https://api.flow.engineer/v1/senders \
  -H "Authorization: Bearer $FLOW_MESSAGING_KEY"

{
  "data": [
    {
      "id": "snd_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
      "channel": "telegram",
      "kind": "shared",
      "livemode": false,
      "status": "active",
      "address": { "username": "flow_sandbox_bot", "link": "https://t.me/flow_sandbox_bot?start=wild-otter-04508705" },
      "join_code": "join wild-otter-04508705",
      "limits": { "new_contacts_per_day": 50, "new_contacts_per_hour": 10 },
      "created_at": "2026-11-01T09:00:00Z"
    }
  ],
  "has_more": false
}

address.link opens a chat with the sender: https://t.me/... for a Telegram bot (and https://wa.me/... for a WhatsApp number, once available). On the Telegram sandbox bot the link carries your join code (https://t.me/<bot>?start=<code>), so opening it and tapping Start joins your app. For an iMessage line it is the line’s opt-in link, which opens Messages with the line and a prefilled text the person sends to start the conversation; it is set only when the line has one configured.

Two kinds of sender

	Shared (sandbox)	Dedicated
Who uses it	Many apps, in test mode	Your app only, in live mode
Key	`fk_test_...`	`fk_live_...`
Who it can talk to	Only people who sent your app’s join code	Anyone the channel’s rules allow
Name people see	Flow’s sandbox name	Your brand
How you get it	Already there	Telegram: `POST /v1/senders` with your bot’s token. iMessage: ask the Flow team. See Going live

The sandbox and join codes

A shared sender serves many apps at once. A person joins your app by sending its join code, such as join wild-otter-04508705, to the sandbox sender. On Telegram, opening the sender’s address.link and tapping Start does the same; typing join <code> is the fallback when the link can’t be used. From then on their messages reach your app, and your app can message them.

A join code is two words and eight digits. Your app’s code is sandbox_join_code in GET /v1/app (the bare code, for example wild-otter-04508705); each shared sender shows what a person sends as join_code (join wild-otter-04508705).
A join starts a conversation and sends you conversation.started with via: "sandbox_join".
Your test key cannot message anyone who has not joined. That is what keeps the sandbox safe for everyone.

Status and limits

Each sender has its own status and budget for starting conversations:

`status`	Meaning
`pending`	Requested; Flow is provisioning it (for senders Flow provisions, such as WhatsApp numbers once available).
`active`	Sending normally.
`warming_up`	Active, with a new-contact budget that grows day by day.
`throttled`	Slowed after an abuse signal; recovers by itself at `throttled_until`. Replies still go.
`flagged`	Flagged by the channel or by Flow; starting conversations is paused. A Telegram bot whose token Telegram rejected is `flagged` and holds its queued messages until you send the new token (`POST /v1/senders`); held messages fail with `outside_window` (`channel_code` `queued_too_long`) after 72 hours.
`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.

limits.new_contacts_per_day and limits.new_contacts_per_hour are the sender’s current budget for starting conversations; WhatsApp senders (once available) also show quality_rating and limits.whatsapp_tier. Every change arrives as a sender.status_changed event. The rules behind them are on The send gate.

Get started

Concepts

Channel guides

Agent frameworks

Compare

Senders: the shared sandbox and dedicated numbers, bots and lines

Two kinds of sender

The sandbox and join codes

Status and limits

​Two kinds of sender

​The sandbox and join codes

​Status and limits

​Related

Two kinds of sender

The sandbox and join codes

Status and limits

Related