Flow and Photon

​

TL;DR

​

Choose Photon if

• You want to self-host, or run on your own Mac. Spectrum is open source and runs without Photon’s cloud. Its local iMessage mode reads the Messages database on your own Mac and needs no project credentials (source, Oct 2026).
• You need a WhatsApp sandbox, or SMS, voice or Slack, today. Flow’s WhatsApp is self-serve with your own WhatsApp Business Account, but there is no sandbox yet, and Flow’s SMS is a US pilot, not generally available; Photon’s plans include RCS and SMS fallback (source, Oct 2026). Photon describes itself as an official Meta Business Technology Provider (source, Oct 2026), and the spectrum-ts README lists a Slack provider (source, Oct 2026).
• You need iMessage groups, polls or cold outreach. Photon says iMessage is where Spectrum is most mature, with groups, effects and per-line routing (source, Oct 2026). It can send polls (source, Oct 2026), and its Business plan supports cold outreach to up to 50 new contacts a day per line (source, Oct 2026). Flow’s iMessage lines reply after the person writes first (writing first is available on request on dedicated lines), and group chats work on dedicated lines only.
• You write TypeScript and want streaming built into the SDK. text() takes an OpenAI, Anthropic or AI SDK stream. On iMessage (remote mode) it edits the message in place; on Telegram private chats it shows a native draft preview (source, Oct 2026).
• You build on the Vercel Chat SDK. Photon publishes an iMessage adapter for it (source, Oct 2026).
• You need a compliance statement now. Photon’s homepage states it is SOC 2 Type II compliant (source, Oct 2026). Flow does not publish a compliance certification.

​

Choose Flow if

• Your agent is not written in TypeScript. Every operation is plain HTTP and JSON with an OpenAPI 3.1 spec, so Python, Go or any other language works today, without waiting for an SDK.
• You want a durable event log. Webhooks are retried for 3 days and arrive in order per conversation; after that the events stay in the log, and GET /v0/events?after=... or the live stream replays them. See Events and webhooks.
• Duplicate messages would hurt. Every POST takes an Idempotency-Key, so a retried request never sends twice (Idempotency), and replies sent in a webhook answer use the event’s ID as their key.
• You want channel rules enforced for you. Every send passes one send gate. Flow converts nothing: what you send is what the contact gets, and a kind, field or value a channel does not take fails with 422 unsupported_content, naming it (param) and saying what to send instead (hint).
• You want errors an agent can act on. Every error has a closed type, a hint for this case and a doc_url (error types).
• A coding agent should be able to start on its own. POST /v0/sandbox/keys returns a test key with no account, and the shared Telegram sandbox bot is ready to use (Keys and sign-in). The project owner can also add Flow’s hosted MCP server to their coding tools, so the agent can send a real test message and see what the webhook answered.
• You don’t want to hold channel credentials. Flow hosts the senders: the sandbox bot, or your own Telegram bot connected once with its token.

​

Same task: receive a Telegram message and reply

import { Spectrum } from "spectrum-ts";
import { telegram } from "spectrum-ts/providers/telegram";

const app = await Spectrum({
  projectId: process.env.PROJECT_ID!,
  projectSecret: process.env.PROJECT_SECRET!,
  providers: [
    telegram.config({
      botToken: process.env.TELEGRAM_BOT_TOKEN!,
    }),
  ],
});

for await (const [space, message] of app.messages) {
  if (message.content.type === "text") {
    await space.send(`Echo: ${message.content.text}`);
  }
}

// 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.
  return Response.json({ reply: `Echo: ${event.data.message.content.text ?? ""}` });
}

curl https://api.flow.engineer/v0/webhook_endpoints \
  -H "Authorization: Bearer $FLOW_MESSAGING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/api/flow", "events": ["message.received"]}'

• Where the process runs. Both can run as a webhook. Spectrum has the app.messages loop for a long-lived process and a webhook mode, which Photon describes as “Receive messages via HTTP instead of a long-lived process”: app.webhook() handles a POST route, with first-party adapters for Hono, Express and Elysia (source, Oct 2026). Flow’s handler is a stateless webhook in any language, and Flow also offers a stream (GET /v0/stream) for long-running workers and local development.
• What happens when your server is down. Flow keeps retrying for 3 days and keeps every event in the log for replay. Photon’s stable webhooks make up to 6 attempts within a default backoff budget of about 30 seconds, which the Photon team can tune; there is no dead-letter queue, and for zero loss Photon recommends reconciling against its API (source, Oct 2026). Photon’s Beta API contract adds webhook destinations with a retry budget, manual retry and dead-lettering (source, Oct 2026).
• Who holds the bot token. With Flow, you send the token once to POST /v0/senders and never handle it again. With Spectrum on Telegram, your process holds it.

​

Details

​

Related

• Choosing a messaging API for your AI agent: Flow, Photon, the Telegram Bot API, Twilio and iMessage APIs side by side.
• Quickstart and Keys and sign-in.