Local development: receive Telegram and iMessage messages on localhost

// npm install @flow-engineer/messaging
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"] })) {
  await event.conversation.reply(`You said: ${contentText(event.data.message.content)}`, {
    idempotencyKey: event.id,
  });
}

​

How it works

1. Connect to wss://api.flow.engineer/v1/stream with Authorization: Bearer $FLOW_MESSAGING_KEY. Filter with type (repeat it for several types).
2. Every text frame is one JSON object. event frames carry the same event a webhook would receive.
3. Reply over the API (POST /v1/conversations/{conversation_id}/messages), or send a send frame on the same socket; each send gets one ack or error frame back, matched by ref (your idempotency key).
4. Keep the id of the last event you handled. When you reconnect, or when the server sends a reconnect frame before it restarts, connect again with after set to that ID: the stream replays everything after it, then goes live.

# pip install websockets
import asyncio, json, os, websockets

async def main():
    url = "wss://api.flow.engineer/v1/stream?type=message.received"
    headers = {"Authorization": f"Bearer {os.environ['FLOW_MESSAGING_KEY']}"}
    async with websockets.connect(url, additional_headers=headers) as ws:
        async for raw in ws:
            frame = json.loads(raw)
            print(frame)  # an "event" frame; reply with POST /v1/conversations/{id}/messages

asyncio.run(main())

​

Testing your webhook handler locally

npx @flow-engineer/messaging listen --forward-to http://localhost:3000/api/flow

• Each event is POSTed with the same headers and signature as a real webhook delivery (Flow-Signature, Flow-Event-Id, Flow-Event-Type, Flow-Version), signed with FLOW_MESSAGING_WEBHOOK_SECRET (made and saved to .env if it is not set).
• If your handler answers a message.received with {"reply": ...}, listen sends the reply into the conversation, with the event’s ID as the idempotency key, as the API does for real webhooks.
• Flags: --events a,b (only these event types), --after evt_... (replay from this event first, then go live), --secret whsec_... (the signing secret to use). Without --forward-to, listen only prints events.

​

Tips

• Use a test key while developing: only people who joined your sandbox can reach your agent.
• To run past events through new code, find the event just before them with GET /v1/events and pass its ID as after.
• The stream is for long-running processes. In production, serverless apps usually use webhooks.

​

Related

• Events and webhooks
• For AI coding agents: the MCP server can wait for events and replay them too.
• API: Open the live stream