Choose a messaging API

​

TL;DR: pick by need

​

Side by side

​

When Flow is not the right choice

• You need a WhatsApp sandbox now. Flow’s WhatsApp is self-serve with your own WhatsApp Business Account, but there is no sandbox yet.
• You need SMS, RCS, voice, email, Slack, Discord or any channel beyond Telegram, WhatsApp and iMessage. None of these is available on Flow yet. Twilio and the other CPaaS providers cover SMS, RCS and voice, the iMessage APIs below fall back to SMS, and Photon lists more channels than Flow, with RCS and SMS fallback on its plans.
• Your agent must start iMessage conversations at scale, or take FaceTime calls. Flow’s iMessage lines answer people who wrote first; writing first is available on request on dedicated lines, within a warm-up. FaceTime attempts only arrive as events. Group chats work on dedicated lines, which are arranged with the Flow team; Flow’s shared line is self-serve through the free trial.
• You must self-host, or keep message data on your own infrastructure. Flow is a hosted service only; its spec and SDKs are open source, the service is not.
• You need a contractual SLA or a compliance certification. Confirm availability with the Flow team before relying on either.
• You run one simple Telegram bot. The Bot API is free, and a few dozen lines of code may be all you need (see below).
• You want a Go SDK today. Flow’s TypeScript SDK is on npm (@flow-engineer/messaging) and its Python SDK on PyPI (flow-messaging); the Go SDK is coming, so until then Go calls the HTTP API.

​

The Telegram Bot API directly

// app/api/telegram/route.ts. Register it once:
// curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
//   -d url=https://example.com/api/telegram -d secret_token=$TELEGRAM_WEBHOOK_SECRET
export async function POST(req: Request) {
  if (req.headers.get("X-Telegram-Bot-Api-Secret-Token") !== process.env.TELEGRAM_WEBHOOK_SECRET) {
    return new Response(null, { status: 401 });
  }
  const update = await req.json();
  const msg = update.message;
  if (msg?.text) {
    await fetch(`https://api.telegram.org/bot${process.env.TELEGRAM_BOT_TOKEN}/sendMessage`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ chat_id: msg.chat.id, text: `Echo: ${msg.text}` }),
    });
  }
  return new Response("ok");
}

// app/api/flow/route.ts
import { createHmac, timingSafeEqual } from "node:crypto";

// Flow-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "t.<t>.<raw body>">
function verify(body: string, header: string, secret: string): boolean {
  const parts = header.split(",").map((p) => p.trim().split("="));
  const t = parts.find(([k]) => k === "t")?.[1];
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const want = createHmac("sha256", secret).update(`t.${t}.${body}`).digest();
  return parts.some(([k, v = ""]) => k === "v1" && /^[0-9a-f]{64}$/.test(v) && timingSafeEqual(want, Buffer.from(v, "hex")));
}

export async function POST(req: Request) {
  const body = await req.text(); // the raw body: a re-serialized one will not verify
  if (!verify(body, req.headers.get("Flow-Signature") ?? "", process.env.FLOW_MESSAGING_WEBHOOK_SECRET!)) {
    return new Response(null, { status: 400 });
  }
  const event = JSON.parse(body);
  if (event.type !== "message.received") return Response.json({});
  // The reply goes through the send gate into the same conversation, keyed by the event's ID.
  return Response.json({ reply: `Echo: ${event.data.message.content.text ?? ""}` });
}

​

Twilio and other CPaaS providers

​

iMessage APIs for agents

​

About Flow, today

• Live: Telegram (sandbox bot, or your own bot once you sign in with a Flow account); WhatsApp on a number in your own WhatsApp Business Account (self-serve once you sign in); the TypeScript SDK on npm (@flow-engineer/messaging); iMessage replies on lines arranged with the Flow team; signed, ordered webhooks and a WebSocket stream; the send gate; typed errors with hints; a hosted MCP server, which the project owner can choose to add to their coding tools; test keys with no account (POST /v0/sandbox/keys); sign-in with a Flow account (flow.engineer) and a dashboard.
• Not available yet: SMS and voice.
• Arranged with the Flow team: WhatsApp on Flow’s number, or help connecting your own; no WhatsApp sandbox yet.
• Coming: a Go SDK; docs.flow.engineer (not deployed yet; meanwhile see llms.txt and the OpenAPI spec).

​

Related

• Flow vs Photon (spectrum-ts)
• Quickstart, Keys and sign-in, The send gate, Events and webhooks