跳至主要內容

iMessage

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

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

Webhook URL
「Webhook URL」的直接連結

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

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

使用公開 Mastra 伺服器 URL 作為基底 URL：

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

在 Photon dashboard 註冊此 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 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 等私有位址，也不會經過重新導向。進行本機開發時，請依照頻道總覽使用 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