Skip to main content
Every send, whether over HTTP, the live stream or a webhook reply, passes one send gate that applies the channel’s rules before anything leaves Flow; this page lists those rules.
TypeScript

​
Rule 1: is the conversation open?

On WhatsApp, conversation.window_open_until (on the conversation and on every event) says when the window closes. Subscribe to conversation.window_closing to hear about it 1 hour before.

​
Rule 2: starting a conversation spends budget

Writing to someone first (POST /v1/messages) spends the sender’s new-contact budget:
  • Per sender: a number of new contacts per day and per hour, in sender.limits.
  • Warm-up: a new sender that writes first starts with a small daily budget that grows day by day while it is warming_up.
  • WhatsApp (once available): also the number’s messaging tier (sender.limits.whatsapp_tier).
  • Telegram: a bot can write only to people who started it, so in practice its budget is not the limit.
  • iMessage: Flow’s lines are reply-only today, so writing first gets 403 permission.
When the budget is used up the send fails with 429 new_contact_limit and retry_after in seconds. A message to someone who already has an open conversation with that sender goes into it and spends nothing.

​
Rule 3: abuse protection

The gate watches for signs that a sender is being used for unwanted messages:
  • the same text going to many new contacts;
  • a high share of new conversations that get no reply;
  • people blocking the sender;
  • a drop in WhatsApp’s quality rating (once WhatsApp is available).
When one trips, the sender is throttled: until throttled_until, starting conversations fails with 429 sender_throttled, while replies into existing conversations still go. You receive sender.status_changed with a one-sentence reason, and another when the sender recovers by itself.

​
Rule 4: pacing and order

  • Each sender has a sending rate (pacing): only so many messages a second, from all your conversations together. A send over it is refused with 429 rate_limited and retry_after; wait that long and retry with the same idempotency key.
  • At most one message per conversation is in flight at a time, and messages go out in the order you sent them.

​
Write agents that respect the gate

  • Reply, don’t broadcast. Agents that answer people who wrote first never meet rules 2 and 3.
  • Check before you send. GET /v1/capabilities?conversation=conv_... returns window.open and what each content type would do.
  • Retry only what clears by itself. new_contact_limit, sender_throttled and rate_limited carry retry_after; outside_window will not clear until the person writes again, so wait for them to message the line (iMessage), or send a template instead (WhatsApp, once available).
  • Watch sender.status_changed. It is the early warning before a channel acts against a number.
  • Senders: statuses and limits.
  • Going live: templates and dedicated numbers.
  • Rate limits: request limits per API key, which are separate from the gate.