iMessage agent with the Vercel AI SDK

Building on the iMessage API? Build on iMessage with Flow: one agent for iMessage, WhatsApp and Telegram. New to it? Read the iMessage API guide.

The route

Flow’s Vercel AI SDK guide keeps channel delivery separate from your model and tools. This is the Next.js route from that guide:

// app/api/flow/route.ts (Next.js)
// npm install @flow-engineer/messaging ai @ai-sdk/openai
import { after } from "next/server";
import { FlowMessaging, contentText } from "@flow-engineer/messaging";
import { streamText, type ModelMessage } from "ai";
import { openai } from "@ai-sdk/openai";

const flow = new FlowMessaging();

export const POST = flow.webhooks.handler({
  onEvent: async (event) => {
    if (event.type !== "message.received") return;

    after(async () => {
      // The last 20 messages of this conversation, oldest first (the new one included).
      const page = await event.conversation.messages({ limit: 20 });
      const messages: ModelMessage[] = page.data
        .reverse()
        .map((m) => ({ role: m.direction === "in" ? "user" : "assistant", content: contentText(m.content) }) as ModelMessage)
        .filter((m) => m.content);

      const result = streamText({
        model: openai("gpt-4.1-mini"),
        system: "You are the assistant for Asha's Bakery. Answer in short messages.",
        messages,
      });
      await event.conversation.reply(result, { idempotencyKey: event.id });
    });
  },
});

flow.webhooks.handler verifies the Flow-Signature header with your webhook secret before it calls onEvent. The idempotency key is the event ID, so a redelivered event cannot make the agent answer twice.

How it fits

• Streaming into bubbles. reply(result) reads result.textStream, keeps typing on, and sends a bubble at each paragraph break while the model writes. See Flow’s streaming replies docs.
• History from Flow. The route loads the last 20 messages of the conversation, so you do not need your own store to start.
• Fast webhook. The handler answers at once and after() runs the model call.
• One handler for many channels. It serves Telegram and iMessage alike.

Run and test it

Set FLOW_MESSAGING_KEY, FLOW_MESSAGING_WEBHOOK_SECRET and OPENAI_API_KEY. Then register https://<your-app>/api/flow as a webhook endpoint for message.received with POST /v1/webhook_endpoints, and keep the whsec_... secret it returns.

During development you do not need a public URL. Flow’s docs suggest reading events from the live stream, and npx @flow-engineer/messaging listen --forward-to http://localhost:3000/api/flow wraps that and forwards signed deliveries to this route.

Get a test key with no account using npx @flow-engineer/messaging init. The self-serve sandbox is a Telegram bot, so you chat with your agent there. Send iMessage programmatically covers keys, signed webhooks and retries in more detail.

Tools and long tool calls

Tools work as usual with tools and stopWhen. Only the model’s text goes to the person. If a tool takes a while, wrap the work in event.conversation.responding(...) so the person sees typing while they wait.

For the design of the tools themselves, see Build an iMessage AI agent: read before write, confirm before you act, and say it is done only when your backend says so.

Going live on iMessage

Flow’s iMessage numbers are US numbers, shared or dedicated, and the same route answers on iMessage with no code change. By default customers text the line first, and a dedicated line with the outbound add-on can write first. iMessage has no buttons, so Flow sends numbered text, and your code still receives a button_reply.

Other agent frameworks follow the same shape: OpenAI Agents SDK, Claude Agent SDK and LangChain.

Frequently asked questions

Keep reading

All posts: the Flow blog. The Flow docs have the reference.