Connect Hermes to iMessage with Photon

Photon gives Hermes an iMessage channel without requiring a self-hosted Mac relay. A supervised Node sidecar holds a persistent gRPC connection to Photon, while the Python gateway talks to that sidecar over loopback. No public URL or inbound webhook is required.

Understand the service model

Photon's shared-line tier can assign different sending lines across recipients, while each conversation remains stable. A dedicated business line provides a consistent number. Start with the managed shared-line path unless the use case requires one public identity.

Run hermes gateway setup and choose Photon, or use hermes photon setup --phone <your-number>. Setup handles device login, project provisioning, phone registration, sidecar dependencies, and the assigned iMessage line. Node.js 18.17 or newer must be available.

Setup checklist

Confirm a supported Node.js version is on PATH.
Complete Photon device authorization.
Record the assigned iMessage line without publishing credentials.
Use DM pairing or a narrow E.164 allowlist.
Require wake-word mentions in groups when appropriate.
Keep the gateway running for cron and standalone sends.

Pitfalls

Shared lines cannot initiate a brand-new conversation until the recipient messages first. Inbound attachment bytes are not yet available even though metadata is visible; do not promise inbound file analysis on this path. A healthy Photon account does not prove the local sidecar is running. Immutable installations may place sidecar dependencies in a writable Hermes data directory.

Verification steps

Run hermes photon status and confirm credentials, Node, and sidecar dependencies are healthy.
Start the gateway and verify the sidecar health message.
Text the assigned line from an approved number and confirm one reply.
Test an unknown number and verify pairing or silent denial matches policy.
Restart the gateway and confirm the sidecar runtime record is recreated.

See the official Photon iMessage guide for current quotas, media support, sidecar behavior, and authorization options.