Build an iMessage AI agent with the Flow Messaging API

// npm install @flow-engineer/messaging
import { FlowMessaging, contentText } from "@flow-engineer/messaging";
import { askMyAgent } from "./agent"; // returns a string, or any LLM stream

const flow = new FlowMessaging();

for await (const event of flow.events.stream({ types: ["message.received"] })) {
  const text = contentText(event.data.message.content);
  await event.conversation.react(event.data.message.id, "👍"); // shows as the Like tapback
  await event.conversation.reply(await askMyAgent(text));
}

​

1. Get a line

1. Sign in to the dashboard with GitHub and make a live key (fk_live_...) on the Keys page. See Going live.
2. Ask the Flow team to connect an iMessage line to your app. iMessage lines are not self-serve: POST /v1/senders with "channel": "imessage" answers 501 not_implemented.
3. With the live key, GET /v1/senders?channel=imessage lists the line. Its address.link, when set, is the line’s opt-in link: it opens Messages with the line and a prefilled text the person sends to start.
4. Run the code above, text the line from an iPhone or Mac, and your agent answers.

​

2. Bubbles fit iMessage

​

3. Tapbacks and effects

• Reactions become tapbacks. iMessage has a fixed set, so with fallback: "auto" (which react() sets) Flow uses the closest tapback, or skips the reaction and says so in delivered_as.
• Effects send text with an iMessage effect:

import { effect } from "@flow-engineer/messaging";

await event.conversation.send({ content: effect("Your order is confirmed!", "confetti"), fallback: "auto" });

​

4. No buttons: use the fallback

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

await event.conversation.send({
  content: buttons("Which time works?", [{ id: "t10", label: "10:00" }, { id: "t14", label: "14:00" }]),
  fallback: "auto",
});

​

5. Replies only

• The person writes first. Flow’s iMessage lines are reply-only: starting a conversation with a new contact (POST /v1/messages) is refused with 403 permission. Someone who has written to the line before is an open conversation, and replies to them are not budgeted.
• Get people to write with the opt-in link. When the line has one, the sender’s address.link opens Messages with the line and a prefilled text the person sends to start. Put it on your site, receipts or a QR code.
• No cold outreach. Sending the same text to many people, or messages that get no reply, can throttle the line (sender_throttled).

​

6. What iMessage supports

​

7. Contacts

​

Related

• Going live: live keys and iMessage lines.
• Content types