Introducing iMessage Support for Mastra Agents

Your Mastra agents can now send and receive messages using iMessage on iPhone, iPad, or Mac. The Photon chat adapter enables direct and group chat messages and uses your agent's webhook URL to handle two-way communication.

iMessage conversations have a limited surface area available to help you debug or monitor agent behavior. Mastra's observability system provides visibility into each trace, letting you inspect and debug each run.

Agent interactions differ from app to app. Some conversations are more suited to mobile chat interfaces, others to desktop applications. Choosing the most suitable interface can enhance user experience. iMessage joins Mastra's existing channel adapters: Slack, Discord, WhatsApp, Microsoft Teams, and more, letting you choose the right UI for your users.

Delivery reliability varies by channel. Photon retries failed messages so duplicate deliveries can occasionally occur. Mastra automatically dedupes using in-memory keys, which persist in long-running instances but can be lost in serverless environments. To persist dedupe keys across cold starts, restarts, or crashes, add createRedisState() to your agent's channels.state.

Get started

Install the iMessage adapter:

npm install @photon-ai/chat-adapter-imessage

Add createiMessageAdapter() to your agent's channels.adapters object:

import { Agent } from "@mastra/core/agent";
import { createiMessageAdapter } from "@photon-ai/chat-adapter-imessage";
 
export const conciergeAgent = new Agent({
  id: "concierge-agent",
  name: "Concierge Agent",
  description: "Handles restaurant bookings over iMessage",
  instructions: /* ... */,
  model: "anthropic/claude-sonnet-5",
  channels: {
    adapters: {
      imessage: {
        adapter: createiMessageAdapter(),
        toolDisplay: "hidden",
        gateway: false
      }
    }
  }
});

• toolDisplay: "hidden" — hides tool call details from message output
• gateway: false — disables the gateway listener when using webhooks

For more information and full configuration options, see:

• iMessage
• Channels overview