It's a drop-in test harness: write your agent against the unified `app.messages` stream, and develop everything end-to-end without provisioning a phone number or pairing a device.
###### How it works
`terminal.config()` spawns the standalone [tuichat](https://github.com/photon-hq/tuichat) binary as a subprocess and drives it over JSON-RPC. The binary auto-downloads from GitHub Releases the first time you run it. In a TTY it boots the rich UI; in a non-TTY context (CI, piped input) it falls back to a synchronous readline loop, so the same agent code works for scripted integration tests.
```ts
import { Spectrum } from "spectrum-ts";
import { terminal } from "spectrum-ts/providers/terminal";
const app = await Spectrum({
providers: [terminal.config()],
});
for await (const [space, message] of app.messages) {
if (message.content.type === "text") {
await space.send(`echo: ${message.content.text}`);
}
}
```
No credentials, no config — just import and run.
###### What you get
Input and output are decoupled, so you can type while the agent is responding and the agent can push messages whenever it wants.
| Feature | How |
|---|---|
| Multiple chats | `Ctrl+N` opens a new chat, `Ctrl+J` / `Ctrl+K` switch between them. Each chat is its own Spectrum space. |
| Reactions | Press `r` on a message to react. Arrives in your code as a `reaction` content message. |
| Replies | Press `e` to reply inline. Arrives with a `replyTo: { messageId }` extra on the message. |
| File attachments | Drag-and-drop into the terminal — messages arrive with name, MIME type, and buffer. |
| Inline images | Rendered with the Kitty graphics protocol when supported, with a half-block fallback. |
| Typing indicators | `space.startTyping()` / `space.stopTyping()` show a live indicator. |
| Console capture | `console.log` / `info` / `warn` / `error` / `debug` from your agent are forwarded into a pinned `__system__` chat instead of garbling the UI. |
###### Config
```ts
terminal.config({
commands: [
{ name: "/clear", description: "Clear conversation memory" },
{ name: "/whoami", description: "Print sender details" },
],
});
```
| Option | Type | Default | Description |
|---|---|---|---|
| `commands` | `{ name: string; description?: string }[]` | `[]` | Slash commands surfaced in the TUI's command picker. Names must match `/^\/[A-Za-z0-9_-]+$/`. |
Slash commands arrive as regular text messages with the command string as the content — handle them in your `for await` loop the same way you'd handle any text.
###### Working with multiple spaces
By default the TUI starts on `chat-1`; new chats opened with `Ctrl+N` get `chat-2`, `chat-3`, and so on. To open a named space programmatically, pass an `id`:
```ts
import { terminal } from "spectrum-ts/providers/terminal";
const t = terminal(app);
const debug = await t.space({ id: "debug" });
await debug.send("agent online");
```
Calling `space()` ensures the chat exists in the sidebar — useful for kicking off a conversation before any user input.
###### Reactions and replies
Reactions ride the same `app.messages` stream as text — they arrive as a `reaction` content message:
```ts
for await (const [space, message] of app.messages) {
if (message.content.type === "reaction") {
console.log(`${message.sender.id} reacted ${message.content.emoji}`);
continue;
}
if (message.content.type === "text") {
await message.react("👀");
await space.send(`echo: ${message.content.text}`);
}
}
```
Threaded replies arrive as a normal message with a `replyTo` field:
```ts
const replyTo = (message as { replyTo?: { messageId: string } }).replyTo;
if (replyTo) {
await message.reply(`acknowledged your reply to ${replyTo.messageId}`);
}
```
###### When to use it
- **Iterating on agent logic** — every Spectrum API works exactly as it would in production, so behavior you build here ships unchanged.
- **Integration tests** — pipe stdin in non-TTY mode and assert on stdout; no TUI dependency for CI.
- **CLI tools** — same handler shape as any multi-platform deployment, with reactions and replies as first-class events.
##### WhatsApp Business
Source: https://photon.codes/docs/spectrum-ts/providers/whatsapp-business
```ts
import { whatsappBusiness } from "spectrum-ts/providers/whatsapp-business";
```
The WhatsApp Business provider wraps the official WhatsApp Business Cloud API. Reactions and threaded replies map to native WhatsApp features.
WhatsApp Business supports **1:1 conversations only**. The API does not expose group management for business accounts — calling `space(userA, userB)` throws.
###### Config
```ts
whatsappBusiness.config({
accessToken: "your-access-token",
phoneNumberId: "your-phone-number-id",
appSecret: "your-app-secret",
});
```
| Option | Description |
|---|---|
| `accessToken` | Permanent or system-user token from Meta for Developers. |
| `phoneNumberId` | The phone number ID for the business account sending messages. |
| `appSecret` | App secret used to verify webhook payload signatures. |
Find these values in your WhatsApp Business app settings on [Meta for Developers](https://developers.facebook.com/).
###### Example
```ts
import { Spectrum } from "spectrum-ts";
import { whatsappBusiness } from "spectrum-ts/providers/whatsapp-business";
const app = await Spectrum({
providers: [
whatsappBusiness.config({
accessToken: process.env.WA_TOKEN!,
phoneNumberId: process.env.WA_NUMBER_ID!,
appSecret: process.env.WA_SECRET!,
}),
],
});
for await (const [space, message] of app.messages) {
if (message.content.type === "text") {
await message.reply(`Got it: ${message.content.text}`);
}
}
```
###### Starting a conversation
Resolve a user by their WhatsApp phone number (international format, digits only) and open a 1:1 space:
```ts
const wa = whatsappBusiness(app);
const customer = await wa.user("15551234567");
const space = await wa.space(customer);
await space.send("Thanks for reaching out.");
```
Passing more than one user to `space()` throws — the provider rejects group creation explicitly.
#### Advanced
##### Custom Events and Lifecycle
Source: https://photon.codes/docs/spectrum-ts/custom-events-and-lifecycle
###### Custom events
Platform providers can emit events beyond messages — typing indicators, read receipts, delivery status, whatever the provider chooses to surface. Spectrum exposes each event as a flat async iterable on the app instance:
```ts
for await (const event of app.typing) {
console.log(`${event.platform}: typing event received`);
}
```
The property name matches the event name the provider declared. Events are merged across every provider that emits them, and each payload is annotated with a `platform` field so you know the source.
###### Lazy streams
Event streams are created lazily on first access. Accessing `app.typing` once kicks off the underlying listener; subsequent iterations share the same source.
###### Per-platform access
The same events are available on a narrowed platform instance, scoped to that platform only:
```ts
import { imessage } from "spectrum-ts/providers/imessage";
const im = imessage(app);
for await (const event of im.typing) {
// iMessage-only typing events
}
```
Use the flat form on `app` when you want a merged feed across platforms; use the narrowed form when you only care about one.
###### Lifecycle
###### Graceful shutdown
```ts
await app.stop();
```
This closes the merged message stream, drains and disposes every custom event stream, tears down every platform client via its `lifecycle.destroyClient` hook (if one is defined), and flushes any pending telemetry data when [telemetry](/spectrum-ts/getting-started#telemetry) is enabled. It's idempotent — calling `stop()` twice is safe.
###### Signal handling
Spectrum registers `SIGINT` and `SIGTERM` handlers on startup. When a signal fires:
1. `stop()` is invoked with a 3-second timeout.
2. If cleanup completes in time, the process exits with code 0.
3. If not, the process exits with code 1.
You don't need to wire this up yourself — running your app in a container with `docker stop` or hitting Ctrl-C in a terminal will drain cleanly.
###### When to call `stop()` manually
- You're embedding Spectrum in a longer-running process and want to tear it down without exiting.
- You're writing tests that create and dispose an app per case.
- You want deterministic cleanup before re-initializing with a different provider set.
##### Building a Custom Platform
Source: https://photon.codes/docs/spectrum-ts/custom-platforms
`definePlatform` is the entry point for building your own provider. It takes a name and a definition object, and returns a callable that:
- exposes a `.config()` method for registering the provider on `Spectrum()`
- accepts a Spectrum instance, space, or message for [narrowing](/spectrum-ts/platform-narrowing)
- carries any `static` properties you declare (like iMessage's `tapbacks`)
The full definition shape is `PlatformDef`.
###### Shape
```ts
import { definePlatform } from "spectrum-ts";
import z from "zod";
export const myPlatform = definePlatform("my-platform", {
// Validate provider config
config: z.object({
apiKey: z.string(),
}),
// Resolve a user from a string ID
user: {
resolve: async ({ input, client }) => ({
id: input.userID,
displayName: await client.lookupUser(input.userID),
}),
},
// Resolve or create a conversation
space: {
resolve: async ({ input, client }) => ({
id: await client.findOrCreateConversation(input.users.map(u => u.id)),
}),
},
// Client lifecycle
lifecycle: {
createClient: async ({ config, store }) => new MyPlatformClient(config.apiKey),
destroyClient: async ({ client }) => { await client.disconnect(); },
},
// Inbound message stream
async *messages({ client }) {
for await (const msg of client.onMessage()) {
yield {
id: msg.id,
content: { type: "text", text: msg.body },
sender: { id: msg.authorId },
space: { id: msg.channelId },
timestamp: new Date(msg.ts),
};
}
},
// Outbound dispatcher — all content types flow through here
send: async ({ space, content, client }) => {
switch (content.type) {
case "text":
return await client.send(space.id, content.text);
case "reaction":
await client.react(space.id, content.target.id, content.emoji);
return;
case "reply":
return await client.reply(space.id, content.target.id, content.content);
case "typing":
await client.setTyping(space.id, content.state === "start");
return;
}
},
// Optional static properties
static: {
reactions: { thumbsUp: "+1", thumbsDown: "-1" } as const,
},
});
```
###### Field reference
| Field | Required | Description |
|---|---|---|
| `config` | Yes | A Zod schema that validates the object passed to `platform.config()`. If every field is optional, `platform.config()` can be called with no arguments. |
| `user.resolve` | Yes | Resolves a user from a string ID. Returns at minimum `{ id: string }`. |
| `user.schema` | No | Optional Zod schema for extra user properties. |
| `space.resolve` | Yes | Resolves or creates a conversation. Receives an array of users plus optional params. |
| `space.schema` | No | Optional Zod schema for the resolved space. |
| `space.params` | No | Zod schema for additional space creation parameters — surfaces as the second arg to `platform(app).space()`. |
| `space.actions` | No | A map of content-builder factories that become sugar methods on the resolved space. Each `space.already scheduled?} C -->|yes| D[Reset its run_at to now + debounce] C -->|no| E[Schedule new batch flush job] D --> F[Job fires at run_at] E --> F F --> G[Handler reads + deletes rows
from batch_queue] G --> H[Hand drained messages to read stage] ``` If the flush job is cancelled between steps F and G, the rows stay in `batch_queue` and the next incoming message picks them up. ##### Carry-forward Sometimes the handler does drain the queue but is then cancelled mid-generation. Those messages are now in memory inside a cancelled job - they'd be lost on the floor. The fix is a `carried_messages` table. When a job is cancelled after draining, write the drained messages there. The next batch's handler reads from `carried_messages` first and prepends them as `[Earlier message] ...` lines so the model sees them as historical context, not as fresh input. ```mermaid stateDiagram-v2 [*] --> Queued Queued --> Drained: handler starts Drained --> Generating: pass to LLM Generating --> Sent: reply complete Generating --> Carried: cancelled Carried --> Queued: re-enqueued for next batch Sent --> [*] ``` ##### In-flight cancellation When a new message arrives and you have a job in flight (reading, generating, or sending), you need to stop it. Two pieces: 1. **A cancellation flag** in a per-chat `in_flight` table. The enqueuer sets `cancelled_at` and calls `boss.cancel(jobId)`. 2. **Polling inside the handler.** The send stage in particular polls `cancelled_at` every 500ms and aborts via an `AbortController`. The subtle bit: compare `cancelled_at` against the chain's own `chainStartedAt` timestamp, not against "is the flag set." Otherwise a stale flag from a prior cancelled chain orphans the new one. The flag is per-chain, not per-chat. ```ts const inflight = await readInflight(chatId); if (inflight?.cancelled_at && inflight.cancelled_at > chainStartedAt) { abortController.abort(); } ``` ##### What you give up This pipeline buys you correctness at the cost of a few hundred milliseconds of hop latency between stages. For a conversational Spectrum agent that's irrelevant - humans don't notice 300ms when a "real" reply takes 5 seconds anyway. For a low-latency tool integration, you'd consolidate stages. #### Recovery and state Source: https://photon.codes/docs/best-practices/recovery-and-state Workers crash. The send job fails halfway through a 4-message reply. The retry runs from the top - and the user gets messages 1 and 2 again, then 3 and 4 for the first time. Now they have a duplicate. You need three things to make this robust: stable client GUIDs, a resume cursor, and a place to record what failed. ##### Stable client GUIDs Every message you enqueue gets a deterministic identifier - a `clientGuid` - assigned at enqueue time, not at send time. The transport uses it for deduplication: if it sees the same `clientGuid` twice, it discards the second copy. ```ts const messages = reply.map((text, index) => ({ text, clientGuid: `${jobId}-${index}`, // stable across retries })); ``` Most modern messaging transports support stable client-side IDs for dedup, and Spectrum surfaces them through the provider interface - check what your provider exposes before assuming you need to build dedup yourself. The reason `clientGuid` must be stable is subtle: a worker that crashes after the transport ack'd but before the worker recorded it will retry the same message. Without a stable GUID, the transport sees a "new" message and delivers a duplicate. ##### startIndex resume cursor GUID-based dedup handles the "transport already saw this" case. But you also want the worker itself to skip messages it knows it already sent - both for performance and to avoid even attempting the dedup roundtrip. Persist a `startIndex` on the job. After each successful send, atomically bump it. On retry, resume from there: ```mermaid sequenceDiagram participant W as Worker participant Tx as Transport W->>W: assign clientGuids [A, B, C, D] W->>Tx: send msg[0] (guid A) Tx-->>W: ack W->>W: startIndex = 1 (persisted) W->>Tx: send msg[1] (guid B) Tx-->>W: ack W->>W: startIndex = 2 (persisted) W-x W: ⚡ crash Note over W,Tx: retry - load startIndex=2 W->>Tx: send msg[2] (guid C) W->>Tx: send msg[3] (guid D) ``` If the crash happens _between_ ack and persist, the retry will resend `msg[1]` - but the transport sees the same `clientGuid B` and discards it. Both layers of defense are doing work. ##### Per-resource memory scope A single agent talks to many users. Each one needs their own working memory, conversation history, and observational notes. Mixing them up is catastrophic - the agent telling one user about another user's plans is the kind of bug you see once and never forget. Scope every memory operation by `resourceId = senderAddress`. The thread ID is per-chat (`chat-${chatId}`), but memory is per-person: ```ts await memory.getWorkingMemory({ resourceId: senderAddress, threadId: `chat-${chatId}`, }); ``` The same person messaging from a group chat versus a 1:1 sees the same working memory (same `resourceId`), but conversation history is per-thread (different `threadId`). That's usually what you want - the agent remembers _who you are_ across all chats but treats each thread as its own conversation. ```mermaid flowchart TD Sender[senderAddress: alice@example.com] Sender --> WM[Working memory:
per-resource] Sender --> Notes[Observational notes:
per-resource] Chat1[chat-1
1:1 with alice] Chat2[chat-2
group with alice + bob] Chat1 --> H1[Message history
per-thread] Chat2 --> H2[Message history
per-thread] WM -.shared across.- Chat1 WM -.shared across.- Chat2 ``` If you shard memory across databases or tenants, each shard needs to follow the same convention. Test multi-user concurrency hard - race conditions in working-memory updates corrupt state silently and you won't notice until two users compare notes. ##### Job failure audit log When a job fails, you want to know which job, when, with what payload, and why - without grepping through rotating logs. A `job_failures` table is a small amount of code that pays back disproportionately. Every error path calls `recordJobFailure(queueName, jobId, payload, error)` and inserts a row. Now you can ask: - "Which jobs failed in the last hour?" - "Are all failures coming from one chat?" (a corrupt working-memory state) - "Are all failures from one queue stage?" (a transport outage vs. an LLM bug) - "What was the payload that triggered this?" (reproducer) Couple of operational notes: - **Add a retention policy.** Otherwise the table grows forever. Delete entries older than 30 days. - **Make `recordJobFailure` itself fail-safe.** Wrap it in a try/catch with a log fallback - you don't want a failed-failure-record to take down the worker. - **Be careful with payload size.** If your jobs carry images or large blobs, the audit table balloons. Either truncate the payload or store a pointer to it. ##### Putting it together The crash-recovery story: ```mermaid flowchart TD Job[Job starts] --> Try{Run handler} Try -->|success| Done[Done] Try -->|crash| Retry[Queue retries with same jobId] Try -->|error| Audit[recordJobFailure] Audit --> Retry Retry --> Resume[Load startIndex] Resume --> Send[Send from startIndex onward] Send --> Tx{Transport check} Tx -->|new clientGuid| Deliver[Delivered] Tx -->|seen clientGuid| Skip[Discarded as dup] Deliver --> Bump[Persist startIndex] Skip --> Bump Bump --> Done ``` Three independent layers - queue retry, resume cursor, transport dedup - and any one of them is enough to prevent a duplicate in most failure modes. Together they survive almost everything short of the database itself going down. #### iMessage deliverability Source: https://photon.codes/docs/best-practices/imessage-deliverability iMessage is end-to-end encrypted, so Apple can't read message content: they filter on behavior. Patterns that look automated, cold, or burst-y will get a line flagged regardless of what the messages actually say. The guidance below is what we see work and fail in production. ##### Inbound-first is the decision that matters The single most important design call is whether users text you first or you text users. Inbound-first integrations never surface the "Report Junk" banner that Apple shows on every message from an unknown number. Outbound-first integrations do, and after a couple of unanswered messages it tends to get tapped. How to make inbound-first work in practice: - **Pre-populate the first message.** Ship `sms:+1...&body=Hey!` deep links so tapping opens Messages with text pre-filled. Zero friction, and the user is the one who hits send. - **Share a contact card early.** Push a native iMessage contact card (or a `.VCF` for Android) shortly after the first exchange. Once they save it, you're a known contact and "Report Junk" is gone for good. ##### Capacity Two quotas govern how much traffic a deployment can carry. They're enforced limits. | Limit | Guidance | |---|---| | **5,000 messages per server per day** | Counts every send across all chats on a server. Past this, sends are rejected until the window resets. Email [help@photon.codes](mailto:help@photon.codes) for an increase. | | **50 new conversations per line per day** | A "new conversation" is the first message a line sends to a recipient it has never messaged before. Replies within existing conversations don't count. Most relevant if you're initiating outbound. | When a server hits 70-80% utilization, stop assigning new users to it. When the whole pool gets there, add capacity. On the Business plan, [auto-scale](/spectrum-ts/providers/imessage#auto-scale) handles the second step automatically. ###### What gets a line flagged Because Apple filters on behavior, the same five patterns account for nearly every flag we see: 1. **Burst sending**: 100+ messages from one line in a tight window 2. **No conversation**: broadcasting without exchange 3. **Hammering non-responders**: more than 2–3 follow-ups 4. **Cold outreach**: texting people who never opted in 5. **Off-hours sending**: 3am messages signal automation Avoid all five and blocks are rare. When a line does get flagged, the cause is almost always one of the first three within the hour before. ##### Do - **Design for inbound-first.** Users text you, not the other way around. - **Pace messages naturally.** Don't fire several within seconds. Bursts of 100/min look automated because they are. - **Make outreach conversational.** If you need to push an update (digest, accountability ping), open with a question and wait: "Ready for your update?" - **Share a contact card after the first exchange.** Once saved, the "Report Junk" surface is gone. - **Round-robin new users across lines.** Spread load before any one line stands out. - **Watch the dashboard.** When a line goes Flagged, review what the agent was doing in the hour before — the cause is almost always there. ##### Don't - **Push past the per-server quota.** Add capacity; horizontal scaling is the design. - **Include links or media in the first message.** Apple suppresses link-clicking until a reply lands. Ship a text-only opener built to get a response. - **Leave fallback lines dormant.** Apple deactivates lines with no traffic for ~2 months. Every line you keep around needs some traffic. - **Bombard non-responders.** Cap at 2–3 follow-ups, spaced across days, not hours. - **Segment Android users onto separate lines.** Spread them through the pool — they may be your power users. - **Use iMessage for cold outreach.** Cold belongs on A2P channels (Twilio etc.). iMessage is for warm conversations. ##### Getting help If you're scaling past a handful of lines, talk to us. We do capacity planning with customers, surface per-line analytics in the dashboard, and run a shared Slack or Discord channel with engineering for production deployments. --- ## CLI ### Getting Started #### Photon CLI Source: https://photon.codes/docs/cli/overview The Photon CLI replaces the [Dashboard](https://app.photon.codes) web UI for everyday work. Manage projects, Spectrum users and lines, billing, and your developer profile — all from a terminal. ```sh npx @photon-ai/cli login ``` You can run it on Node.js >= 18 — no additional runtime required. ##### Quick demo After [installing](/cli/installation) the CLI: ```sh # Log in (opens a browser to approve the device) photon login # List your projects photon projects ls # Set a project for the current shell session export PHOTON_PROJECT_ID=
###### Message Effects
Message effects apply to the whole outgoing message: confetti, fireworks, slam, invisible ink, and similar iMessage effects.
```ts
import { MessageEffect } from "@photon-ai/advanced-imessage";
await im.messages.sendText(chat.guid, "Happy birthday", {
effect: MessageEffect.confetti,
});
```
| Constant | Effect |
|---|---|
| `MessageEffect.confetti` | Confetti |
| `MessageEffect.fireworks` | Fireworks |
| `MessageEffect.balloons` | Balloons |
| `MessageEffect.heart` | Heart |
| `MessageEffect.lasers` | Lasers |
| `MessageEffect.celebration` | Celebration |
| `MessageEffect.sparkles` | Sparkles |
| `MessageEffect.spotlight` | Spotlight |
| `MessageEffect.echo` | Echo |
| `MessageEffect.slam` | Slam |
| `MessageEffect.loud` | Loud |
| `MessageEffect.gentle` | Gentle |
| `MessageEffect.invisible` | Invisible ink |
Clients that do not support a given effect show the message normally.
###### Text Formatting
`formatting` applies bold, italic, underline, strikethrough, or animated text effects to a range of text.
```ts
import { TextEffect } from "@photon-ai/advanced-imessage";
await im.messages.sendText(chat.guid, "Bold then bloom", {
formatting: [
{ type: "bold", start: 0, length: 4 },
{ type: "effect", start: 10, length: 5, effect: TextEffect.bloom },
],
});
```
| `type` | Effect | Shape |
|---|---|---|
| `"bold"` | Bold | `{ type: "bold", start, length }` |
| `"italic"` | Italic | `{ type: "italic", start, length }` |
| `"underline"` | Underline | `{ type: "underline", start, length }` |
| `"strikethrough"` | Strikethrough | `{ type: "strikethrough", start, length }` |
| `"effect"` | Animated text effect | `{ type: "effect", start, length, effect }` |
`start` and `length` use UTF-16 code units. In plain ASCII text, offsets match what you see on screen. With emoji or other non-BMP characters, one visible character may use two code units.
| Constant | Effect |
|---|---|
| `TextEffect.big` | Big |
| `TextEffect.small` | Small |
| `TextEffect.shake` | Shake |
| `TextEffect.nod` | Nod |
| `TextEffect.explode` | Explode |
| `TextEffect.ripple` | Ripple |
| `TextEffect.bloom` | Bloom |
| `TextEffect.jitter` | Jitter |
###### Send Attachments
Sending an attachment has two steps:
1. Upload file bytes with [`im.attachments.upload(...)`](/advanced-kits/imessage/attachments) to get an attachment GUID.
2. Pass `uploaded.attachment.guid` to `sendAttachment(...)`.
```ts
const uploaded = await im.attachments.upload({
fileName: "photo.jpg",
data: await readFile("photo.jpg"),
});
const sent = await im.messages.sendAttachment(chat.guid, uploaded.attachment.guid);
console.log(sent.guid);
```
The second argument to `sendAttachment(...)` is a server attachment GUID, not a local file path. Upload behavior, file extensions, Live Photos, and downloads are covered in [attachments](/advanced-kits/imessage/attachments).
###### Audio Messages
To use Apple's audio-message bubble UI, set `isAudioMessage: true`:
```ts
const audio = await im.attachments.upload({
fileName: "voice.m4a",
data: await readFile("voice.m4a"),
});
await im.messages.sendAttachment(chat.guid, audio.attachment.guid, {
isAudioMessage: true,
});
```
| Option | Meaning |
|---|---|
| `isAudioMessage: true` | Shows the audio-message UI, such as a play button and waveform |
| Omitted | Sends as a regular attachment |
###### Send Mini App Cards
`sendCustomizedMiniApp(...)` sends a card that, when tapped, opens your iMessage extension and hands it `url`. Use it to launch your own app with a structured payload; for plain link previews, just put the URL in `sendText(...)`.
You need a published iMessage extension on the App Store before you can call this. `appName`, `appStoreId`, `teamId`, and `extensionBundleId` identify that extension so Messages.app can route the tap to it on the recipient's device.
For most cards we recommend an image preview with an overlaid title:
```ts
const sent = await im.messages.sendCustomizedMiniApp(chat.guid, {
appName: "MyGame",
appStoreId: 1234567890,
teamId: "ABCDE12345",
extensionBundleId: "com.example.mygame.MessagesExtension",
url: "https://mygame.example.com/level/7",
layout: {
image: await readFile("preview.jpg"),
imageTitle: "Level 7",
},
});
console.log(sent.guid);
```
| Field | Meaning |
|---|---|
| `appName` | Display name of your app. Recipients without your extension installed see this on an App Store install prompt. |
| `appStoreId` | Numeric App Store id, e.g. `1234567890` from `apps.apple.com/app/id1234567890`. Positive integer. |
| `teamId` | 10-character uppercase alphanumeric Apple Team ID. Find it in App Store Connect → Membership. |
| `extensionBundleId` | Bundle identifier of the iMessage extension target inside your app. |
| `url` | Absolute URL delivered to your extension when the recipient taps the card. |
| `layout` | What the card looks like in the conversation, covered in [Card Layout](#card-layout) below. |
This call does not accept `replyTo`, message effects, or `subject`. The only option you can pass in the final argument is `clientMessageId`, used as an idempotency key for job retries.
###### Card Layout
`layout` mirrors Apple's `MSMessageTemplateLayout` — slot names match the Apple field names, so Apple's documentation applies directly.
| Slot | Where it renders |
|---|---|
| `caption` | Top-left, bold. The most prominent text slot. |
| `subcaption` | Below `caption`, on the left. |
| `trailingCaption` | Top-right. |
| `trailingSubcaption` | Below `trailingCaption`, on the right. |
| `image` | JPEG preview image filling the card. |
| `imageTitle` | Overlay text above the image. |
| `imageSubtitle` | Overlay text below `imageTitle`. |
| `summary` | Fallback text for notifications, lock screens, and other surfaces that cannot render the full card. |
The server enforces these rules at send time:
- At least one of `caption`, `subcaption`, `trailingCaption`, `trailingSubcaption`, or `image` must be set. `summary` alone is not enough — it only appears on fallback surfaces.
- `image` and `imageTitle` must be set together. Setting one without the other is rejected.
- `imageSubtitle` requires `image`.
`layout.image` must be JPEG bytes. The server checks the JPEG SOI marker (`FF D8`) and rejects any other format. Convert PNG, WebP, HEIC, or anything else to JPEG before calling.
###### Reply to a Message
To reply to a message, pass the target message GUID as `replyTo`:
```ts
await im.messages.sendText(chat.guid, "Replying to this", {
replyTo: sent.guid,
});
```
`replyTo` works with text, attachment, and multipart sends:
| Method | Reply field |
|---|---|
| `sendText(...)` | `options.replyTo` |
| `sendAttachment(...)` | `options.replyTo` |
| `sendMultipart(...)` | `options.replyTo` |
For a multipart target, pass both the message GUID and the zero-based bubble index:
```ts
await im.messages.sendText(chat.guid, "Replying to the second bubble", {
replyTo: {
guid: sent.guid,
partIndex: 1,
},
});
```
###### Send Multipart Messages
`sendMultipart(...)` sends text, mentions, and attachments as one logical message. Recipients see related bubbles instead of separate sends.
```ts
await im.messages.sendMultipart(chat.guid, [
{ text: "Look at this " },
{ text: "@Alice", mentionedAddress: "alice@example.com" },
{
attachmentGuid: uploaded.attachment.guid,
attachmentName: "photo.jpg",
},
]);
```
Each part is one text, mention, or attachment bubble. Do not mix text and attachment fields in the same part object.
Text part:
```jsonc
{
"text": "Look at this", // Text content
"mentionedAddress": "alice@example.com", // Optional; marks this text part as a mention
"formatting": [] // Optional; applies only to this text part
}
```
Attachment part:
```jsonc
{
"attachmentGuid": "attachment-guid", // Attachment GUID
"attachmentName": "photo.jpg" // Optional display name
}
```
| Input | Rule |
|---|---|
| `parts` | Must not be empty |
| Text part | Pass `text`; it is trimmed and must not be empty after trimming |
| Attachment part | Pass `attachmentGuid`; do not pass a local file path |
| `mentionedAddress` | Text parts only |
| `formatting` | Applies only to the current text part |
Multiple images are also multipart messages: upload each image, then put each attachment GUID in the same `sendMultipart(...)` call.
```ts
const photos = await Promise.all(
["photo-1.jpg", "photo-2.jpg", "photo-3.jpg"].map(async (fileName) => {
return im.attachments.upload({
fileName,
data: await readFile(fileName),
});
}),
);
await im.messages.sendMultipart(chat.guid, [
{
attachmentGuid: photos[0]!.attachment.guid,
attachmentName: "photo-1.jpg",
},
{
attachmentGuid: photos[1]!.attachment.guid,
attachmentName: "photo-2.jpg",
},
{
attachmentGuid: photos[2]!.attachment.guid,
attachmentName: "photo-3.jpg",
},
]);
```
###### Reactions and Stickers
###### Reactions
`setReaction(...)` adds or removes a tapback / emoji reaction. The fourth argument is `true` to add and `false` to remove.
```ts
await im.messages.setReaction(chat.guid, sent.guid, { kind: "love" }, true);
```
```ts
await im.messages.setReaction(chat.guid, sent.guid, { kind: "love" }, false);
```
| `kind` | Meaning |
|---|---|
| `"love"` | Heart |
| `"like"` | Thumbs up |
| `"dislike"` | Thumbs down |
| `"laugh"` | Laugh |
| `"emphasize"` | Emphasis |
| `"question"` | Question mark |
| `"emoji"` | Custom emoji; also pass `emoji` |
```ts
await im.messages.setReaction(chat.guid, sent.guid, { kind: "emoji", emoji: "👍" }, true);
```
###### Stickers
A sticker is an image placed on top of a message. Upload the sticker image first, then call `placeSticker(...)`.
Sticker placement is not screen pixels. Think of the target message bubble as a small coordinate space: `x: 0.5, y: 0.5` is roughly the center. Larger `x` moves right; smaller `x` moves left. Larger `y` moves down; smaller `y` moves up. Start near `0.5, 0.5` and make small adjustments. Do not pass pixel-like values such as `120` or `90`.
```ts
const sticker = await im.attachments.upload({
fileName: "sticker.png",
data: await readFile("sticker.png"),
});
await im.messages.placeSticker(chat.guid, sent.guid, sticker.attachment.guid, {
x: 0.54,
y: 0.48,
scale: 0.45,
rotation: -0.08,
width: 96,
});
```
| Field | Meaning |
|---|---|
| `x` | Horizontal position. `0.5` is roughly centered; larger moves right, smaller moves left |
| `y` | Vertical position. `0.5` is roughly centered; larger moves down, smaller moves up |
| `scale` | Optional scale factor |
| `rotation` | Optional rotation. Use small values such as `-0.08` or `0.08` for a slight tilt; do not pass `8` |
| `width` | Display width. Pass it explicitly to keep large source images from covering the message |
For multipart messages, reactions and stickers can target one bubble with `partIndex`. `partIndex` is zero-based. When omitted, the first bubble is targeted.
```ts
await im.messages.setReaction(chat.guid, sent.guid, { kind: "like" }, true, {
partIndex: 1,
});
```
`placeSticker(...)` supports the same `partIndex` option.
###### Edit and Unsend
`edit(...)` changes a sent message and returns the updated `Message`.
```ts
const edited = await im.messages.edit(chat.guid, sent.guid, "Corrected text", {
backwardCompatText: "Edited: Corrected text",
});
console.log(edited.guid);
```
`unsend(...)` retracts a sent message and returns `void`.
```ts
await im.messages.unsend(chat.guid, sent.guid);
```
| Operation | Apple window | Returns |
|---|---|---|
| `edit(...)` | Within 15 minutes of sending | `Message` |
| `unsend(...)` | Within 2 minutes of sending | `void` |
After the Apple window expires, the server rejects the request and the SDK throws. See [error handling](/advanced-kits/imessage/error-handling).
| Option | Used by | Meaning |
|---|---|---|
| `backwardCompatText` | `edit(...)` | Fallback text for clients that cannot display message edits |
| `partIndex` | `edit(...)`, `unsend(...)` | Target bubble index for multipart messages; zero-based |
| `clientMessageId` | `edit(...)`, `unsend(...)` | Idempotency key for job retries |
###### Notify Anyway
`notifySilenced(...)` triggers Apple's "Notify Anyway" action after a recipient has Focus silence enabled.
```ts
await im.messages.notifySilenced(chat.guid, sent.guid);
```
Returns `void`. To check Focus state before sending, use [`im.addresses.isFocusSilenced(address)`](/advanced-kits/imessage/addresses#check-focus-status).
###### Get and List Messages
###### Get One Message
When you know `chat.guid` and `message.guid`, call `get(...)`:
```ts
const message = await im.messages.get(chat.guid, sent.guid);
console.log(message.content.text);
```
Missing chats or messages throw `NotFoundError`.
###### List Recent Messages
`listRecent(...)` lists recent messages across chats:
```ts
const recent = await im.messages.listRecent({
pageSize: 25,
});
for (const message of recent.messages) {
console.log(message.guid, message.content.text);
}
```
`listInChat(...)` lists messages in one chat:
```ts
const page = await im.messages.listInChat(chat.guid, {
pageSize: 25,
before: new Date("2026-01-01T00:00:00Z"),
});
for (const message of page.messages) {
console.log(message.guid);
}
```
For pagination, pass the previous response's `nextPageToken` as the next request's `pageToken`:
```ts
let pageToken;
do {
const page = await im.messages.listInChat(chat.guid, {
pageSize: 50,
pageToken,
});
for (const message of page.messages) {
console.log(message.guid, message.content.text);
}
pageToken = page.nextPageToken;
} while (pageToken);
```
| Filter | Meaning |
|---|---|
| `after` | Only messages created after this time |
| `before` | Only messages created before this time |
| `isFromMe` | `true` for sent messages only, `false` for received messages only |
| `isRead` | `true` for read messages only, `false` for unread messages only |
| `pageSize` | Number of messages per page; range `1..100` |
| `pageToken` | `nextPageToken` from the previous response |
###### Embedded Media
Digital Touch and handwritten-message media are not exposed as regular attachments. Use `getEmbeddedMedia(...)` to read that media.
```ts
const media = await im.messages.getEmbeddedMedia(chat.guid, message.guid);
console.log(media.mimeType, media.data.byteLength);
```
| Case | Result |
|---|---|
| Message is Digital Touch or handwritten media | Returns `{ data, mimeType }` |
| Chat or message does not exist | Throws `NotFoundError` |
| Message is not an embedded-media type | Throws `ValidationError`, with `error.code === ErrorCode.operationNotSupported` |
###### Message Events
`subscribeEvents(...)` streams live message changes. To scope it to one chat, pass `{ chat: chat.guid }`:
```ts
for await (const event of im.messages.subscribeEvents({ chat: chat.guid })) {
switch (event.type) {
case "message.received":
console.log(event.message.guid, event.message.content.text);
break;
case "message.edited":
console.log(event.messageGuid, event.editedAt);
break;
case "message.unsent":
console.log(event.messageGuid, event.retractedAt);
break;
}
}
```
Omit the filter to receive events for all visible chats:
```ts
for await (const event of im.messages.subscribeEvents()) {
console.log(event.chatGuid, event.type);
}
```
Common event fields:
```ts
const event = {
// Event type.
type: "message.received",
// Durable event sequence.
sequence: 123,
// Chat that owns the event.
chatGuid: "any;-;alice@example.com",
// Whether the current account produced the event.
isFromMe: false,
occurredAt: new Date("2026-01-01T12:00:00Z"),
// Participant that triggered the event; may be absent.
actor: {
address: "alice@example.com",
service: "iMessage",
},
// Present on message.received.
message: {
guid: "message-guid",
},
};
```
| `event.type` | Extra fields | Meaning |
|---|---|---|
| `message.received` | `message` | A message was received or became visible |
| `message.edited` | `messageGuid`, `content`, `editedAt` | A message was edited |
| `message.read` | `messageGuid`, `readAt` | A message was marked read |
| `message.unsent` | `messageGuid`, `retractedAt` | A message was retracted |
| `message.reactionAdded` | `messageGuid`, `reaction`, `targetPartIndex?` | A reaction was added |
| `message.reactionRemoved` | `messageGuid`, `reaction`, `targetPartIndex?` | A reaction was removed |
| `message.stickerPlaced` | `messageGuid`, `sticker?`, `placement?`, `targetPartIndex?` | A sticker was placed on a message |
Write method return values tell you that the call you made has completed. Event streams are for changes from other people, other devices, or another part of your system. In production, consume live streams and recovery together; see [events](/advanced-kits/imessage/events).
###### Next Steps
1. [Attachments](/advanced-kits/imessage/attachments) — upload files, get attachment GUIDs, and send attachment messages
2. [Chats](/advanced-kits/imessage/chats) — create chats and get `chat.guid`
3. [Events](/advanced-kits/imessage/events) — handle live events and recovery
4. [Error Handling](/advanced-kits/imessage/error-handling) — handle errors, retries, and idempotent writes
##### Chats
Source: https://photon.codes/docs/advanced-kits/imessage/chats
`im.chats` creates and manages iMessage conversations. A chat can be a direct conversation or a group conversation.
Most chat methods identify the conversation by `chat.guid`. The exceptions are `create(...)`, which takes email addresses or phone numbers and returns `chat.guid`, and `count(...)`, which does not take a chat argument.
For group names, participants, group icons, and leaving a group, use [groups](/advanced-kits/imessage/groups).
###### What You Can Do
| Need | Use this when |
|---|---|
| Create a chat | You have one or more email addresses or phone numbers |
| Get a chat | You have `chat.guid` and need chat details |
| Count chats | You need the number of currently visible chats |
| Mark read | A user opened the conversation and you want to clear unread state |
| Set typing | You want to show or hide the typing indicator |
| Share a contact card | You want to send the current account's contact card |
| Set a background | You want to apply an image as the chat background |
| Subscribe to events | You need live changes for read state, archive state, or backgrounds |
###### Chat GUIDs
A chat GUID is the server identifier for a conversation:
| Chat type | GUID shape | Example |
|---|---|---|
| Direct chat | `any;-;{recipient}` | `any;-;alice@example.com` |
| Group chat | `any;+;{group-id}` | `any;+;group-id` |
In normal code, do not hand-write GUIDs. Use the `chat.guid` returned by `im.chats.create(...)`, `im.chats.get(...)`, message results, or event payloads.
###### Create a Chat
One address creates a direct chat. Two or more addresses create a group chat:
```ts
const { chat } = await im.chats.create(["alice@example.com"]);
console.log(chat.guid);
```
```ts
const { chat: group } = await im.chats.create(["alice@example.com", "bob@example.com"]);
console.log(group.guid);
```
Returns `CreateChatResult`:
```jsonc
{
"chat": { // Created or resolved Chat
"guid": "any;-;alice@example.com",
"displayName": "Alice",
"isGroup": false
},
"initialMessage": { // Present only when options.message is sent
"guid": "message-guid"
}
}
```
| Input | Rule |
|---|---|
| `addresses` | At least one full email address or E.164 phone number |
| `options.message` | Optional opening text; sent as part of the same call |
| `options.effect` | Optional effect for the opening message; values are listed under [message effects](/advanced-kits/imessage/messages#message-effects) |
| `options.clientMessageId` | Optional idempotency key for retrying the same logical create operation |
The server normalizes addresses and rejects short codes, service numbers, invalid email addresses, and duplicate recipients.
`effect` only applies when `options.message` is present. It is not a chat property. For more complex sends, such as formatting or replies, create the chat first and then use the [messages API](/advanced-kits/imessage/messages).
`clientMessageId` is only needed when your job system might retry the same write after a crash or timeout. Most direct calls can omit it. See [error handling](/advanced-kits/imessage/error-handling) for details.
###### Get a Chat
```ts
const chat = await im.chats.get("any;-;alice@example.com");
console.log(chat.displayName, chat.unreadCount, chat.isGroup);
```
Returns `Chat`:
```jsonc
{
"guid": "any;-;alice@example.com", // Chat GUID used by chat and message APIs
"displayName": "Alice", // Display name
"isGroup": false, // Whether this is a group chat
"participants": [ // Chat participants
{
"address": "alice@example.com",
"service": "iMessage"
}
],
"service": "iMessage", // Chat service
"isArchived": false, // Whether the chat is archived
"isFiltered": false, // Whether the system filtered this chat
"unreadCount": 0, // Unread count; may be absent
"lastMessage": {} // Latest message when available
}
```
`get(...)` throws `NotFoundError` when the chat does not exist or cannot be resolved.
###### Count Chats
By default, archived chats are excluded:
```ts
const active = await im.chats.count();
```
Include archived chats with `includeArchived: true`:
```ts
const total = await im.chats.count({ includeArchived: true });
```
Returns `number`.
###### Read and Typing State
###### Mark Read
```ts
await im.chats.markRead(chat.guid);
```
Returns `void`. Calling it again when the chat has no unread messages is safe.
###### Typing Indicator
Show typing:
```ts
await im.chats.setTyping(chat.guid, true);
```
Stop typing:
```ts
await im.chats.setTyping(chat.guid, false);
```
Returns `void`. Typing is temporary UI state. It is not written to the durable event log and cannot be caught up after a disconnect.
###### Contact Card
```ts
await im.chats.shareContactInfo(chat.guid);
```
Returns `void`. The contact card comes from the Mac running the service. The SDK cannot choose which fields are included.
###### Chat Backgrounds
Chat backgrounds use raw image bytes. They are not attachment GUIDs, and you do not upload them through `im.attachments` first.
###### Set a Background
```ts
await im.chats.setBackground(chat.guid, await readFile("background.jpg"));
```
Returns `void`. `data` must not be empty. The server detects the image type from the bytes. JPEG, PNG, HEIC, and HEIF are supported.
After `setBackground(...)` succeeds, the background usually syncs to other participants' devices within `30s`. The image is uploaded to iCloud and then distributed to the conversation. This is not a hard SLA: network state, iCloud state, and the Messages client state all affect when the background appears.
| Stage | What happens |
|---|---|
| Before `setBackground(...)` returns | The server waits until the background asset is uploaded and ready for distribution |
| After `setBackground(...)` returns | The chat background change has been submitted, and iCloud distributes the asset |
| On other devices | The background appears after Messages receives the iCloud-distributed asset |
Common reasons the background UI may not appear:
| Situation | Result |
|---|---|
| The recipient's network, iCloud, or Messages state is unhealthy | The background may appear late, often after reopening Messages |
| A group member has never spoken, interacted, or is treated by Apple as unknown / untrusted | Apple may not show the background UI to that member |
The last case is a Messages display rule, not an SDK option. If one group member never sees the background, it is usually more effective for that member to send a message, mark the sender as known, or reopen Messages than to call `setBackground(...)` repeatedly.
###### Check Background State
```ts
const hasCustom = await im.chats.hasBackground(chat.guid);
```
Returns `boolean`.
###### Remove a Background
```ts
await im.chats.removeBackground(chat.guid);
```
Returns `void`. Removing a background is safe to repeat, even when no custom background is set.
###### Chat Events
`subscribeEvents(...)` returns `TypedEventStream