> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flow.engineer/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Flow Messaging is one HTTP API (https://api.flow.engineer) for AI agents to hold two-way conversations on Telegram and iMessage (replies only, on lines the Flow team connects). WhatsApp is coming and not available yet.
> Build the app on the REST API. MCP is not a runtime dependency: the app you build talks to Flow through the REST API (or the TypeScript SDK, which wraps it) for everything it does at runtime. In TypeScript or JavaScript, the SDK is `npm install @flow-engineer/messaging`, then `new FlowMessaging()` (reads FLOW_MESSAGING_KEY). Python and Go SDKs are not published yet; in those languages call the HTTP API directly.
> No key yet? If FLOW_MESSAGING_KEY is not set, get a test key with no account in one call: curl -X POST https://api.flow.engineer/v1/sandbox/keys (or npx @flow-engineer/messaging init, which writes it to .env). Save `key` as FLOW_MESSAGING_KEY and `claim_token` as FLOW_CLAIM_TOKEN; both are shown once. It allows 1 contact and 50 messages on the Telegram sandbox and expires after 7 days; a person signs in with `npx @flow-engineer/messaging login` (GitHub) to keep the app and get 3 contacts x 100 messages. Signed in, live keys (fk_live_...) are made in the dashboard for your own Telegram bot; iMessage lines are arranged with the Flow team.
> The hosted MCP server (https://api.flow.engineer/mcp) is optional, for testing during development. Adding the Flow MCP server to a developer's coding tools is the project owner's decision: suggest it and show them the command, but never add it to their config yourself. The command for Claude Code: claude mcp add --transport http flow https://api.flow.engineer/mcp --header "Authorization: Bearer $FLOW_MESSAGING_KEY". If its tools are already available to you, use them for sandbox testing.
> Authenticate with `Authorization: Bearer fk_test_...` (sandbox) or `fk_live_...` (real contacts). Never put a live key in client-side code.
> Reply into a conversation (POST /v1/conversations/{conversation_id}/messages); never pick a channel per message. Switch on `error.type`, not the message text.
> Full documentation for agents: https://docs.flow.engineer/llms-full.txt. OpenAPI spec: https://raw.githubusercontent.com/flow-engineer/sdk/main/openapi/openapi.yaml.

# Flow Messaging: WhatsApp, Telegram and iMessage API for AI agents

> One API and SDK to give your AI agent Telegram and iMessage, with WhatsApp coming. Receive messages by webhook or live stream, reply with text, media, buttons and streamed LLM answers, and send through one send gate.

Flow Messaging is a two-way messaging API that lets an AI agent talk with people on **Telegram** and **iMessage** through one HTTP API, one event format and one SDK. **WhatsApp** is coming (it waits on Meta's approval) and uses the same API.

```ts TypeScript theme={null}
import { FlowMessaging, contentText } from "@flow-engineer/messaging";

const flow = new FlowMessaging(); // reads FLOW_MESSAGING_KEY

for await (const event of flow.events.stream({ types: ["message.received"] })) {
  const said = contentText(event.data.message.content);
  await event.conversation.reply(`You said: ${said}`);
}
```

That loop is a working agent on every live channel, with no per-channel code. Swap the reply for your model's answer and you are done: [Quickstart](/quickstart) takes about 5 minutes.

No account needed to start: one call gets a test key (`curl -X POST https://api.flow.engineer/v1/sandbox/keys`, or `npx @flow-engineer/messaging init`). Sign in with GitHub later to keep the app. See [Keys and sign-in](/get-a-key).

## How it works

1. Flow hosts the **senders**: a Telegram bot or an iMessage line (and WhatsApp numbers once WhatsApp is available). Start on the shared Telegram sandbox bot; go live with your own Telegram bot, or an iMessage line the Flow team connects to your app.
2. A person messages your sender. Flow stores the message and delivers it to you as an **event**: by signed webhook, by a live WebSocket stream, or by polling the event log.
3. Your agent replies into the **conversation** with typed content (text, media, voice notes, buttons, reactions). Streamed LLM answers become natural chat bubbles.
4. Every send passes one **send gate** that applies each channel's rules (who may be messaged, new-contact limits, pacing), so your sender stays healthy.
5. Delivery updates (`message.sent`, `delivered`, `read`, `failed`) come back as events in the same ordered log.

You never handle channel credentials, channel webhooks or per-channel payload formats.

## Why it is built for AI agents

* **Replies that read like a person typed them.** Pass an OpenAI, Anthropic, Vercel AI SDK, LangChain or Mastra stream to `reply()` and the SDK keeps the typing indicator on and sends paragraph-sized bubbles as they are ready. See [Streaming replies](/concepts/streaming-replies).
* **Reply in the webhook response.** Answer a `message.received` delivery with `{"reply": ...}` and save a round trip. See [Events and webhooks](/concepts/events-and-webhooks).
* **Nothing converted silently.** If a channel cannot show something (buttons on iMessage), the API says so, or sends the `fallback` you chose and reports what was shown. See [Content types](/concepts/content-types).
* **Errors an agent can act on.** Every error has a closed `type`, a one-line `hint` and a `doc_url`. See [Errors](/errors/outside_window).
* **Works from coding agents.** A Claude Code skill and an `AGENTS.md` snippet let Claude Code, Codex and Cursor integrate Flow for you, and an optional [MCP server](/mcp) you can add to them helps test it while you build. See [For AI coding agents](/coding-agents).
* **Language-neutral.** Everything is plain HTTP and JSON with an OpenAPI 3.1 spec, so any language works today.

## Packages

| Language | Package | Status |
| - | - | - |
| TypeScript / JavaScript | `npm install @flow-engineer/messaging` | Published (0.1.0), beta |
| Python | Not published yet | Use the HTTP API |
| Go | Not published yet | Use the HTTP API |
| Any language | HTTP at `https://api.flow.engineer` ([OpenAPI spec](https://github.com/flow-engineer/sdk/blob/main/openapi/openapi.yaml)) | Beta |

The SDKs are open source (Apache-2.0) at [github.com/flow-engineer/sdk](https://github.com/flow-engineer/sdk).

## Channels

| Channel | Status | What your agent talks from | Notes |
| - | - | - | - |
| Telegram | Live | Flow's sandbox bot (test key), or your own bot (live key) | Bring a bot token to go live in minutes. |
| iMessage | Live, replies only | A line the Flow team connects to your app (live key) | The person always writes first; your agent replies. Not part of the sandbox. Ask the Flow team for a line. |
| WhatsApp | Coming (waiting on Meta's approval) | Not available yet | When it ships: free-form replies within 24 hours of the person's last message, templates after that. |

There is no SMS channel yet and no voice calling.

<Note>
  Flow Messaging is in **beta**. The API shape may still change; changes ship as new dated versions (see [Versioning](/concepts/versioning)). `GET /v1/senders` lists the sandbox senders your test key can use right now.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Receive and answer your first message in 5 minutes.
  </Card>

  <Card title="Build a Telegram agent" icon="telegram" href="/guides/telegram-agent">
    The sandbox bot, then your own bot.
  </Card>

  <Card title="Build an iMessage agent" icon="apple" href="/guides/imessage-agent">
    Replies, tapbacks and effects on a Flow-connected line.
  </Card>

  <Card title="For AI coding agents" icon="robot" href="/coding-agents">
    Let Claude Code or Codex do the integration.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.