跳到主要内容

iMessage

iMessage Channels 让 Mastra Agent 能够接收来自 iMessage 的私信和群组消息。Mastra 负责 Agent 接线、webhook 路由和 Gateway 监听器；Photon iMessage 适配器文档则介绍号码配置、凭据和 webhook 注册。

安装适配器
安装适配器的直接链接

安装 Photon iMessage 适配器：

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

Agent 配置
Agent 配置的直接链接

将 createiMessageAdapter() 添加到 Agent 的 channels.adapters 对象：

src/mastra/agents/imessage-agent.ts
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: 'openai/gpt-5.6-sol',
  channels: {
    adapters: {
      imessage: {
        adapter: createiMessageAdapter(),
        toolDisplay: 'text',
      },
    },
    threadContext: { maxMessages: 0 },
  },
})

在 Mastra 实例上注册该 Agent：

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { imessageAgent } from './agents/imessage-agent'

export const mastra = new Mastra({
  agents: { imessageAgent },
})

使用 imessage 作为适配器键。Mastra 会根据该键推导 webhook 路径以及 requestContext 上的 platform 值。

由于 iMessage 没有用于批准和拒绝操作的交互式卡片，toolDisplay: 'text' 会在消息中描述 Tool 调用。threadContext: { maxMessages: 0 } 会跳过 Agent 首次在群聊中被提及时由 Mastra 执行的平台历史记录查询，因为该适配器无法完成这项查询。这两项设置覆盖了默认值；这些默认值假设平台具备 iMessage 所不支持的功能。

适配器设置
适配器设置的直接链接

按照 Photon iMessage 适配器文档完成 iMessage 专用设置，包括号码配置、托管与自托管模式，以及 webhook 注册。适配器会根据你设置的环境变量选择模式。

使用托管服务时，请在 app.photon.codes 创建项目并使用项目凭据：

.env
IMESSAGE_PROJECT_ID=your-project-id
IMESSAGE_PROJECT_SECRET=your-project-secret
IMESSAGE_WEBHOOK_SECRET=your-webhook-signing-secret

使用自托管 Server 时，请将适配器指向其 gRPC 地址，格式为 host:port。适配器会移除所有 URL scheme，并向不含端口的主机追加 :443：

.env
IMESSAGE_SERVER_URL=imessage.example.com:443
IMESSAGE_API_KEY=your-server-token
IMESSAGE_PHONE=+15551234567

IMESSAGE_PHONE 是可选项，用于在自托管 Server 拥有多个号码时路由消息。你也可以直接将这些值传给 createiMessageAdapter()，包括一个在首次使用时从 secret store 解析项目 ID 和 secret 的 credentials 函数。

Webhook URL
Webhook URL的直接链接

Mastra 根据 Agent ID 和适配器键生成 iMessage webhook 路由：

/api/agents/imessage-agent/channels/imessage/webhook

使用公开的 Mastra Server URL 作为基础 URL：

https://your-app.example.com/api/agents/imessage-agent/channels/imessage/webhook

在 Photon dashboard 中注册此 URL，然后将返回的签名 secret 设置为 IMESSAGE_WEBHOOK_SECRET。该 secret 只会在注册时显示一次。适配器会验证每次投递的签名，并拒绝不匹配的请求。Webhook 仅在托管模式下可用。

Photon 会以退避策略重试失败的投递，并保证至少投递一次，因此同一条消息可能到达两次。Chat SDK 使用 Channel state 适配器丢弃重复消息，而 Mastra 默认会将这些去重键保存在内存中。这足以覆盖单个长时间运行的 Server。

Server 重启后，重复消息仍可能到达 Agent；在 serverless 环境中，重试也可能被路由到不同实例。请在 channels.state 上传入共享 state 适配器，使去重键在所有位置均可见。将它与适配器一起安装：

npm install @chat-adapter/state-redis

createRedisState() 会读取 REDIS_URL 环境变量：

src/mastra/agents/imessage-agent.ts
import { createRedisState } from '@chat-adapter/state-redis'

channels: {
  adapters: {
    imessage: {
      adapter: createiMessageAdapter(),
      toolDisplay: 'text',
    },
  },
  threadContext: { maxMessages: 0 },
  state: createRedisState(),
},

这对于有副作用的 Tool 尤其重要，因为重复处理同一条消息会被用户察觉。

备注

Photon 只向公开 HTTPS 端点投递。它不会向 http://、localhost 等私有地址或重定向后的地址投递。本地开发时，请按照 Channels 概览中的说明使用隧道。

Gateway 监听器
Gateway 监听器的直接链接

适配器可以保持开放连接并实时流式传输消息，而不是通过 webhook 接收消息。托管和自托管模式都支持这种方式。

Mastra 会在初始化期间启动此监听器，并在连接中断后重新连接，因此长时间运行的 Server 无需 cron job 或额外路由。使用 webhook 时，可在适配器配置中设置 gateway: false 将其关闭：

src/mastra/agents/imessage-agent.ts
imessage: {
  adapter: createiMessageAdapter(),
  toolDisplay: 'text',
  gateway: false,
},

在 serverless 平台上应优先使用 webhook。Gateway 监听器需要持续存活的进程。请参阅 Serverless 部署。

On this page