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

# 아이메시지

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

## 어댑터 설치

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

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

## 어댑터 설정

번호 프로비저닝, 호스팅 및 자체 호스팅 모드, 웹훅 등록을 포함한 iMessage 관련 설정은 [Photon iMessage 어댑터 문서](https://github.com/photon-hq/vercel-chat-adapter-imessage)를 따르세요. 어댑터는 설정한 환경 변수에 따라 모드를 선택합니다. 호스팅 서비스의 경우 [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
```

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

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

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

## 웹훅 URL

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

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

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

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

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

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

**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` environment variable:

```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/ko/docs/capabilities/channels/overview)에 설명된 터널을 사용하세요.

## 게이트웨이 리스너

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

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

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

서버리스 플랫폼에서는 웹후크를 선호합니다. 게이트웨이 수신기에는 활성 상태로 유지되는 프로세스가 필요합니다. 보다[Serverless deployment](https://mastra.zisheng.pro/ko/docs/capabilities/channels/overview).

## 관련된

- [채널 개요](https://mastra.zisheng.pro/ko/docs/capabilities/channels/overview)
- [더](https://mastra.zisheng.pro/ko/docs/capabilities/channels/other-adapters)