Chat SDK

• Cloud (recommended) — connects to Spectrum Cloud with a project ID and secret. Runs anywhere, including serverless.
• Self-hosted — connects to your own @photon-ai/advanced-imessage gRPC endpoint.
• Local — reads the on-device Messages database and sends through Apple’s native APIs. macOS only.

​

Installation

pnpm add chat chat-adapter-imessage

​

Add the adapter

import { Chat } from "chat";
import { createiMessageAdapter } from "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!");
});

const bot = new Chat({
  userName: "mybot",
  adapters: {
    imessage: createiMessageAdapter({
      local: false,
      serverUrl: process.env.IMESSAGE_SERVER_URL,
      apiKey: process.env.IMESSAGE_API_KEY,
    }),
  },
});

createiMessageAdapter({
  local: false,
  clients: [
    { address: "imessage.example.com:443", token: "…", phone: "+1234567890" },
  ],
});

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

​

Configuration

​

Environment variables

# .env.local
IMESSAGE_LOCAL=false                  # "false" for cloud/self-host (default: true)

# Cloud (recommended)
IMESSAGE_PROJECT_ID=...
IMESSAGE_PROJECT_SECRET=...

# Self-hosted (alternative)
IMESSAGE_SERVER_URL=imessage.example.com:443   # gRPC host:port (NOT an https URL)
IMESSAGE_API_KEY=...
IMESSAGE_PHONE=+1234567890                      # optional, for multi-number routing

# Webhooks (remote/cloud only)
IMESSAGE_WEBHOOK_SECRET=whsec_...               # per-webhook signing secret

​

Receiving messages

• Webhooks (recommended for serverless) — Spectrum Cloud delivers each message to an HTTPS endpoint as signed JSON. No long-lived connection or cron job. Cloud mode only.
• Gateway listener — startGatewayListener() consumes spectrum-ts’s message stream in real time. Works in all modes; in serverless it needs a cron job to stay connected.

​

Webhooks

IMESSAGE_WEBHOOK_SECRET=whsec_...

// 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),
  });
}

bot.onNewMention(async (thread, message) => {
  await thread.post("Got it!"); // works directly from a webhook delivery (DM)
});

​

Gateway listener for serverless

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

export const maxDuration = 800;

export async function GET(request: Request): Promise<Response> {
  const cronSecret = process.env.CRON_SECRET;
  if (!cronSecret) {
    return new Response("CRON_SECRET not configured", { status: 500 });
  }

  const authHeader = request.headers.get("authorization");
  if (authHeader !== `Bearer ${cronSecret}`) {
    return new Response("Unauthorized", { status: 401 });
  }

  const durationMs = 600 * 1000;

  return bot.adapters.imessage.startGatewayListener(
    { waitUntil: (task) => after(() => task) },
    durationMs
  );
}

// vercel.json
{
  "crons": [
    {
      "path": "/api/imessage/gateway",
      "schedule": "*/9 * * * *"
    }
  ]
}

​

Feature support

​

Modals

• Modal.title becomes the poll question.
• Select.options become the poll choices (2–10 supported).
• Votes trigger onModalSubmit with the selected option’s value.

import { Chat, Modal, Select, SelectOption } from "chat";
import { createiMessageAdapter } from "chat-adapter-imessage";

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

bot.onNewMention(async (thread, message) => {
  await message.openModal(
    Modal({
      callbackId: "fav-color",
      title: "What is your favorite color?",
      children: [
        Select({
          id: "color",
          label: "Pick a color",
          options: [
            SelectOption({ label: "Red", value: "red" }),
            SelectOption({ label: "Blue", value: "blue" }),
            SelectOption({ label: "Green", value: "green" }),
          ],
        }),
      ],
    })
  );
});

bot.onModalSubmit("fav-color", async (event) => {
  const color = event.values.color; // "red", "blue", or "green"
});

​

Tapback reactions

​

Limitations

• DMs send cold; groups are session-bound. For a DM, the adapter rebuilds the thread from its address over gRPC, so it can send, react, edit, and show typing even into a thread it hasn’t seen this session — including a webhook delivery. A group has no by-id resolver, so addressing one requires it to have been received over the gateway/stream in the current session; cold sends to an unseen group throw NotImplementedError. Local mode cannot create spaces at all — it only replies to received messages.
• No message history. fetchMessages is not supported — spectrum-ts exposes no paginated history API.
• No thread/chat info. fetchThread is not supported.
• No reaction removal. removeReaction is not supported.
• Local mode supports sending and receiving, but not reactions, typing, editing, modals, history, or thread info.
• Formatting. iMessage is plain-text only; Markdown formatting is stripped when sending, preserving the text content.
• Platform. Local mode requires macOS. Cloud and self-host run anywhere.
• Cards. iMessage has no structured card layouts.

​

Troubleshooting