- A Photon Spectrum project with iMessage enabled
- A public URL that reaches the bot. During development, a tunnel such as ngrok gives your local port one
Step 1: Set up Photon Spectrum
- Create a Spectrum project and enable the iMessage platform
- Copy your project ID and project secret — together they are the Basic-auth credentials for Spectrum’s management API
-
Register a webhook pointing at your bot’s
/webhookendpoint (the bot listens on port3204by default; override withBOT_SERVER_PORT): -
Copy the webhook secret: Spectrum signs every request, and the SDK rejects requests whose
X-Spectrum-Signaturedoes not verify
Step 2: Add the credentials
Inapps/bots/.env:
Step 3: Start the bot
Recipients must be registered first
Spectrum’s shared line won’t deliver to a number the project hasn’t registered.POST /platform-links/imessage/connect registers the number (E.164, idempotent) and returns the line assigned to that user. There is no single number to hand out.
Platform behavior
User-facing limits (phone number only, DMs only, plain text, Pro only) are in the iMessage guide. Two details matter when developing:- Outbound sends go through the space:
im.space.create(handle).send(...). There is no REST send endpoint. - Voice notes are unsupported because the webhook payload carries no attachment id for them.
Docker note
The bot image ships onlydist/ plus the three gRPC peer packages the Photon SDK resolves at runtime (nice-grpc, nice-grpc-common, @grpc/grpc-js). tsup bundles their code, but the SDK calls import.meta.resolve() on them before creating its client, so they must also exist on disk — the shared apps/bots/Dockerfile stages them for this bot and fails the build if any is missing.

