iMessage tapbacks, typing indicators and effects via API

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.

What an API can send

The things that make an iMessage conversation feel native are small: a typing bubble, a thumbs-up on a message, confetti on an order confirmation. A good iMessage API exposes them, and a good agent uses them sparingly.

Flow’s iMessage features cover what the line supports: text up to 9,999 characters, photos, video and audio, documents, voice notes, tapbacks, typing, read receipts and effects. There are no buttons, lists or templates. If you design an iMessage agent, these are the details that matter.

Tapbacks

Reactions become tapbacks. A reaction is any one emoji, and Flow sends it as written, never swapped for another one. Reactions are not available in groups. This example reacts and then replies:

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));
}

react() sends the reaction with no fallback. If the conversation does not take it, as in a group, the call answers 422 unsupported_content and nothing is sent.

Use a tapback to say “got it” while the agent works, not as decoration on every message.

Typing and read receipts

Show typing while the model works. On Flow:

• Typing shows for up to 60 seconds, and works for 5 minutes after your line’s last message to the contact, not in groups. Send a reply first. Outside that, the call answers 409 outside_window, and you can ignore it.
• Channels clear the indicator after a few seconds, so keep turning it on until you send.
• reply() does this for you: it turns typing on, sends bubbles as they are ready and turns it off, even if the stream fails.

Read receipts work for the whole conversation. iMessage has no per-message receipt, so up_to has no effect. Like typing, they work only for 5 minutes after your line’s last message to the contact, so mark the conversation read once your reply has gone.

On Flow, iMessage typing needs an existing conversation, works for 5 minutes after your line’s last message to the person (the person’s message alone does not open it), not in group chats, and is best-effort. It clears itself when your next message goes or after a few seconds, so call it again while your agent works.

Effects

Effects send text with an iMessage bubble or screen effect:

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

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

Flow lists these effects: slam, loud, gentle, invisible_ink, echo, spotlight, balloons, confetti, love, lasers, fireworks and celebration: 12 in all. Effects are iMessage only: on another channel the call answers 422 unsupported_content and nothing is sent, so send plain text there.

An effect is a moment, not a style. Use one for a confirmation, a birthday or a small win, and the rest of the time send plain text.

Edit and unsend

On Flow’s iMessage line:

• Edit. You can replace the text of a sent message within 15 minutes, but not the message that started the conversation.
• Unsend. You can remove a message within two minutes.

WhatsApp supports neither, so write the agent so a mistake can be corrected with a new message, not only with an edit. The one-agent guide has the table of what each channel can do.

Build expressive replies with Flow

Flow exposes reactions, typing, effects, edits and unsend through the same conversation API. Flow converts nothing: when a channel does not take a kind, it answers 422 unsupported_content with a hint, so your agent can send plain text instead.

Frequently asked questions

Keep reading

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