iMessage API Flow Framework
Put your agent where your customers already text. Build it with Flow Framework, or connect the one you have through the iMessage API.
Free trial: 25 people on the shared line, no card. See pricing
Today 9:41 AM
hey, can you fit a tune-up in this week?
Yes! Thursday at 10:00 or 14:00. Which works?
14:00 please
Read 9:42 AM
Booked: Thursday 14:00. See you then 🚲
Sent with ConfettiIllustration: Northside Bikes is made up, not a Flow customer.
Two ways to build
Flow Framework open source · TypeScript
Write your agent’s jobs once as typed tools.
$ npx @flow-engineer/flow new my-agent $ npx @flow-engineer/flow link --channel imessage $ npm start
iMessage API any language
Send and receive iMessage from the code you run today.
$ npm install @flow-engineer/messaging # or $ pip install flow-messaging
What it can do
Show typing while your agent works, and mark messages read.
React with tapbacks or any emoji.
Twelve effects, from confetti to invisible ink, plus text styles.
Both ways, with files scanned for malware.
On a dedicated line, your agent replies in groups people add it to.
People not on iMessage get SMS or RCS from the same number.
How it works
Start on Flow’s shared line, or get your own US number.
Customers text your line from their own phone.
Your agent gets each message and answers in the same chat.
Want your agent to text first? Add Outbound to a dedicated line, +$40/mo.
About OutboundThe API
One endpoint per kind of message: what you send is what the person gets.
agent.ts
import { FlowMessaging, contentText, effect } from "@flow-engineer/messaging"; const flow = new FlowMessaging(); // reads FLOW_MESSAGING_KEY // live events, no public URL needed (or use signed webhooks) for await (const event of flow.events.stream({ types: ["message.received"] })) { const chat = event.conversation; const text = contentText(event.data.message.content); if (chat.type !== "group") { await chat.react(event.data.message.id, "👍"); // a Like tapback } const { reply, booked } = await askMyAgent(text); // your agent, any model await chat.reply(reply); // typing, then iMessage-sized bubbles (or pass an LLM stream) if (booked) await chat.send(effect("You're booked!", "confetti")); }
app.py
from fastapi import FastAPI, Request, Response from flow_messaging import ( WebhookSignatureError, construct_event, content_text, webhook_reply, ) app = FastAPI() @app.post("/flow") async def flow_webhook(request: Request): raw = await request.body() # the raw body, before parsing try: # checks Flow-Signature with FLOW_MESSAGING_WEBHOOK_SECRET event = construct_event(raw, request.headers.get("Flow-Signature")) except WebhookSignatureError: return Response(status_code=400) if event.type == "message.received": text = content_text(event.data.message.content) return webhook_reply(ask_my_agent(text)) # sent as the reply return {}
terminal
# reply in the conversation (202: queued for the channel) curl https://api.flow.engineer/v0/conversations/$CONVERSATION_ID/basic \ -H "Authorization: Bearer $FLOW_MESSAGING_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"text": "Thursday 10:00 or 14:00?"}' # text with an iMessage effect curl https://api.flow.engineer/v0/conversations/$CONVERSATION_ID/effect \ -H "Authorization: Bearer $FLOW_MESSAGING_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"text": "Booked: Thursday 14:00", "effect": "confetti"}'
src/tools.ts · src/agent.ts
// src/tools.ts: what the agent can do, written once import { tool, z } from "@flow-engineer/flow"; export const tools = [ tool({ name: "book_tune_up", description: "Book a bike tune-up at the time the customer chose.", input: z.object({ day: z.string(), time: z.string() }), run: ({ day, time }, { idempotencyKey }) => shop.book({ day, time, idempotencyKey }), }), ]; // src/agent.ts: the same agent on iMessage, WhatsApp and Telegram import { createAgent } from "@flow-engineer/flow"; import { flowMessaging } from "@flow-engineer/flow/flow-messaging"; const fm = flowMessaging(); // reads FLOW_MESSAGING_KEY const agent = createAgent({ dir: "./agent", model, tools, channels: [fm.imessage(), fm.whatsapp(), fm.telegram()], }); await agent.resume(); fm.start(agent, { cursorFile: ".flow/flow-messaging-cursor" });
Flow Framework + Flow Cloud
$ npx @flow-engineer/flow test --synthetic $ npx @flow-engineer/flow deploy $ npx @flow-engineer/flow deploy promote
Pricing
Each person counts once a day and once a month, however many messages you exchange.
$0
Try your agent on iMessage today.
Start freeWas $30 now $25 /mo
Your agent on our shared line.
Get started$100$140 /mo
Your agent on its own US number.
Get started Get startedNo per-message fees. Separate from Cloud plans. All pricing questions
Apple has no public iMessage API. Apple Messages for Business is a separate channel run by Apple-approved providers, and Flow is not one of them. Flow gives your agent a real iMessage line that your code reaches through an API.
No. Flow runs the line and your agent calls an API. Test with simulated conversations, or text the line from any iPhone or Mac.
Only on a dedicated line with the Outbound add-on ($40 a month): 2 new conversations a day at first, 40 a day from day 22. Otherwise people text first. Message only people who gave you their number.
iMessage has no 24-hour window: once someone has texted your line, your agent can message them any time. The only timing rule is that typing indicators and read receipts work for 5 minutes after your line’s last message to that person. The person writes first, unless a dedicated line has the Outbound add-on.
They get SMS or RCS from the same number, on every plan. Effects and text styles do not show there.
Yes, on a dedicated line through the iMessage API, in groups people add it to. It cannot create, rename or manage groups, and groups have no tapbacks, typing or read receipts. The shared line and Flow Framework agents do not answer in groups.
Once the person has written, both work for 5 minutes after your line’s last message to them. Not in group chats.
No. The iMessage API works from any language, with SDKs on npm (@flow-engineer/messaging) and PyPI (flow-messaging). Flow Framework is the open-source way to build the agent itself.
Free for 25 people on the shared line, ever. Shared is $25 a month (launch discount: $5 off $30), for 300 people a month and 200 a day. Dedicated is $100 a month for your own US number and 1,000 people a day (250 a day at first, ramping over 14 days). Outbound adds $40 a month. No per-message fees.
Guides
Start free on the shared line. The same code runs on your own number.
