iMessage

// 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);
  if (event.conversation.type !== "group") {
    await event.conversation.react(event.data.message.id, "👍"); // shows as the Like tapback; groups take no reactions
  }
  await event.conversation.reply(await askMyAgent(text));
}

​

1. Get a line

​

2. Bubbles fit iMessage

​

3. Tapbacks and effects

• Reactions (POST .../reaction): ❤️ 👍 👎 😂 ‼️ ❓ show as tapbacks, and any other emoji as an emoji reaction. Groups take none (422 unsupported_content, channel_code group_unsupported).
• Effects (POST .../effect) send text with an iMessage effect:

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

await event.conversation.send(effect("Your order is confirmed!", "confetti"));

​

4. No buttons: list the choices in the text

await event.conversation.send("Which time works, 10:00 or 14:00?", { idempotencyKey: `${event.id}:time` });

​

5. Who writes first

• The person writes first. A line replies only, unless writing first is switched on for it (imessage.can_initiate). From a reply-only line, starting a conversation with a new contact (POST /v0/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.
• Writing first is available on request, for dedicated lines only. The Flow team switches it on per line, within a warm-up: the line’s new-contact budget (limits) starts small and grows. If the channel still refuses a start, the send ends in message.failed with outside_window. The shared line never writes first.
• 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. SMS and RCS from the same number

​

7. Group chats

• A group is one conversation with type group. It has no contact; group holds the group’s name, when it has one, and its participants (each a contact on the channel, made the first time Flow sees them). Every inbound message carries from, the contact who wrote it.
• People who join or leave change the list without an event. Read the conversation (GET /v0/conversations/{conversation_id}) for the current list; events inline only group_name.
• Writers count toward your plan’s people; members who never write do not. A writer past a limit is held: their messages wait and arrive when they are let in, and the rest of the group’s messages are not held up. See Pricing.
• Reply with the normal sends (POST /v0/conversations/{conversation_id}/basic and the other kinds’ endpoints): basic messages (with imessage.styles, imessage.subject and link_preview), media, voice notes, effects, threaded replies (reply_to), edits and unsends work in groups.
• No reactions, typing or read receipts from your line. Each answers 422 unsupported_content with param kind and channel_code group_unsupported, and nothing is sent: leave them out in groups.
• Flow cannot create a group, rename one, or add or remove people. A start (POST /v0/messages) always makes a direct conversation.

​

8. Calls

• Phone calls to a dedicated line’s number can be forwarded to a phone you choose, set up with the Flow team with the SMS/RCS add-on (imessage.call_forwarding.phone shows where). Forwarded calls send no event. The shared line does not forward calls.
• FaceTime calls are never forwarded: the line cannot answer them, and each attempt arrives as a call.received event (data.call.contact, data.call.network facetime) in the direct conversation with the caller, made if it is new. A webhook endpoint receives it only when it lists call.received in events.
• A call is not a message: it does not count toward your plan’s people, and it does not let a reply-only line write to the caller first.

​

9. Text styles, subjects and link previews

await flow.messages.basic(event.conversation.id, {
  text: "Your order is on its way. Track it: https://example.com/t/4821",
  imessage: { subject: "Order 4821", styles: [{ start: 14, length: 10, style: "big" }] },
  link_preview: false,
});

​

10. What iMessage supports

​

11. Contacts

​

Related

• Going live: live keys and iMessage lines.
• Pricing: plans and how many people each reaches.
• Content types