Developer guideiMessage API8 min read
iMessage API glossary
A plain Flow iMessage API glossary: tapback, A2P 10DLC, reply window, idempotency key, send gate, MCP and more, each defined briefly.
The short answer
Flow gives you one messaging layer, but iMessage still has its own rules. This glossary explains the terms that matter to your agent, from tapbacks and fallback to reply windows, idempotency keys and send gates.
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.
Messaging terms
iMessage
Apple’s messaging service between Apple devices. It brings blue bubbles, tapbacks, typing indicators, read receipts, effects and rich media. Apple has no public server API for it, so you reach it through a third-party provider. See the iMessage API guide.
Blue bubble and green bubble
An iMessage shows as a blue bubble on an iPhone. An SMS shows as green. The difference is the service the message used.
Tapback
A quick reaction to a message, such as a like or a laugh, chosen from a fixed set. Through an API, a reaction maps to the closest tapback. See tapbacks, typing and effects.
Typing indicator
The “…” bubble that shows someone is writing. On Flow it works within five minutes of the contact’s last message, and channels clear it after a few seconds.
Read receipt
A signal that messages were read. On iMessage there is no per-message receipt through Flow, so the whole conversation is marked read.
Message effect
A bubble or screen effect on a message, such as confetti or balloons. Which effects a line can send may vary.
Group chat
A conversation with more than two people. Support varies by provider and plan. See iMessage group chats via API.
Reply window
The period in which you may send free-form messages after the contact writes. On WhatsApp it is 24 hours. On Flow’s iMessage line, the contact must have written to the line before.
Reply-only line
A line that can answer people who wrote to it but cannot start conversations. A Flow shared iMessage line works this way; dedicated lines can support writing first subject to availability and warm-up limits.
Opt-in link
A link that opens Messages with your line and a prefilled text, so a customer can start the conversation in one tap. See opt-in links and QR codes.
Fallback
Sending on another channel, or in another form, when the first is not possible. SMS or RCS fallback sends a message another way when iMessage is not available. Content fallback, such as numbered text for buttons, adapts what a channel cannot show.
Apple and carrier terms
Apple Messages for Business
Apple’s official business messaging channel. Customers start the chat from an Apple entry point, and automation must connect through an Apple-approved provider. See Apple Messages for Business vs iMessage API.
MSP (Messaging Service Provider)
A provider approved by Apple to connect businesses to Apple Messages for Business. Apple’s FAQ says automation and virtual agents must connect through one.
SMS and MMS
The carrier text message and its media version. They reach almost any phone but have tight size limits.
RCS
The carrier-backed upgrade to SMS, with richer content on supported phones and networks. Flow can use RCS as fallback from the same number when the customer cannot receive iMessage.
A2P 10DLC
Application-to-person messaging over 10-digit long codes. In the US, anyone sending SMS or MMS from a 10-digit number to US recipients must follow the applicable registration rules.
E.164
The international format for phone numbers, such as +15550100100. Flow normalises SMS and WhatsApp numbers to it.
Opt-out
A person’s request to stop receiving messages, such as the text STOP. Honour it at once and keep a record.
API terms
Webhook
An HTTPS request a provider sends to your server when something happens, such as a new message. See iMessage webhooks.
Signature
A value, computed from the request body and a secret, that proves a webhook came from the provider. Flow uses HMAC-SHA256 in a Flow-Signature header.
Idempotency key
A unique string sent with a request so that repeating it does not repeat the action. See idempotency keys.
Event log
The ordered record of events, such as messages and delivery updates, that webhooks, streams and polling all read from. Flow keeps it for 30 days by default.
Live stream
A WebSocket that pushes events as they happen. It needs no public URL, which makes it handy for development.
Test key and live key
A test key works in a sandbox with small limits, and a live key sends from real senders. On Flow they are fk_test_... and fk_live_....
Sandbox
A shared test environment. Flow’s self-serve sandbox runs on Telegram, and simulated contacts let you test agent logic without a phone.
Sender (line)
The bot, number or line your agent sends from. On Flow, an iMessage line is a US number, shared or dedicated.
Send gate
The set of rules Flow applies to every send: reply windows, new-contact budgets, abuse protection and pacing. See rate limits and sending rules.
Pacing
A limit on how many messages a sender may send a second. A send over it is refused with a 429.
Agent terms
Tool
A typed action your agent can call, such as looking up an order. In Flow Framework you write a tool once and use it from MCP, a CLI and your messaging agent.
MCP (Model Context Protocol)
A standard way for AI assistants to use a product’s tools. See iMessage MCP server.
Simulated contact
A test user that exists only inside Flow, so a test can play the person’s side with no phone. See testing without a phone.
Streaming reply
Sending a model’s answer as natural chat bubbles while it is still being written, with typing on. See Build an iMessage AI agent.
Frequently asked questions
What is an iMessage API?
A third-party service that lets your server send and receive iMessages through REST calls and webhooks. Apple has no public iMessage API for servers, so every such API is run by a provider.
What is the difference between iMessage, SMS and RCS?
iMessage is Apple's service between Apple devices. SMS is the carrier text message. RCS is the carrier-backed upgrade to SMS with richer content on supported phones and networks.
What does A2P 10DLC mean?
Application-to-person messaging over 10-digit long codes. In the US, anyone sending SMS or MMS from a 10-digit number to US recipients must follow the applicable registration rules.
What is a tapback?
A quick reaction to a message in iMessage, such as a like or a laugh, chosen from a fixed set.
What is an idempotency key?
A unique string sent with a request so that repeating the request does not repeat the action.
What is MCP?
The Model Context Protocol, a standard way for AI assistants to use a product's tools. A messaging MCP server lets a coding agent send test messages, and your own product can be served as an MCP server for Claude and ChatGPT.
Keep reading
All posts: the Flow blog. The Flow docs have the reference.
From reading to building
Your agent, on iMessage and everywhere else.
Flow gives your agent an iMessage line, and the same code answers on WhatsApp and Telegram and works as an MCP server and CLI. See how it works on iMessage.
Build on iMessage with Flow