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

# iMessage

iMessage 頻道可讓 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 instance 上註冊 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 路徑，以及 `requestContext` 上的 `platform` 值。

`toolDisplay: 'text'` 會以文字描述訊息中的 Tool 呼叫，因為 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()`，包括第一次使用時從秘密儲存區解析專案 ID 與 secret 的 `credentials` 函式。

## Webhook URL

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

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

使用公開 Mastra 伺服器 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 一次。Adapter 會驗證每次傳遞的簽章，並拒絕不相符的請求。Webhook 僅適用於託管模式。

Photon 會以 backoff 重試失敗的傳遞，且至少傳遞一次，因此同一則訊息可能送達兩次。Chat SDK 會使用頻道 state adapter 捨棄重複項目，而 Mastra 預設會將這些去重 key 保存在記憶體中。這足以涵蓋單一、長時間執行的伺服器。

重新啟動後，重複訊息仍可能送達 Agent；在 serverless 環境中，重試也可能被路由至不同 instance。請在 `channels.state` 傳入共享的 state adapter，讓去重 key 在所有 instance 上都可見。請一併安裝下列套件：

**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` 等私有位址，也不會經過重新導向。進行本機開發時，請依照[頻道總覽](https://mastra.zisheng.pro/zh-TW/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-TW/docs/capabilities/channels/overview)。

## 相關內容

- [頻道總覽](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/overview)
- [更多平台](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/other-adapters)