Skip to main content
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:
ValueFormat
Server addresshost:port, for example "imessage.example.com:443"
Bearer tokenA 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"
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

​
Send Your First Message

The first send has three steps:
  1. Create a client with your server address and token.
  2. Resolve the recipient with im.chats.create(...). This gives you a chat.guid.
  3. 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 typeGUID shapeExample
Direct chatany;-;{recipient}any;-;[email protected]
Group chatany;+;{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
On success, the script prints message.guid. Seeing that GUID means the message was accepted and sent.

​
Client Options

createClient(...) accepts these options:
OptionTypeRequiredDescription
addressstringYesServer address in host:port format. Do not include https://.
tokenstringYesBearer token.
tlsbooleanNoEncrypt the gRPC connection. Defaults to true; keep the default for hosted servers.
timeoutnumberNoTimeout, in milliseconds, for unary requests. Streams stay open.
retryboolean | RetryOptionsNoRetry retryable unary failures. Streams are not retried automatically.

​
SDK Overview

The client is organized by resource:
NamespaceWhat it does
im.messagesSend text, attachments, mini app cards, multipart messages, replies, reactions, stickers, edits, unsends, list queries, and message events
im.chatsCreate chats, read chat state, count chats, mark read, set typing, share contact cards, and manage chat backgrounds
im.groupsRename groups, manage participants, set group icons, and leave groups
im.attachmentsUpload files, read metadata, and stream downloads
im.pollsCreate polls, vote, unvote, add options, and subscribe to poll events
im.addressesCheck address metadata, Focus silence state, and iMessage availability
im.locationsRead Find My shared friend locations, request location sharing, and watch live updates
im.eventsReplay durable events after a disconnect

​
Next Steps

Core path:
  1. Messages — send text, attachments, mini app cards, multipart messages, reactions, edits, unsends, and subscribe to message events
  2. Chats — create chats, mark read, set typing, and manage chat backgrounds
  3. Events — catch up on durable events after a disconnect
  4. 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