One agent on iMessage, WhatsApp and Telegram

Building on the iMessage API? Build on iMessage with Flow: one agent for iMessage, WhatsApp and Telegram. New to it? Read the iMessage API guide.

One handler, three channels

The promise of a unified messaging layer is that the code that answers a customer does not care where the customer is. This is the whole loop on Flow, from the quickstart:

import { FlowMessaging, contentText } from "@flow-engineer/messaging";

const flow = new FlowMessaging();
for await (const event of flow.events.stream({ types: ["message.received"] })) {
  const said = contentText(event.data.message.content);
  await event.conversation.reply("You said: " + said, { idempotencyKey: event.id });
}

The same loop receives a message from a Telegram bot, a WhatsApp number or an iMessage line, and replies into the same conversation. event.conversation.channel tells you which one if you want to change the tone.

The differences are not in the code. They are in the rules each channel enforces, and a messaging layer should apply them for you so a refused send comes back as a clear error.

Who can write first

This is from Flow’s sending rules and its iMessage plans. The practical lesson is the same on all three: agents that reply to people who wrote first rarely meet these rules. Agents that broadcast do.

Flow keeps the channel rules at the messaging boundary: customers text the shared iMessage line first, while writing first comes with the $40 a month Outbound add-on on a dedicated line, and the conversations it starts ramp from 2 a day to 40 a day over 21 days. Your agent logic stays the same across channels.

What each channel can show

From Flow’s content types docs:

Nothing is converted. What you send is what the person gets: a kind or field the channel does not take fails with 422 unsupported_content and nothing is sent. Its param names what was refused and its hint says what to send instead, so choosing the substitute is your code’s job:

import { buttons, UnsupportedContentError } from "@flow-engineer/messaging";

try {
  await event.conversation.send(buttons("When should we deliver?", ["Today", "Tomorrow"]), { idempotencyKey: `${event.id}:when` });
} catch (err) {
  if (!(err instanceof UnsupportedContentError)) throw err;
  // iMessage has no buttons: ask in words instead, with a new idempotency key
  await event.conversation.send("When should we deliver: today or tomorrow?", { idempotencyKey: `${event.id}:when:basic` });
}

The 422 is kept under its idempotency key like any answer, so the substitute needs a new key: the refused one plus what it is.

Know before you send

You do not have to memorise the table. Each endpoint’s page in Flow’s API reference opens with the channels it works on and their limits, and the content types page has them all in one table. Branch on event.conversation.channel to choose content before sending, and handle unsupported_content and outside_window for what slips through.

For retries, send an Idempotency-Key with every POST. Retry only what clears by itself: rate_limited and sender_throttled carry a retry_after, and outside_window will not clear until the person writes again.

One person, many channels

Customers do not think in channels. The same person may text on iMessage and message on WhatsApp. Joining those identities is a security decision, so do it deliberately.

Flow’s framework docs say phone numbers on SMS and WhatsApp are normalised to E.164, so +1 555 555 0123 and 15555550123 identify the same phone. For other interfaces you supply a resolve function that maps the verified channel identity to your own account key. Flow does not guess that an app user and a phone number are the same account.

An iMessage handle can be a phone number or an email address, so do not assume a number. Never link identities by a matching display name.

Where this fits with Flow

Flow is the framework and messaging API this post is based on. You write your product’s tools once in TypeScript and the same agent answers on iMessage, WhatsApp and Telegram, and works as an MCP server and CLI for ChatGPT, Claude and coding agents. iMessage starts with a free trial on the shared line for 25 people, a $25 a month shared line for 300 people a month and 200 a day, and a $100 a month dedicated line. See iMessage API pricing.

For Flow’s iMessage plans and limits, see Flow on iMessage: features, pricing and limits. For the full agent design, read Build an iMessage AI agent, or start with a test key on the Telegram sandbox.

Frequently asked questions

Keep reading

All posts: the Flow blog. The Flow docs have the reference.