Build with a coding agent

​

1. Get a key and set up

npx @flow-engineer/messaging init

• writes FLOW_MESSAGING_KEY and FLOW_CLAIM_TOKEN to .env and adds .env to .gitignore;
• prints the sandbox link and join code, the allowance and the expiry;
• with the user’s approval (they are the project owner, so leave the answer to them and never pass --yes yourself), installs the Claude Code skill in .claude/skills/flow-messaging/, adds a Flow Messaging section to AGENTS.md (read by Codex and other agents), and registers the MCP server flow for Claude Code (.mcp.json) and Codex (codex mcp add).

curl -X POST https://api.flow.engineer/v0/sandbox/keys

npm install @flow-engineer/messaging

​

2. Environment variables

​

3. The MCP server (optional, for development)

claude mcp add --transport http flow https://api.flow.engineer/mcp --header "Authorization: Bearer $FLOW_MESSAGING_KEY"

[mcp_servers.flow]
url = "https://api.flow.engineer/mcp"
bearer_token_env_var = "FLOW_MESSAGING_KEY"

{"mcpServers": {"flow": {"url": "https://api.flow.engineer/mcp", "headers": {"Authorization": "Bearer ${env:FLOW_MESSAGING_KEY}"}}}}

​

4. The skill

• Claude Code: init installs the skill in .claude/skills/flow-messaging/. It tells Claude how to integrate, which errors to handle and how to test.
• Any agent: a skill file is published at https://docs.flow.engineer/unified-messaging-api/skill.md. Install it with npx skills add https://docs.flow.engineer.

​

5. Integrate: what to write

1. Receive message.received events. In a web app, add a webhook route with flow.webhooks.handler({ onEvent }) (or constructEvent on the raw body). In a worker or script, use for await (const event of flow.events.stream({ types: ["message.received"] })).
2. Read what the person said with contentText(event.data.message.content); it covers text, captions, voice note transcripts and button taps.
3. Answer with event.conversation.reply(x), where x is a string or the user’s LLM stream (OpenAI, Anthropic, Vercel AI SDK, OpenAI Agents SDK, Claude Agent SDK, LangChain, Mastra). Pass { idempotencyKey: event.id }.
4. Register the webhook: POST /v0/webhook_endpoints with the public URL and ["message.received"]; save the returned secret as FLOW_MESSAGING_WEBHOOK_SECRET. Locally, with no public URL, read events from the live stream instead: GET /v0/stream (WebSocket, resumable with after; flow.events.stream(...) in TypeScript). See Local development.
5. Handle errors by error.type (TypeScript: err instanceof OutsideWindowError etc.). Each error carries a hint and a doc_url such as https://api.flow.engineer/docs/errors/outside_window.

import { FlowMessaging, contentText } from "@flow-engineer/messaging";
import { runAgent } from "./agent"; // the user's existing agent: returns a string or an LLM stream

const flow = new FlowMessaging();

export const POST = flow.webhooks.handler({
  onEvent: async (event) => {
    if (event.type !== "message.received") return;
    const input = contentText(event.data.message.content);
    await event.conversation.reply(await runAgent(input, { conversationId: event.conversation.id }), {
      idempotencyKey: event.id,
    });
  },
});

​

6. Verify end to end

1. Ask the user to join the sandbox from their phone, if they have not: give them the sandbox sender’s link from sandbox_join (or GET /v0/senders). On Telegram, opening the link and tapping Start joins; otherwise they send the sender’s join_code as it is, for example Hi Sandbox app (ref wild-otter-04508705). The join reaches the app as their first message.received.
2. Start the app (reading GET /v0/stream when developing locally without a public URL).
3. If the Flow MCP tools are available to you, call send_test_message or ask the user to send a message, then wait_for_event for message.received. Without them, ask the user to send a message and read it with GET /v0/events?type=message.received. After a send, wait for message.sent or message.failed (not message.delivered, which not every channel reports). Each wait_for_event call waits up to 50 seconds (a longer timeout_seconds is clamped to 50, with a note, not refused); if it times out, call it again with after set to the next_after it returned.
4. If a delivery failed, read it with get_webhook_deliveries (MCP), fix the handler, and replay_event; without the MCP tools, fix the handler and have the user write again.

​

Rules

• Build on the REST API (or the TypeScript SDK); the MCP server is never a runtime dependency.
• Use the SDK in TypeScript/JavaScript; do not hand-roll HTTP calls there.
• Reply into the conversation (event.conversation, or POST /v0/conversations/{conversation_id}/basic and the other kinds’ endpoints). Never choose a channel per message and never assume a contact has a phone number.
• Verify webhook signatures on the raw body before trusting it; deduplicate on the event id.
• Answer webhooks within 10 seconds. Run slow agents after the response (after(), waitUntil(), a queue) or use the event stream.
• Send only what the channel takes. Each kind has its own endpoint, whose page lists its channels; Flow converts nothing. A 422 unsupported_content names what was refused (param, channel, channel_code) and its hint says what to send instead; send that with a new Idempotency-Key, the refused one plus what it is (evt_123:card:2:basic). Code written for /v1: use the flow-messaging-migrate skill (Moving from /v1).
• Never message first on iMessage unless the sender’s imessage.can_initiate is on: the person writes first; on outside_window, wait for them to write, do not retry the same content. (On WhatsApp: send an approved template instead.)
• Handle iMessage group chats: a conversation with type group has no contact; read message.from for who wrote. Do not react, show typing or send read receipts in groups (each answers 422 unsupported_content, group_unsupported).
• Test keys only while building. Do not switch to fk_live_ unless the user asks.
• Do not work around the sandbox allowance. On 403 permission with channel_code sandbox_allowance_used or sandbox_contact_limit, or 401 authentication with sandbox_key_expired, do not retry and do not get more keys: ask the user to sign in (npx @flow-engineer/messaging login --no-wait, then login once they approve).

​

Docs for agents