Getting Started

Most apps should start with Spectrum. It gives you one API across iMessage, WhatsApp Business, and other channels. Use @photon-ai/advanced-imessage directly when you need low-level iMessage features that Spectrum does not expose.

Before You Start

You need three things: a runtime, Photon credentials, and a recipient that can receive iMessage.

Runtime

Use Node.js >=18.17 or Bun. If you are using Node, check your version first:

node --version

Photon Credentials

Copy these two values:

Value	Format
Server address	`host:port`, for example `"imessage.example.com:443"`
Bearer token	A token string for the server

The server address is only the host and port. Do not include https://. For the first working example, put the server address directly in send.ts.

Put the bearer token in an environment variable. Do not commit it to source control.

export IMESSAGE_TOKEN="your-token"

$env:IMESSAGE_TOKEN="your-token"

This sets the variable only for the current terminal session. If you close the terminal, set it again. In production, set IMESSAGE_TOKEN through your deployment platform or secret manager.

Recipient

Prepare an address that can receive iMessage:

an email address, such as [email protected]
an E.164 phone number, such as +15551234567

The example below uses that address to create a chat, then sends a message to the returned chat.guid.

Install

npm install @photon-ai/advanced-imessage

pnpm add @photon-ai/advanced-imessage

yarn add @photon-ai/advanced-imessage

bun add @photon-ai/advanced-imessage

Send Your First Message

The first send has three steps:

Create a client with your server address and token.
Resolve the recipient with im.chats.create(...). This gives you a chat.guid.
Send text with im.messages.sendText(...).

Create send.ts, then replace imessage.example.com:443 and [email protected]:

import { createClient } from "@photon-ai/advanced-imessage";

const im = createClient({
  address: "imessage.example.com:443",
  token: process.env.IMESSAGE_TOKEN!,
});

try {
  // Message APIs need chat.guid, not the raw email address or phone number.
  const { chat } = await im.chats.create(["[email protected]"]);

  const message = await im.messages.sendText(chat.guid, "Hello from the SDK");
  console.log(message.guid);
} finally {
  await im.close();
}

im.chats.create(...) returns a server chat GUID. Direct chats and group chats use different shapes:

Chat type	GUID shape	Example
Direct chat	`any;-;{recipient}`	`any;-;[email protected]`
Group chat	`any;+;{group-id}`	`any;+;group-id`

Message APIs take chat.guid, not the raw email address or phone number:

await im.messages.sendText(chat.guid, "Hello from the SDK");

Run It

Node.js can run TypeScript through tsx. Bun runs .ts files directly.

npx tsx send.ts

pnpm dlx tsx send.ts

yarn dlx tsx send.ts

bun send.ts

On success, the script prints message.guid. Seeing that GUID means the message was accepted and sent.

Client Options

createClient(...) accepts these options:

Option	Type	Required	Description
`address`	`string`	Yes	Server address in `host:port` format. Do not include `https://`.
`token`	`string`	Yes	Bearer token.
`tls`	`boolean`	No	Encrypt the gRPC connection. Defaults to `true`; keep the default for hosted servers.
`timeout`	`number`	No	Timeout, in milliseconds, for unary requests. Streams stay open.
`retry`	`boolean \| RetryOptions`	No	Retry retryable unary failures. Streams are not retried automatically.

SDK Overview

The client is organized by resource:

Namespace	What it does
`im.messages`	Send text, attachments, mini app cards, multipart messages, replies, reactions, stickers, edits, unsends, list queries, and message events
`im.chats`	Create chats, read chat state, count chats, mark read, set typing, share contact cards, and manage chat backgrounds
`im.groups`	Rename groups, manage participants, set group icons, and leave groups
`im.attachments`	Upload files, read metadata, and stream downloads
`im.polls`	Create polls, vote, unvote, add options, and subscribe to poll events
`im.addresses`	Check address metadata, Focus silence state, and iMessage availability
`im.locations`	Read Find My shared friend locations, request location sharing, and watch live updates
`im.events`	Replay durable events after a disconnect

Next Steps

Core path:

Messages — send text, attachments, mini app cards, multipart messages, reactions, edits, unsends, and subscribe to message events
Chats — create chats, mark read, set typing, and manage chat backgrounds
Events — catch up on durable events after a disconnect
Error Handling — understand error classes, retries, and idempotency keys

Use as needed:

Groups — manage group names, participants, icons, and leaving
Attachments — upload files, read metadata, and stream downloads
Polls — create polls, vote, and subscribe to poll events
Addresses — check addresses, Focus state, and iMessage availability
Locations — read Find My shared friend locations and request location sharing

Advanced Kits

Opensource Kits

Utilities

Getting Started

Before You Start

Runtime

Photon Credentials

Recipient

Install

Send Your First Message

Run It

Client Options

SDK Overview

Next Steps

​Before You Start

​Runtime

​Photon Credentials

​Recipient

​Install

​Send Your First Message

​Run It

​Client Options

​SDK Overview

​Next Steps

Before You Start

Runtime

Photon Credentials

Recipient

Install

Send Your First Message

Run It

Client Options

SDK Overview

Next Steps