Skip to main content
The iMessage bot receives messages through Photon Spectrum, which bridges iMessage to a signed webhook, so you need a publicly reachable URL. Do the shared bot setup first. You also need:
  • 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

  1. Create a Spectrum project and enable the iMessage platform
  2. Copy your project ID and project secret — together they are the Basic-auth credentials for Spectrum’s management API
  3. Register a webhook pointing at your bot’s /webhook endpoint (the bot listens on port 3204 by default; override with BOT_SERVER_PORT):
  4. Copy the webhook secret: Spectrum signs every request, and the SDK rejects requests whose X-Spectrum-Signature does not verify
A project fans every message.received event out to all registered webhooks. Delete stale entries (an old tunnel URL, for example) or every inbound message will also fire at a dead endpoint, and repeated failures can get a webhook disabled.

Step 2: Add the credentials

In apps/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 only dist/ 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.

Troubleshooting