본문으로 건너뛰기

아이메시지

iMessage 채널을 사용하면 Mastra Agent가 iMessage에서 직접 메시지와 그룹 메시지를 받을 수 있습니다. Mastra는 Agent 연결, 웹훅 경로 및 게이트웨이 수신기를 처리합니다. Photon iMessage 어댑터 문서에서는 번호 프로비저닝, 자격 증명 및 웹후크 등록을 다룹니다.

어댑터 설치
어댑터 설치에 대한 직접 링크

Photon iMessage 어댑터를 설치합니다:

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를 사용하세요. Mastra는 이 키에서 웹훅 경로와 requestContext의 platform 값을 파생합니다. iMessage에는 승인 및 거부 동작을 위한 대화형 카드가 없으므로 toolDisplay: 'text'는 메시지의 Tool 호출을 설명합니다. threadContext: { maxMessages: 0 }은 그룹 채팅에서 Agent가 처음 언급될 때 Mastra가 수행하는 플랫폼 기록 조회를 건너뜁니다. 이 조회는 어댑터에서 수행할 수 없습니다. 두 설정 모두 iMessage에 없는 플랫폼 기능을 전제로 하는 기본값을 재정의합니다.

어댑터 설정
어댑터 설정에 대한 직접 링크

번호 프로비저닝, 호스팅 및 자체 호스팅 모드, 웹훅 등록을 포함한 iMessage 관련 설정은 Photon iMessage 어댑터 문서를 따르세요. 어댑터는 설정한 환경 변수에 따라 모드를 선택합니다. 호스팅 서비스의 경우 app.photon.codes에서 프로젝트를 생성하고 프로젝트 자격 증명을 사용하세요.

.env
IMESSAGE_PROJECT_ID=your-project-id
IMESSAGE_PROJECT_SECRET=your-project-secret
IMESSAGE_WEBHOOK_SECRET=your-webhook-signing-secret

자체 호스팅 서버의 경우 host:port 형식의 gRPC 주소로 어댑터를 연결하세요. 어댑터는 URL 스킴을 제거하고 포트가 없는 호스트에는 :443을 추가합니다.

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

IMESSAGE_PHONE은 선택 사항이며 자체 호스팅 서버에 번호가 여러 개 있을 때 메시지를 라우팅합니다. 이 값을 createiMessageAdapter()에 직접 전달할 수도 있으며, 최초 사용 시 비밀 저장소에서 프로젝트 ID와 비밀을 해석하는 credentials 함수도 전달할 수 있습니다.

웹훅 URL
웹훅 URL에 대한 직접 링크

Mastra는 Agent ID 및 어댑터 키에서 iMessage 웹후크 경로를 생성합니다.

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

공개 Mastra 서버 URL을 기본 URL로 사용하십시오.

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

이 URL을 Photon 대시보드에 등록한 다음 반환된 서명 비밀을 IMESSAGE_WEBHOOK_SECRET으로 설정하세요. 비밀은 등록할 때 한 번만 표시됩니다. 어댑터는 모든 전달의 서명을 검증하고 일치하지 않는 요청을 거부합니다. 웹훅은 호스팅 모드에서만 사용할 수 있습니다. Photon은 백오프를 통해 실패한 전달을 재시도하고 최소한 한 번 전달하므로 동일한 메시지가 두 번 도착할 수 있습니다. Chat SDK는 채널 상태 어댑터를 사용하여 반복을 삭제하고 Mastra의 기본값은 해당 중복 제거 키를 Memory에 유지합니다. 여기에는 단일 장기 실행 서버가 포함됩니다.

재시작 후 중복 요청이 Agent에 도달하거나 재시도가 다른 인스턴스로 라우팅될 수 있는 서버리스 환경에서는 공유 상태 어댑터를 channels.state에 전달하여 중복 제거 키를 모든 곳에서 확인할 수 있게 하세요. 어댑터와 함께 하나를 설치하세요.

npm install @chat-adapter/state-redis

createRedisState()읽는다REDIS_URL environment variable:

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와 같은 비공개 주소 또는 리디렉션을 통해서는 전달하지 않습니다. 로컬 개발에는 채널 개요에 설명된 터널을 사용하세요.

게이트웨이 리스너
게이트웨이 리스너에 대한 직접 링크

어댑터는 웹후크를 수신하는 대신 열린 연결을 유지하고 메시지를 실시간으로 스트리밍할 수 있습니다. 이는 호스팅 모드와 자체 호스팅 모드 모두에서 작동합니다.

Mastra는 초기화 중 이 리스너를 시작하고 연결이 끊기면 다시 연결하므로 장기 실행 서버에서는 크론 작업이나 추가 경로가 필요하지 않습니다. 웹훅을 사용할 때 이 기능을 끄려면 어댑터 구성에 gateway: false를 설정하세요.

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

서버리스 플랫폼에서는 웹후크를 선호합니다. 게이트웨이 수신기에는 활성 상태로 유지되는 프로세스가 필요합니다. 보다Serverless deployment.

On this page