跳至主要內容

iMessage

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

安裝 adapter
安裝 adapter 的直接連結

安裝 Photon iMessage adapter：

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

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

Adapter 設定
Adapter 設定 的直接連結

請按照 Photon iMessage adapter 文件完成 iMessage 專用設定，包括號碼配置、託管和自行託管模式，以及 webhook 註冊。Adapter 會根據你設定的環境變數選擇模式。

如使用託管服務，請在 app.photon.codes 建立項目，並使用項目憑證：

.env
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：

.env
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
Webhook URL 的直接連結

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

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

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

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

在 Photon dashboard 註冊此 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 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 endpoint。它不會傳送至 http://、localhost 等私有位址，亦不會透過 redirect 傳送。如需在本機開發，請按照 Channels 概覽所述使用 tunnel。

Gateway listener
Gateway listener 的直接連結

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

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

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

在 serverless 平台上，建議使用 webhook。Gateway listener 需要持續運行的 process。請參閱 Serverless 部署。

On this page