chat-adapter-imessage

Vercel AI SDK：iMessage アダプタースキル

このスキルでは、Vercel AI SDK（Chat SDK）を iMessage に接続する Photon 公式アダプターである chat-adapter-imessage の完全なリファレンスを提供します。

概要

このアダプターはブリッジとして機能し、Vercel AI SDK を使って、iMessage 経由でユーザーとやり取りする AI エージェントやアシスタントを構築できます。内部では、@photon-ai/imessage-kit（セルフホスト可能）と @photon-ai/advanced-imessage-kit（Photon の本番環境向けインフラストラクチャ）を利用します。

主な機能

• 2 つのモード： 開発時は任意の Mac でローカルモードを実行し、Photon の本番 iMessage インフラストラクチャに接続してリモートモードを実行できます。
• 統一されたインターフェース： 基盤となるモードにかかわらず、メッセージの送受信に一貫した API を提供します。
• Vercel AI SDK との統合： chat パッケージの Adapter インターフェースを実装しているため、すぐに使えるソリューションとして利用できます。
• Markdown の変換： AI SDK の Markdown を iMessage 対応のプレーンテキストに自動変換します。

---

セットアップと初期化

インストール

pnpm install chat-adapter-imessage @photon-ai/imessage-kit
# For remote mode, also install the advanced kit
pnpm install @photon-ai/advanced-imessage-kit

createiMessageAdapter(config)

これはメインのエントリーポイントです。iMessageAdapter のインスタンスを作成して設定します。

import { createiMessageAdapter } from 'chat-adapter-imessage';

// Local Mode: Runs on your Mac, uses your iMessage
const localAdapter = createiMessageAdapter({ local: true });

// Remote Mode: Connects to Photon's production servers
const remoteAdapter = createiMessageAdapter({
  local: false,
  serverUrl: process.env.IMESSAGE_SERVER_URL, // Provided by Photon
  apiKey: process.env.IMESSAGE_API_KEY      // Provided by Photon
});

設定（iMessageAdapterConfig）

モード	local	serverUrl	apiKey	説明
ローカル	true	任意	任意	@photon-ai/imessage-kit を使用して macOS 上で実行します。serverUrl と apiKey は無視されます。
リモート	false	必須	必須	@photon-ai/advanced-imessage-kit を使用して Photon のインフラストラクチャに接続します。

Chat との統合

作成したアダプターを、Vercel AI SDK の Chat コンストラクターに渡します。

import { Chat } from 'chat';
import { createiMessageAdapter } from 'chat-adapter-imessage';

const adapter = createiMessageAdapter({ local: true });

const chat = new Chat({
  adapter,
  // ... your other Chat config
});

---

アダプターの主なメソッド

adapter.initialize(chat)

Chat インスタンスから呼び出され、アダプターを接続します。リモートモードでは、このメソッドによって Photon サーバーへの WebSocket 接続も確立されます。

adapter.postMessage(threadId, message)

指定した iMessage スレッドにメッセージを送信します。

• threadId：エンコードされたスレッド識別子。chatGuid の値です（例：iMessage;-;+15551234567）。
• message：AdapterPostableMessage オブジェクト。単純な文字列、または Markdown を含む FormattedContent オブジェクトを指定できます。

const threadId = 'iMessage;-;+15551234567'; // A direct message thread

// Send a simple text message
await adapter.postMessage(threadId, 'Hello from the adapter!');

// Send a message with markdown (will be converted to plain text)
await adapter.postMessage(threadId, {
  markdown: 'Here are the results:\n\n- **Item 1**\n- *Item 2*'
});

adapter.editMessage(threadId, messageId, message)

送信済みのメッセージを編集します。リモートモードでのみサポートされます。

await adapter.editMessage(
  'iMessage;-;+15551234567',
  'p:0/GUID-OF-MESSAGE-TO-EDIT',
  'This is the corrected text.'
);

adapter.deleteMessage(threadId, messageId)

送信済みのメッセージを送信取り消し／削除します。リモートモードでのみサポートされます。

await adapter.deleteMessage(
  'iMessage;-;+15551234567',
  'p:0/GUID-OF-MESSAGE-TO-DELETE'
);

adapter.react(threadId, messageId, emoji)

メッセージに Tapback／リアクションを追加します。リモートモードでのみサポートされます。

• emoji：標準的な絵文字、または heart、like、laugh のような名前を指定します。

await adapter.react(
  'iMessage;-;+15551234567',
  'p:0/GUID-OF-MESSAGE-TO-REACT-TO',
  '❤️'
);

adapter.startGatewayListener(options)

メッセージを受信するための主要なメソッドです。ローカル SDK とリモート SDK の両方からメッセージを取り込むリスナーを起動し、Chat インスタンスに転送します。

// In your main application file

const adapter = createiMessageAdapter({ local: true });
const chat = new Chat({ adapter });

// Start listening for incoming iMessages
adapter.startGatewayListener();

// Now, messages sent to your iMessage will be processed by the Chat SDK
chat.on('message', (message) => {
  console.log(`[${message.author.userName}]: ${message.text}`);
  // Your AI logic here...
});

adapter.handleWebhook(request)

このメソッドはサポートされていません。 このアダプターは、メッセージの取り込みに従来の Webhook を使用しません。代わりに startGatewayListener() を使用してください。

---

型のリファレンス

iMessageThreadId

デコードされた threadId オブジェクトです。

interface iMessageThreadId {
  chatGuid: string; // e.g., "iMessage;-;+1234567890"
}

iMessageGatewayMessageData

アダプター内部で使用する、正規化されたメッセージオブジェクトです。

interface iMessageGatewayMessageData {
  guid: string;
  text: string | null;
  sender: string;
  senderName: string | null;
  chatId: string;
  isGroupChat: boolean;
  isFromMe: boolean;
  date: string; // ISO 8601
  attachments: iMessageAttachment[];
  source: 'local' | 'remote';
  raw?: unknown; // Original message object from the underlying SDK
}

NativeWebhookPayload

Self-Hosted Kit のネイティブ Webhook 機能を使用する場合に、エンドポイントに送信される JSON ペイロードの形式です。このアダプターはこのペイロードを処理できます。

interface NativeWebhookPayload {
  guid: string;
  text: string | null;
  sender: string;
  chatId: string;
  // ... and other fields from the Basic Kit Message object
}

---

参考資料

1. Vercel AI SDK（Chat）
2. npm の chat-adapter-imessage
3. Photon