TLDR; 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.

About Photon

Photon is a unified messaging API that brings AI agents to the interfaces people already use - iMessage, WhatsApp, Telegram, SMS/RCS, Slack, Discord, and more. It is free to start and scales as your agent grows.

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.

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:

1. 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.

2. 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.

How to Setup

Requires @mastra/[email protected] or later.

Install the adapter:

bash

npm

npm

npm

Create a project on the Photon dashboard and add your credentials:

bash

IMESSAGE_PROJECT_ID=your-project-id
IMESSAGE_PROJECT_SECRET=your-project-secret
IMESSAGE_WEBHOOK_SECRET

IMESSAGE_PROJECT_ID=your-project-id
IMESSAGE_PROJECT_SECRET=your-project-secret
IMESSAGE_WEBHOOK_SECRET

IMESSAGE_PROJECT_ID=your-project-id
IMESSAGE_PROJECT_SECRET=your-project-secret
IMESSAGE_WEBHOOK_SECRET

Add the adapter to your agent:

typescript

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 },
  },
});

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 },
  },
});

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 webhook URL Mastra generates (/api/agents/imessage-agent/channels/imessage/webhook) in the Photon dashboard, set the signing secret it returns, and you're live. 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 and Photon docs.

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.

Get started

Docs: docs.photon.codes

Mastra integration: mastra.ai/integrations/channels/imessage

Repo: github.com/photon-hq/spectrum-ts

Discord: discord.com/invite/4yXmmFPadR