Guide
Connect iMessage Without Owning a Mac
Every other way to put an agent on iMessage needs a Mac you keep signed in and switched on forever. Photon is a managed service that holds the Apple side for you, so a hosted agent can have an iMessage line of its own.
Why This Route Exists
Apple has no bot API for iMessage. The usual workaround is to run a bridge on a real Mac signed into your Apple account — that is what our iMessage guide covers, and it is the reason iMessage cannot run from a hosted Linux container the way Telegram or Discord can.
Photon takes a different approach. It runs the Apple line allocation and abuse-prevention layer as a service, and your agent talks to Photon instead of to a Mac. No hardware of yours stays online, and there is no webhook or public URL to expose, because the connection is a long-lived stream the agent opens outward.
What You Get
On the free tier your agent draws from Photon's shared line pool. Different people may see different sending numbers, but each individual conversation keeps a stable number, so a given contact always sees the same thread. The paid Business tier assigns one dedicated number that everybody sees.
Free quotas at the time of writing are 5,000 messages per server per day and 50 new conversation initiations per shared line per day. That is generous for a personal assistant and tight for anything that cold-messages people.
One limit worth knowing up front: the agent can send images, voice notes, video and documents, but inbound attachments arrive as filename and type only. If someone sends your agent a photo, it knows a photo arrived and cannot read the contents yet.
What Setup Needs
Three things, none of them Apple hardware:
- A Photon account at app.photon.codes.
- A phone number that can receive iMessage, used once to bind the account.
- Node 18.17 or newer, which hosted instances already have.
The agent runs a small helper process alongside itself to hold the connection open. It is supervised automatically once configured — there is nothing to keep alive by hand.
Setting It Up on a Hosted Instance
This one is not self-serve yet. The Photon integration ships inside the Hermes agent build we run, but the single-command setup flow that automates the account linking belongs to a newer build than the one currently deployed across our fleet. On today's image the pieces are present and the linking has to be done by hand, including a step that writes into a system directory your instance user cannot modify.
So the honest instruction is: open support from your dashboard, say you want iMessage through Photon, and we will do the linking on your instance. You will need to have created the Photon account and have the phone number to hand, because that part is yours and we should not do it for you.
We would rather tell you that than publish a command list that fails halfway through on the build you are actually running.
Who Is Allowed to Message It
By default an unknown number that texts your line gets a pairing code, and nothing else happens until you approve that code. This is the same pairing model every other channel uses, and it is the setting to keep for a personal assistant.
You can instead pre-approve a fixed list of phone numbers, in which case unknown senders are ignored silently rather than offered a code — an explicit allowlist is read as a deliberate decision to keep everyone else out. There is an open-to-everyone setting as well; it exists for development and is a poor idea on a line that reaches an agent with real tools.
Group Chats
Out of the box the agent answers every message it is authorised to see, which in a busy group chat is too much. Mention gating makes group messages opt-in: the agent stays quiet unless something in the message matches its wake word, while direct messages keep working normally. If you have renamed your agent, the wake pattern can be changed to match.
Troubleshooting
- No line assigned. The account exists but Photon has not provisioned a number for it yet. This is the normal state immediately after signup and resolves on setup.
- The helper process will not start. Its dependencies were never installed, which is the manual step described above.
- Messages arrive but nothing happens. The sender is not approved. Check for a pending pairing code before assuming the connection is broken.
- Your agent got an image and ignored it. Expected today — inbound attachments are metadata only.
Alternatives
If you already own a Mac that is always on, the direct iMessage route costs nothing extra and gives you full fidelity. Photon is the answer when you do not want to own that Mac. If iMessage itself is not the requirement and you just want texting, two-way SMS reaches every phone regardless of platform.
Need a Hand?
Message support from your dashboard. For this one that is the intended path rather than a fallback.