Mastra agents can now send and receive iMessages through Photon Spectrum. Install @photon-ai/chat-adapter-imessage, add one adapter to your agent config, and your agent gets a phone number with native presence in the Messages app — on iPhone, iPad, or Mac. No Mac server, no personal Apple ID, no relay.
How Mastra connects to iMessage through Photon Spectrum
A Mastra agent defines its model, tools, memory, and channels in one place. The Photon iMessage adapter connects that agent to Photon Spectrum, which carries incoming and outgoing messages between Mastra and iMessage.
Adding iMessage to an existing Mastra agent is a config change, not a rewrite. The same agent that answers in Slack can answer in Messages.
How to connect a Mastra agent to iMessage
1. Install the adapter
npm install @photon-ai/chat-adapter-imessage
2. Add your Photon credentials
Create a project on the Photon dashboard and add your credentials:
IMESSAGE_PROJECT_ID=your-project-id
IMESSAGE_PROJECT_SECRET=your-project-secret
IMESSAGE_WEBHOOK_SECRET=your-webhook-signing-secret
IMESSAGE_WEBHOOK_SECRET is required when you use webhooks.
3. Add the adapter to your agent
import { Agent } from "@mastra/core/agent";
import { createiMessageAdapter } from "@photon-ai/chat-adapter-imessage";
export const imessageAgent = new Agent({
id: "imessage-agent",
name: "iMessage Agent",
instructions: "Answer questions and help with tasks over iMessage.",
model: "anthropic/claude-sonnet-5",
channels: {
adapters: {
imessage: {
adapter: createiMessageAdapter(),
toolDisplay: "text",
},
},
threadContext: { maxMessages: 0 },
},
});
Register the agent on your Mastra instance:
import { Mastra } from "@mastra/core";
import { imessageAgent } from "./agents/imessage-agent";
export const mastra = new Mastra({
agents: { imessageAgent },
});
Mastra uses the imessage adapter key to derive the webhook path and the platform value available in requestContext.
4. Choose webhooks or the gateway listener
Use webhooks on serverless deployments. Register the public HTTPS URL Mastra generates in the Photon dashboard:
/api/agents/imessage-agent/channels/imessage/webhook
Set the signing secret the dashboard returns, then disable the gateway listener in your adapter configuration:
imessage: {
adapter: createiMessageAdapter(),
toolDisplay: "text",
gateway: false,
},
On a long-running server, you can skip webhooks entirely. The adapter's gateway listener holds a persistent connection and streams messages in real time.
Full configuration options, self-hosted mode, and serverless notes are in the Mastra iMessage docs, Photon iMessage adapter docs, and Photon docs.
Why iMessage is the missing channel for agent frameworks
Most agent frameworks ship channel integrations for Slack, Discord, and Telegram first. That makes sense: those platforms were designed with bots in mind, with official APIs, tokens, and webhooks.
iMessage was never designed as a bot platform — there's no clean path from an agent to the Messages app, and the self-hosted setups that try don't survive a security review or scale past a single line. Fine for a weekend project; not something an enterprise ships — and Mastra is a framework enterprises run in production.
But iMessage is also where the most valuable conversations happen. It's the default surface for every iPhone user. For a concierge agent, a customer-facing assistant, or anything meant to live in someone's daily life, the blue bubble is the product surface.
Photon closes the gap. Our Spectrum API provisions and manages dedicated iMessage lines in the cloud, so your agent runs anywhere and still shows up natively in Messages: typing indicators, images, voice notes, and SMS/RCS fallback when a recipient isn't on iMessage.
Mastra is the specific framework covered here. The broader pattern is the same one its channels system uses: keep the model, tools, memory, and agent behavior in the framework, then add messaging through a channel adapter.
Why Mastra + Photon is a natural fit
We built this iMessage adapter with the Mastra team because Mastra treats channels as a first-class primitive, not an afterthought. A Mastra agent defines its model, tools, memory, and channels in one place, and the framework handles the wiring: webhook routes, message dedup, and thread context — for every channel the same way.
Two things make Mastra a particularly good home for an iMessage agent:
- Channels are declarative.Adding iMessage to an existing Mastra agent is a config change, not a rewrite. The same agent that answers in Slack can answer in Messages, and Mastra derives the webhook route and platform context automatically.
- Observability is built in.iMessage gives you almost no debugging surface — there's no admin console, no message inspector, no event log on the Apple side. Mastra's tracing fills that hole completely: every inbound message becomes a run you can inspect in Mastra Studio, with each tool call, model step, and output visible. For a channel this opaque, that visibility isn't nice-to-have — it's the difference between a demo and something you can operate.
Mastra also handles the sharp edges we know well from running iMessage infrastructure. Photon delivers at-least-once with retries, and Mastra dedupes repeats out of the box. iPhones send read receipts for every agent message, and Mastra recognizes and skips them so your agent never loops on its own replies. These details are exactly what a framework should absorb so builders don't have to.
Demo: "Where's the closest matcha shop?"
To show what this feels like in practice, we texted our Mastra agent a question every San Franciscan has asked at least once:
"Where's the closest matcha shop near us?"
The agent runs on OpenAI with Exa as its deep research tool. It receives the iMessage, kicks off an Exa search to pull and rank nearby matcha spots, and replies in the same thread with the best pick — typing indicator on while it works, just like texting a friend who happens to be very thorough.
On the Mastra side, the entire run shows up as a trace: the inbound message, the Exa research calls, the model's reasoning steps, and the final reply, all inspectable in Studio. When a deep research pipeline takes a few extra seconds, the trace tells you exactly where the time went.
That's the whole loop. A question in Messages, research tools running anywhere you host them, and full visibility into every step — no Mac in the closet.
Agents should live where people already are
Photon is built around a simple belief: the next generation of AI agents shouldn't ask people to come to them. They should meet people in the interfaces they already open a hundred times a day.
Making that real takes collaboration across the ecosystem — frameworks, model providers, and channel infrastructure working together. That's why Photon is free for personal use and independent developers, and why we partner with teams like Mastra to make channels a solved problem rather than a weekend of yak-shaving.
Your Mastra agent runs wherever. Photon brings it to iMessage.
About Photon
Photon is a unified API that brings agents to interfaces like iMessage, WhatsApp, Telegram, Slack, and more. It is free to start, and it scales as your agent grows.
Related reading
- Introducing Spectrum: Agents for the rest of us — How Spectrum connects one agent model to multiple interfaces.
- How to build an iMessage agent in 2026: every approach compared — The broader implementation choices for bringing an agent to iMessage.
- Opt-in traces for reliable Spectrum messaging — Observability and tracing for production message delivery.
Get started
Start building with Photon · View pricing · Contact the Photon team
Docs: docs.photon.codes
Mastra integration: mastra.ai/integrations/channels/imessage
Adapter: github.com/photon-hq/vercel-chat-adapter-imessage
Spectrum: github.com/photon-hq/spectrum-ts
Follow Photon
X / Twitter · LinkedIn · GitHub · Discord · Instagram