What Chat SDK does and why adapters matter

Chat SDK is Vercel's TypeScript library for building bots that work across messaging platforms from a single codebase. You write your agent logic once — message handlers, streaming responses, state management — and adapters handle the platform-specific translation. Photon's iMessage adapter is one of the first platform adapters launched with Vercel's Chat SDK, alongside Slack, Discord, Teams, Telegram, WhatsApp, and others.

iMessage has always been the hardest platform to cover. Sending iMessages reliably from a server process is a genuinely difficult infrastructure problem — persistent connections, delivery guarantees, number management, and native feature support all have to be solved before the adapter layer even begins.

Our adapter is the most feature-rich and reliable iMessage adapter available for Chat SDK. It is built on Spectrum, Photon's open-source multi-channel agent framework — the same infrastructure that powers production iMessage agents for companies shipping today. Spectrum handles the hard parts — messaging streaming, message routing, delivery confirmation, SMS/RCS fallback — so the adapter can expose the full depth of native iMessage capabilities through a clean Chat SDK interface.

What changed in the upgrade

This release upgrades the adapter to Spectrum, our next-generation messaging infrastructure built for iMessage. The result is the most feature-complete and reliable iMessage integration available in the Chat SDK ecosystem.

Here is what the adapter now supports — no other Chat SDK iMessage adapter covers even half of this list:

Most iMessage integrations stop at "send and receive text." This adapter gives your agent the full range of native iMessage behavior — effects, tapbacks, rich cards, typing indicators, chat wallpapers — the things that make an iMessage conversation feel like an iMessage conversation, not a stripped-down proxy. And it does it reliably, backed by infrastructure purpose-built for always-on iMessage delivery.

Two ways to run it

The adapter auto-detects its mode from environment variables:

Cloud (recommended)

Connect to Spectrum Cloud with a project ID and secret. Runs anywhere — Vercel, AWS, your laptop. No Mac required.

import { Chat } from "chat";
import { createiMessageAdapter } from "@photon-ai/chat-adapter-imessage";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    imessage: createiMessageAdapter({
      local: false,
      projectId: process.env.IMESSAGE_PROJECT_ID,
      projectSecret: process.env.IMESSAGE_PROJECT_SECRET,
    }),
  },
});

bot.onNewMention(async (thread, message) => {
  await thread.post("Hello from iMessage!");
});

import { Chat } from "chat";
import { createiMessageAdapter } from "@photon-ai/chat-adapter-imessage";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    imessage: createiMessageAdapter({
      local: false,
      projectId: process.env.IMESSAGE_PROJECT_ID,
      projectSecret: process.env.IMESSAGE_PROJECT_SECRET,
    }),
  },
});

bot.onNewMention(async (thread, message) => {
  await thread.post("Hello from iMessage!");
});

import { Chat } from "chat";
import { createiMessageAdapter } from "@photon-ai/chat-adapter-imessage";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    imessage: createiMessageAdapter({
      local: false,
      projectId: process.env.IMESSAGE_PROJECT_ID,
      projectSecret: process.env.IMESSAGE_PROJECT_SECRET,
    }),
  },
});

bot.onNewMention(async (thread, message) => {
  await thread.post("Hello from iMessage!");
});

Local

Runs directly on a Mac, reading the local iMessage database and sending via on-device APIs. No external server, no credentials. Great for development.

const bot = new Chat({
  userName: "mybot",
  adapters: {
    imessage: createiMessageAdapter({ local: true }),
  },
});

const bot = new Chat({
  userName: "mybot",
  adapters: {
    imessage: createiMessageAdapter({ local: true }),
  },
});

const bot = new Chat({
  userName: "mybot",
  adapters: {
    imessage: createiMessageAdapter({ local: true }),
  },
});

Webhooks: the serverless-native path

One of the biggest additions in this release is first-class webhook support. In cloud mode, Spectrum Cloud delivers inbound messages to your HTTPS endpoint as signed JSON — no long-lived connections, no cron jobs, no gateway processes to babysit.

// app/api/imessage/webhook/route.ts
import { after } from "next/server";
import { bot } from "@/lib/bot";

export async function POST(request: Request): Promise<Response> {
  return bot.webhooks.imessage(request, {
    waitUntil: (task) => after(() => task),
  });
}

// app/api/imessage/webhook/route.ts
import { after } from "next/server";
import { bot } from "@/lib/bot";

export async function POST(request: Request): Promise<Response> {
  return bot.webhooks.imessage(request, {
    waitUntil: (task) => after(() => task),
  });
}

// app/api/imessage/webhook/route.ts
import { after } from "next/server";
import { bot } from "@/lib/bot";

export async function POST(request: Request): Promise<Response> {
  return bot.webhooks.imessage(request, {
    waitUntil: (task) => after(() => task),
  });
}

The adapter verifies the X-Spectrum-Signature HMAC on every delivery, rejects stale requests, and routes messages into your bot. Spectrum Cloud retries failed deliveries with backoff and delivers at-least-once. For serverless deployments on Vercel, this is the cleanest path — your agent wakes up on demand, processes the message, and goes back to sleep.

Even from a webhook delivery, your bot can still reply, react, edit, and show typing — the adapter rebuilds the thread from its chat GUID via spectrum-ts. This is the kind of deep iMessage integration that no other Chat SDK adapter provides.

Free to start, scales when you do

This is where the Spectrum integration changes the economics.

Photon's Free tier gives you:

• Unlimited daily messages

• Full direct messaging iMessage API access

• RCS and SMS fallback

• iOS 26 features (polls, background customization, and more)

• Up to 10 users

• Zero cost

If you are an individual developer building an agent, or a small team prototyping a product, you do not pay anything. You get the full feature set of the adapter, backed by production infrastructure, with no trial period and no credit card.

Pro ($25/mo) extends that to 100 users with fast-track support. Business ($250/line/mo) adds dedicated iMessage lines, group messaging API, cold outreach, and mini-app support. Enterprise brings custom SLAs, the lowest throttling, dedicated numbers you own, and what we believe is one of the most reliable iMessage API infrastructures in the world — purpose-built for agents that need to be always-on.

The pricing is flat and predictable. No per-message fees, no hidden platform charges, no sales call required to get started.

Get started

1. Sign up at app.photon.codes — takes 30 seconds

2. Set your IMESSAGE_PROJECT_ID and IMESSAGE_PROJECT_SECRET

3. Write your bot

The full README, configuration reference, and feature matrix are on GitHub.

If you have been waiting for an iMessage adapter for Chat SDK that is actually feature-complete and production-ready, this is it.

Spectrum is open source. The adapter is MIT licensed. Start building at photon.codes.