---
title: "We built the most feature-complete iMessage adapter for Vercel Chat SDK"
description: "We upgraded our Chat SDK iMessage adapter to Spectrum: the most feature-rich iMessage integration in the ecosystem, with tapbacks, effects and mini-app cards."
date: "2026-07-08"
authors:
  - "Andy"
  - "Tom"
category: "Engineering"
url: "https://photon.codes/blog/we-built-the-most-feature-complete-imessage-adapter-for-vercel-chat-sdk"
image: "https://pofmg3o8q2h4w0ma.public.blob.vercel-storage.com/cms/pLtfO7P0TN14Eo0aAD3NRitQDgo.png"
---

# We built the most feature-complete iMessage adapter for Vercel Chat SDK

**Preface**

If you are building an AI agent that talks to real people, at some point you will need it to reach them where they already are. Not in a browser tab. Not in a standalone app. In iMessage.

Sending an iMessage programmatically is not the hard part. The hard part is doing it reliably at scale — maintaining mac fleets, handling delivery edge cases, managing number reputation, falling back to SMS/RCS when iMessage is unavailable, and supporting the full depth of native iMessage features beyond plain text. Most iMessage APIs stop at "send and receive." Building one that is production-grade, feature-complete, and stable enough to run an always-on agent is a fundamentally different engineering problem.

We have spent the last year solving that problem. Today we are shipping a major upgrade to `@photon-ai/chat-adapter-imessage`, the iMessage adapter for [Chat SDK](https://chat-sdk.dev/docs). It is the most feature-complete iMessage adapter available for Chat SDK, and it is free to start.

## 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](https://x.com/haydenbleasel/status/2031461764966326577), 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](https://photon.codes/), Photon's 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](https://photon.codes/), 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:

| Capability | Status |
| --- | --- |
| Direct messages | ✅ |
| Cold-start DMs (`openDM`) | ✅ |
| File uploads | ✅ |
| Tapback reactions (add/remove) | ✅ Remote |
| Message editing | ✅ Remote |
| Message unsend | ✅ Remote |
| Typing indicators | ✅ Remote |
| Mark read | ✅ Remote |
| Message effects (confetti, fireworks, lasers…) | ✅ Remote |
| Mini-app cards | ✅ Remote |
| Chat background customization | ✅ Remote |
| Polls via modals | ✅ Remote |
| Voice messages | ✅ Remote |
| Webhooks (Spectrum Cloud) | ✅ |
| SMS/RCS fallback | ✅ |

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](https://app.photon.codes/) with a project ID and secret. Runs anywhere — Vercel, AWS, your laptop. No Mac required.

```typescript
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.

```typescript
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.

```typescript
// 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

```shell
pnpm add chat @photon-ai/chat-adapter-imessage
```

1. Sign up at [app.photon.codes](http://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](https://github.com/photon-hq/vercel-chat-adapter-imessage).

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

*Start building at* [*photon.codes*](https://photon.codes/)*.*
