Go live

export TELEGRAM_BOT_TOKEN=...   # the token from @BotFather; never commit it

curl https://api.flow.engineer/v0/senders \
  -H "Authorization: Bearer $FLOW_MESSAGING_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"channel\": \"telegram\", \"telegram_bot_token\": \"$TELEGRAM_BOT_TOKEN\"}"

​

Checklist

​

WhatsApp

​

Your own number

1. Create a Meta app of type Business with the WhatsApp product, and switch it to Live.
2. Add the phone number to your WhatsApp Business Account, with an approved display name, and add a payment method in WhatsApp Manager (Meta bills its fees to you directly).
3. Create a system user (Admin), assign it your WhatsApp Business Account (full control) and the app, and generate a token that never expires with whatsapp_business_messaging and whatsapp_business_management.

export WHATSAPP_ACCESS_TOKEN=...   # the system user token; never commit it
export WHATSAPP_APP_SECRET=...     # your Meta app's App secret

curl https://api.flow.engineer/v0/senders \
  -H "Authorization: Bearer $FLOW_MESSAGING_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"channel\": \"whatsapp\", \"whatsapp_phone_number_id\": \"106540352242922\", \"whatsapp_business_account_id\": \"102290129340398\", \"whatsapp_access_token\": \"$WHATSAPP_ACCESS_TOKEN\", \"whatsapp_app_secret\": \"$WHATSAPP_APP_SECRET\"}"

• Answer: 200 with the sender active and, only in this answer, setup: enter its callback_url and verify_token in your Meta app (App Dashboard > WhatsApp > Configuration) and subscribe the webhook_fields there, following its steps. Flow has already pointed this number’s webhooks at Flow (your other numbers keep theirs); the settings in your app make its field subscriptions apply. The verify token is shown only in this answer.
• New token: send the number again the same way. It stays the same sender, with the same verify token.
• Disconnect: DELETE /v0/senders/{sender_id} deletes the stored token and app secret and retires the sender. Nothing changes in your Meta app: remove Flow’s callback URL there yourself.
• Numbers the Flow team connected are updated and disconnected by the Flow team (403 permission with channel_code whatsapp_number_managed, and 501 not_implemented on DELETE).

​

Numbers, quality and fees

• Numbers: a number in your business’s own WhatsApp Business Account, or a number Flow provides.
• Quality and tiers: the sender shows WhatsApp’s quality_rating (green, yellow, red) and its messaging tier in limits.whatsapp_tier. Replies to people who wrote first are not limited by the tier.
• Fees: on a number Flow provides, WhatsApp’s own per-message fees (charged by Meta) are passed through. With your own WhatsApp Business Account, Meta bills its fees to your business directly, so add a payment method in WhatsApp Manager. See Pricing.

​

WhatsApp templates

curl https://api.flow.engineer/v0/templates \
  -H "Authorization: Bearer $FLOW_MESSAGING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "snd_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
    "name": "order_ready",
    "language": "en",
    "category": "utility",
    "components": [
      { "type": "body", "text": "Hi {{1}}, your {{2}} is ready for pickup.", "examples": ["Asha", "cake"] },
      { "type": "buttons", "buttons": [
        { "type": "url", "text": "See order", "url": "https://shop.example.com/orders/{{1}}", "example": "A-1042" }
      ] }
    ]
  }'

{
  "id": "tpl_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
  "sender": "snd_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
  "name": "order_ready",
  "language": "en",
  "category": "utility",
  "status": "pending",
  "components": [
    { "type": "body", "text": "Hi {{1}}, your {{2}} is ready for pickup.", "examples": ["Asha", "cake"] },
    { "type": "buttons", "buttons": [
      { "type": "url", "text": "See order", "url": "https://shop.example.com/orders/{{1}}", "example": "A-1042" }
    ] }
  ],
  "created_at": "2026-10-24T09:30:00Z"
}

• Always give samples. WhatsApp reviews a template with them. Put examples on the body and on a text header, one value per placeholder in order ({{1}} first), and example on a url button whose link ends in {{1}}: the end of the link, which Flow shows WhatsApp in place. Left out, Flow sends placeholder samples (x1, x2, …), which WhatsApp often rejects or moves to another category.
• Sample limits: exactly one per placeholder; 1 to 60 characters in a header and 1 to 1024 in a body; no line breaks, tabs or more than four spaces in a row. The url sample has no spaces, and the link with it in place is at most 2000 characters.
• Placeholders are numbered {{1}}, {{2}}, … with none skipped. A header has at most one, a footer none, and a url button’s link only {{1}}, at its end. A template that breaks these rules or the sample limits gets 400 invalid_request, and so do samples on a footer, a buttons part, a media header or text without placeholders.
• Names use lowercase letters, digits and underscores. A name and language pair is unique per sender.
• category is utility (updates about something the person asked for), marketing or authentication; it sets WhatsApp’s fee.
• You receive template.status_changed when WhatsApp approves, rejects (with rejection_reason) or pauses it.
• In the dashboard, open your WhatsApp number on the Senders page, then Templates: its New template form always sends its sample values.
• Send it with POST /v0/conversations/{conversation_id}/template (or start a conversation with POST /v0/messages and "kind": "template"), with values for its placeholders, the url button’s by its position (from 0):

{ "template_id": "tpl_01JB8ZC3K5M7P9R1T3V5X7Z9B1", "language": "en", "params": { "body": ["Asha", "cake"], "buttons": [{ "index": 0, "value": "A-1042" }] } }

​

iMessage: a dedicated line

• Get one: ask the Flow team for a line on the Dedicated plan (Pricing). They connect it to your app; it is listed in GET /v0/senders?channel=imessage with your live key. Flow’s shared line needs no setup: once your account has it (the free trial, kept on a paid plan), a live key sees it too, with your app’s live join message.
• The person writes first: starting a conversation with a new contact is refused with 403 permission, unless writing first is switched on for the line (imessage.can_initiate). Writing first is available on request for dedicated lines, within a warm-up.
• Add-ons on a dedicated line, arranged with the Flow team: SMS and RCS from the same number (for contacts who cannot get iMessage), and forwarding of phone calls. Group chats people add the line to reach your app as group conversations.
• Get people to write: the sender’s address.link is the line’s opt-in link (when it has one): it opens Messages with the line and a prefilled text. Publish it on your site, receipts or QR codes. See Build an iMessage agent.

​

Telegram: your own bot

• New token: after revoking a token in @BotFather, send the new one the same way. The bot stays the same sender; one Telegram rejected meanwhile is flagged until you do. Messages queued while it is flagged wait at most 72 hours, then fail with outside_window (channel_code queued_too_long).
• Disconnect: DELETE /v0/senders/{sender_id} removes the bot’s webhook and token and retires the sender.
• One app per bot: connecting a bot to another app moves it there and retires the old sender.

​

Before you launch

• Handle outside_window, new_contact_limit and sender_throttled (see Errors). Know the sending limits and abuse signals: the same first message to many new contacts throttles a sender for 24 hours.
• Deduplicate webhook deliveries on the event id, and use event IDs as idempotency keys.
• Subscribe your webhook only to the event types you use.
• Message content and media are kept for your plan’s retention period (30 days by default); store anything you need longer yourself.

​

Related

• Senders and Test and live mode
• API: Request a dedicated sender, Create a template