Products

Flow FrameworkOpen-source, one codebase for every chat Unified APIiMessage, WhatsApp and Telegram Flow CloudHosting, tests and observability

Ships to

WhatsAppiMessageTelegramChatGPTClaudeMuseInstinctMCPCLI
PricingBlogDocs GitHub

Build an agentiMessage API7 min read

iMessage API for coding agents

Let Claude Code, Cursor or Codex add Flow messaging to your agent. Give it a test key with no account, one prompt and a workflow it can verify end to end.

By FlowPublished Updated

The short answer

Give your coding agent one Flow prompt and one docs link. It can get a test key with no account, write the reply handler and verify the loop end to end in the sandbox, while you remain in control of the MCP server, sign-in and iMessage line.

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 works today

Coding agents are now a normal way to wire up an integration. Flow’s Build with a coding agent page is written for them, and it starts with what exists today:

  • Telegram is live: the shared sandbox bot with a test key, and your own bot with a live key.
  • iMessage is live on shared and dedicated US numbers. Customers text the line first by default, and a dedicated line with the outbound add-on can write first. The self-serve test key’s sandbox is Telegram.
  • WhatsApp is live on a number in your own WhatsApp Business Account. The shared WhatsApp sandbox is not open yet.
  • SMS (US) is in pilot only, on numbers the Flow team registers.

The code does not change per channel, so the agent builds and tests on Telegram, and the same handler answers on iMessage later. The iMessage API guide explains why iMessage has these rules.

The prompt

You can give your coding agent a short instruction. This is the one from Flow’s docs, shortened:

Add two-way Telegram messaging (and iMessage replies, if the Flow team has connected a line) to my AI agent using Flow Messaging. Follow https://docs.flow.engineer/unified-messaging-api/coding-agents.md exactly: use FLOW_MESSAGING_KEY if it is set, otherwise get a test key yourself with npx @flow-engineer/messaging init, use the TypeScript SDK @flow-engineer/messaging (or the HTTP API in other languages), receive message.received events, reply with my agent’s answer through event.conversation.reply(...), and verify it end to end in the sandbox before you finish.

The point is the docs link. The agent reads a page designed for it, with exact commands and checks, instead of guessing from training data.

What the agent does

  1. Gets a key. If FLOW_MESSAGING_KEY is set, it uses it. If not, npx @flow-engineer/messaging init creates a test key with no account, writes FLOW_MESSAGING_KEY and a claim token to .env, adds .env to .gitignore, and prints the sandbox link and join code.
  2. Installs the SDK. npm install @flow-engineer/messaging for TypeScript, or pip install flow-messaging for Python 3.10 or later.
  3. Writes the handler. It receives message.received events and replies with your agent’s answer.
  4. Verifies it. It sends a real test message in the sandbox, waits for the reply and checks the result. The docs tell it to wait for message.sent or message.failed, not message.delivered, because Telegram never sends that one.

The test key allows one contact and 50 messages on the Telegram sandbox and expires after seven days. Signing in with a Flow account keeps the app and gives three contacts and 100 messages each.

A minimal handler it might write is the one in Send iMessage programmatically. For frameworks, it can follow the Vercel AI SDK, OpenAI Agents SDK, Claude Agent SDK or LangChain posts.

What stays with you

Flow’s docs set clear limits on what the agent decides:

  • The MCP server is your call. The hosted server at https://api.flow.engineer/mcp is an optional development tool. The agent should suggest it and show the command. It should never add it to your config. iMessage MCP server has the setup.
  • Sign-in is yours. The agent can start a sign-in and give you a link and a code. You approve it.
  • No --yes from an agent. The setup command asks before it installs the skill, edits AGENTS.md or registers the MCP server. The docs say to leave that answer to the project owner.
  • Keys stay out of the repo. Never hard-code keys, never commit .env, and never put a key in browser or mobile code.
  • The app does not call MCP. MCP is not a runtime dependency. The app talks to Flow through the REST API or an SDK.

Treat anything an agent writes like any other code: review it before it handles customers.

Why docs written for agents matter

A page for coding agents is short on explanation and long on exact steps, commands and checks. Flow publishes llms.txt and per-page Markdown at docs.flow.engineer, so a coding agent can follow the integration without guessing.

Agent-ready docs, a test key you can get with no human steps, and an MCP server for verification make the loop much faster. Flow provides all three in one workflow.

Frequently asked questions

Can Claude Code or Cursor set up an iMessage integration?

Yes, for the code. Flow publishes a docs page written for coding agents. The agent gets a test key, writes the handler and verifies it in the sandbox. The iMessage number itself is set up through Flow.

Does the coding agent need an account to start?

No. It can get a test key with no account, by running npx @flow-engineer/messaging init or calling POST /v1/sandbox/keys. The key allows one contact and 50 messages on the Telegram sandbox and expires after seven days.

Where does the key go?

In FLOW_MESSAGING_KEY, set in the environment or a .env file that is in .gitignore. Flow's docs say never to hard-code keys, commit .env, or put a key in browser or mobile code.

Should the agent add the MCP server itself?

No. Flow's docs say the project owner decides. The agent should suggest it and show the command, and never add it to the developer's config. The app itself uses the REST API, not MCP, at runtime.

Can the agent test iMessage directly?

Not with the self-serve test key, whose sandbox is a Telegram bot. For iMessage, Flow has a free shared line for up to 25 people a month and dedicated lines. The agent verifies the loop on the Telegram sandbox, and the same code answers on iMessage.

Does this work in languages other than TypeScript?

Yes. The API is plain HTTP. Flow publishes a TypeScript SDK on npm and a Python SDK on PyPI. A Go SDK is not published yet, so Go uses the HTTP API.

Start hereiMessage API: a developer’s guideThe overview of how iMessage APIs work, and what to ask a provider. Build an agentBuild an iMessage AI agentWebhook in, model call, tools, reply out: the Flow loop, memory, testing and production safeguards.Build an agentiMessage agent with the Vercel AI SDKTake a Vercel AI SDK agent and answer on iMessage with streamed, chat-sized bubbles.Build an agentiMessage agent with the OpenAI Agents SDKReceive an iMessage, run an OpenAI Agents SDK agent and send the result back as bubbles.Build an agentiMessage agent with the Claude Agent SDKRun a Claude agent for each iMessage and deliver its streamed answer.Build an agentLangChain iMessage agentConnect a LangChain model or chain to an iMessage conversation.Build an agentOne agent on iMessage, WhatsApp and TelegramWhat changes per channel and what stays the same when one codebase answers everywhere.

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