> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# iMessage

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

## 安装适配器

安装 Photon iMessage 适配器：

**npm**:

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

**pnpm**:

```bash
pnpm add @photon-ai/chat-adapter-imessage
```

**Yarn**:

```bash
yarn add @photon-ai/chat-adapter-imessage
```

**Bun**:

```bash
bun add @photon-ai/chat-adapter-imessage
```

## Agent 配置

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

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

在 Mastra 实例上注册该 Agent：

```typescript
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 适配器文档](https://github.com/photon-hq/vercel-chat-adapter-imessage)完成 iMessage 专用设置，包括号码配置、托管与自托管模式，以及 webhook 注册。适配器会根据你设置的环境变量选择模式。

使用托管服务时，请在 [app.photon.codes](https://app.photon.codes) 创建项目并使用项目凭据：

```bash
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`：

```bash
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

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

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

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

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

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

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

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

**npm**:

```bash
npm install @chat-adapter/state-redis
```

**pnpm**:

```bash
pnpm add @chat-adapter/state-redis
```

**Yarn**:

```bash
yarn add @chat-adapter/state-redis
```

**Bun**:

```bash
bun add @chat-adapter/state-redis
```

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

```typescript
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 概览](https://mastra.zisheng.pro/docs/capabilities/channels/overview)中的说明使用隧道。

## Gateway 监听器

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

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

```typescript
imessage: {
  adapter: createiMessageAdapter(),
  toolDisplay: 'text',
  gateway: false,
},
```

在 serverless 平台上应优先使用 webhook。Gateway 监听器需要持续存活的进程。请参阅 [Serverless 部署](https://mastra.zisheng.pro/docs/capabilities/channels/overview)。

## 相关内容

- [Channels 概览](https://mastra.zisheng.pro/docs/capabilities/channels/overview)
- [更多适配器](https://mastra.zisheng.pro/docs/capabilities/channels/other-adapters)