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

# Unified Messaging API

> Receive and send messages on WhatsApp, iMessage and Telegram through one API.

Bring your existing agent to the apps people already use. Flow Messaging gives it one HTTP API
and event format for WhatsApp, iMessage and Telegram, with SDKs for TypeScript and Python.

Keep your model and tools. Receive a message, run your agent and reply to the same conversation;
Flow handles channel delivery and sending rules.

## Receive and reply

```ts TypeScript
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, {
    idempotencyKey: event.id,
  });
}
```

Install with `npm install @flow-engineer/messaging`. The [quickstart](https://flow.engineer/docs/unified-messaging-api/quickstart.md)
gets you a test key and a Telegram sandbox conversation before running this loop.

**Check it worked:** send a message from your phone and receive it back as “You said: …”.

> [!NOTE]
>
> The API is V0, at `/v0`, with one endpoint per message kind. Code written for `/v1`: see
> [Moving from /v1](https://flow.engineer/docs/unified-messaging-api/quickstart.md#moving-from-the-older-api).

## Choose a channel

> **[Telegram](https://flow.engineer/docs/unified-messaging-api/guides/telegram-agent.md)**
>
> Start on the shared sandbox, then connect your own bot.

> **[WhatsApp](https://flow.engineer/docs/unified-messaging-api/guides/whatsapp-agent.md)**
>
> Connect your own number with a live key.

> **[iMessage](https://flow.engineer/docs/unified-messaging-api/guides/imessage-agent.md)**
>
> Try Flow's shared line free, then get a line of your own.

> [!NOTE]
>
> The Telegram sandbox is available for testing. Flow's shared iMessage line comes with the free
> trial your first sign-in at flow\.engineer starts; dedicated iMessage lines, with group chats and
> SMS and RCS from the same number, are set up with the Flow team. The shared WhatsApp sandbox is not open to
> test keys. The US SMS/MMS channel is in pilot, not general availability.
> `GET /v0/senders` tells you which senders your key can use.

## What Flow handles

| You do                     | Flow does                                                                   |
| -------------------------- | --------------------------------------------------------------------------- |
| Receive events             | Delivers one event format through signed webhooks, a live stream or polling |
| Reply into a conversation  | Uses that conversation's sender and channel                                 |
| Send one kind per endpoint | Sends exactly that, or refuses it with `422` and a hint; converts nothing   |
| Retry with the same key    | Deduplicates the API request                                                |
| Follow delivery events     | Reports sent or failed, plus delivered and read where supported             |

See [sending rules](https://flow.engineer/docs/unified-messaging-api/concepts/send-gate.md) for reply windows, pacing and new-contact
budgets. These rules apply whether you send over HTTP, a stream or a webhook response.

## Pick your integration

> **[Use an SDK or HTTP](https://flow.engineer/docs/unified-messaging-api/quickstart.md)**
>
> TypeScript, Python or any language that makes HTTP requests.

> **[Use your agent framework](https://flow.engineer/docs/unified-messaging-api/frameworks/vercel-ai-sdk.md)**
>
> Connect an existing agent without changing its model or tools.

> **[Build with a coding agent](https://flow.engineer/docs/unified-messaging-api/coding-agents.md)**
>
> Setup instructions, a skill and an optional development MCP.

> **[Build on Flow Framework](https://flow.engineer/docs/framework/index.md)**
>
> Use Flow's conversation runtime as well as the messaging connection.

The SDKs are open source under Apache-2.0 in [flow-engineer/sdk](https://github.com/flow-engineer/sdk).
The HTTP API is versioned by date; [pin a version](https://flow.engineer/docs/unified-messaging-api/concepts/versioning.md) for production.