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

# iMessage

iMessage channel 讓 Mastra Agent 接收來自 iMessage 的直接訊息和群組訊息。Mastra 會處理 Agent 連接配置、webhook 路由和 gateway listener；Photon iMessage adapter 文件則涵蓋號碼配置、憑證和 webhook 註冊。

## 安裝 adapter

安裝 Photon iMessage adapter：

**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` 作為 adapter key。Mastra 會根據此 key 產生 webhook 路徑和 `platform` 在 `requestContext` 上的值。

`toolDisplay: 'text'` 會在訊息中描述 Tool call，因為 iMessage 沒有可用於 Approve 和 Deny 操作的互動式卡片。`threadContext: { maxMessages: 0 }` 會略過 Agent 首次在群組對話中被提及時 Mastra 執行的平台歷史記錄查詢，因為 adapter 無法執行此查詢。兩項設定均會覆寫原有預設值，這些預設值假設平台具備 iMessage 所欠缺的功能。

## Adapter 設定

請按照 [Photon iMessage adapter 文件](https://github.com/photon-hq/vercel-chat-adapter-imessage)完成 iMessage 專用設定，包括號碼配置、託管和自行託管模式，以及 webhook 註冊。Adapter 會根據你設定的環境變數選擇模式。

如使用託管服務，請在 [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
```

如使用自行託管的伺服器，請將 adapter 指向其 gRPC 位址，格式為 `host:port`。Adapter 會移除所有 URL scheme，並在只有 host 的情況下附加 `:443`：

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

`IMESSAGE_PHONE` 是選填項目，在自行託管的伺服器有多個號碼時用於路由訊息。你亦可將這些值直接傳遞至 `createiMessageAdapter()`，包括在首次使用時從 secret store 解析項目 ID 和 secret 的 `credentials` 函式。

## Webhook URL

Mastra 會根據 Agent ID 和 adapter key 產生 iMessage webhook 路由：

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

以 Mastra 伺服器的公開 URL 作為 base URL：

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

在 [Photon dashboard](https://app.photon.codes) 註冊此 URL，然後將系統傳回的 signing secret 設為 `IMESSAGE_WEBHOOK_SECRET`。Secret 只會在註冊時顯示一次。Adapter 會驗證每次傳送的 signature，並拒絕不相符的請求。Webhook 僅適用於託管模式。

Photon 會以退避機制重試傳送失敗的訊息，並保證至少傳送一次，因此同一則訊息可能會送達兩次。Chat SDK 會使用 channel state adapter 捨棄重複訊息，而 Mastra 的預設設定會將這些去重 key 保存在記憶體中。這足以涵蓋單一長時間運行的伺服器。

伺服器重新啟動後，重複訊息仍可能送達 Agent；在 serverless 環境中，重試亦可能被路由至另一個實例。請在 `channels.state` 傳入共用 state adapter，讓所有實例均可存取去重 key。與 adapter 一併安裝：

**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 endpoint。它不會傳送至 `http://`、`localhost` 等私有位址，亦不會透過 redirect 傳送。如需在本機開發，請按照 [Channels 概覽](https://mastra.zisheng.pro/zh-HK/docs/capabilities/channels/overview)所述使用 tunnel。

## Gateway listener

Adapter 可保持連線開啟並即時串流訊息，而毋須接收 webhook。託管和自行託管模式均支援此功能。

Mastra 會在初始化期間啟動此 listener，並在連線中斷時重新連線，因此長時間運行的伺服器毋須 cron job 或額外路由。如使用 webhook，請在 adapter 設定中設定 `gateway: false` 以關閉此功能：

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

在 serverless 平台上，建議使用 webhook。Gateway listener 需要持續運行的 process。請參閱 [Serverless 部署](https://mastra.zisheng.pro/zh-HK/docs/capabilities/channels/overview)。

## 相關內容

- [Channels 概覽](https://mastra.zisheng.pro/zh-HK/docs/capabilities/channels/overview)
- [更多](https://mastra.zisheng.pro/zh-HK/docs/capabilities/channels/other-adapters)