Skip to main content
import { imessage } from "spectrum-ts/providers/imessage";
The iMessage provider supports two connection modes: cloud and local. It exposes iMessage-specific features such as tapbacks, DM and group spaces, chat backgrounds, mini-app cards, and per-phone routing through platform narrowing. Group creation and group-change events require a dedicated cloud line.

​
Quick start

Use cloud mode when you want Spectrum to manage the iMessage infrastructure: 
import { Spectrum } from "spectrum-ts";
import { imessage } from "spectrum-ts/providers/imessage";

const app = await Spectrum({
  projectId: process.env.PROJECT_ID!,
  projectSecret: process.env.PROJECT_SECRET!,
  providers: [imessage.config()],
});
Use local mode when you are developing on your own Mac and only need local Messages database access: 
imessage.config({ local: true });
Cloud mode discovers all lines owned by your project by default. If your project owns multiple dedicated lines and you want the SDK to subscribe to only some of them, pass those cloud clients explicitly: 
imessage.config({
  clients: [
    { address: "line-1.imsg.photon.codes:443", token: "your-token", phone: "+15551111111" },
  ],
});
This is advanced cloud configuration, not a separate connection mode. Explicit client tokens are not renewed by the SDK, so you are responsible for keeping them current. Most applications should use imessage.config() and let Spectrum discover and renew their cloud clients automatically.

​
Explore iMessage

Connection and routing

Compare cloud and local modes. Learn line allocation, quotas, space types, and per-phone routing.

Messaging features

Use effects, chat renames, avatars, group membership, backgrounds, mini-app cards, contact cards, attachments, and tapbacks.