chat-sdk

Chat SDK

Slack、Teams、Google Chat、Discord、Telegram、GitHub、Linear、WhatsApp に対応する、チャットボット構築用の統合 TypeScript SDK です。ボットのロジックを一度記述するだけで、あらゆるプラットフォームにデプロイできます。

公開済みのソースから始める

ユーザーのプロジェクトに Chat SDK がインストールされている場合は、node_modules に含まれる公開ファイルを確認してください。

node_modules/chat/docs/                    # bundled docs
node_modules/chat/dist/index.d.ts          # core API types
node_modules/chat/dist/jsx-runtime.d.ts    # JSX runtime types
node_modules/chat/docs/contributing/       # adapter-authoring docs
node_modules/chat/docs/guides/             # framework/platform guides

以下のパスのいずれかが存在しない場合、そのパッケージはまだプロジェクトにインストールされていません。

コードを書く前に、以下を読んでください。

• node_modules/chat/docs/getting-started.mdx — インストールとセットアップ
• node_modules/chat/docs/usage.mdx — Chat の設定とライフサイクル
• node_modules/chat/docs/handling-events.mdx — イベントのルーティングとハンドラー
• node_modules/chat/docs/threads-messages-channels.mdx — スレッド／チャンネル／メッセージのモデル
• node_modules/chat/docs/posting-messages.mdx — メッセージの投稿、編集、削除、スケジュール
• node_modules/chat/docs/streaming.mdx — AI SDK との統合とストリーミングの動作
• node_modules/chat/docs/cards.mdx — JSX カード
• node_modules/chat/docs/actions.mdx — ボタン／選択操作
• node_modules/chat/docs/modals.mdx — モーダルの送信／クローズのフロー
• node_modules/chat/docs/slash-commands.mdx — スラッシュコマンドのルーティング
• node_modules/chat/docs/direct-messages.mdx — DM の動作と openDM()
• node_modules/chat/docs/files.mdx — 添付ファイル／アップロード
• node_modules/chat/docs/state.mdx — 永続化、ロック、重複排除
• node_modules/chat/docs/adapters.mdx — クロスプラットフォーム機能マトリックス
• node_modules/chat/docs/api/chat.mdx — 正確な Chat API
• node_modules/chat/docs/api/thread.mdx — 正確な Thread API
• node_modules/chat/docs/api/message.mdx — 正確な Message API
• node_modules/chat/docs/api/modals.mdx — モーダルの要素とイベントの詳細

使用する特定のアダプターまたは状態パッケージについては、node_modules 内にインストールされたパッケージの dist/index.d.ts のエクスポート内容を確認してください。

クイックスタート

import { Chat } from "chat";
import { createSlackAdapter } from "@chat-adapter/slack";
import { createRedisState } from "@chat-adapter/state-redis";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    slack: createSlackAdapter(),
  },
  state: createRedisState(),
  dedupeTtlMs: 600_000,
});

bot.onNewMention(async (thread) => {
  await thread.subscribe();
  await thread.post("Hello! I'm listening to this thread.");
});

bot.onSubscribedMessage(async (thread, message) => {
  await thread.post(`You said: ${message.text}`);
});

主な概念

• Chat — アダプター、ルーティング、ロック、状態を調整するメインのエントリーポイント
• Adapters — Slack、Teams、Google Chat、Discord、Telegram、GitHub、Linear、WhatsApp 向けのプラットフォーム固有の統合
• State adapters — サブスクリプション、ロック、重複排除、スレッド状態の永続化
• Thread — post()、stream()、subscribe()、setState()、startTyping() を使用する会話のコンテキスト
• Message — text、formatted、添付ファイル、作成者情報、プラットフォームの raw を含む正規化されたコンテンツ
• Channel — スレッドとトップレベルの投稿を格納するコンテナー

イベントハンドラー

ハンドラー	トリガー
onNewMention	サブスクライブされていないスレッドでボットが @ メンションされた
onDirectMessage	サブスクライブされていない DM スレッドで新しい DM が届いた
onSubscribedMessage	サブスクライブ済みのスレッドでメッセージが届いた
onNewMessage(regex)	サブスクライブされていないスレッドで正規表現に一致した
onReaction(emojis?)	絵文字が追加または削除された
onAction(actionIds?)	ボタンのクリック、選択／ラジオ操作
onModalSubmit(callbackId?)	モーダルフォームが送信された
onModalClose(callbackId?)	モーダルが閉じられた／キャンセルされた
onSlashCommand(commands?)	スラッシュコマンドが呼び出された
onAssistantThreadStarted	Slack のアシスタントスレッドが開かれた
onAssistantContextChanged	Slack のアシスタントコンテキストが変更された
onAppHomeOpened	Slack の App Home が開かれた
onMemberJoinedChannel	Slack のメンバーがチャンネルに参加したイベント

ハンドラーを設定する前に、node_modules/chat/docs/handling-events.mdx、node_modules/chat/docs/actions.mdx、node_modules/chat/docs/modals.mdx、node_modules/chat/docs/slash-commands.mdx を読んでください。onDirectMessage の動作については、node_modules/chat/docs/direct-messages.mdx に記載されています。

ストリーミング

任意の AsyncIterable<string> を thread.post() または thread.stream() に渡します。AI SDK では、ステップの境界を保持できるよう、利用可能な場合は result.textStream より result.fullStream を優先してください。

import { ToolLoopAgent } from "ai";

const agent = new ToolLoopAgent({ model: "anthropic/claude-4.5-sonnet" });

bot.onNewMention(async (thread, message) => {
  const result = await agent.stream({ prompt: message.text });
  await thread.post(result.fullStream);
});

主な詳細：

• streamingUpdateIntervalMs は、投稿と編集によるフォールバックの間隔を制御します
• fallbackStreamingPlaceholderText のデフォルト値は "..." です。無効にするには null を設定します
• 構造化された StreamChunk のサポートは Slack のみです。それ以外のアダプターはテキスト以外のチャンクを無視します

カードとモーダル（JSX）

tsconfig.json で jsxImportSource: "chat" を設定します。

カードコンポーネント：

• Card、CardText、Section、Fields、Field、Button、CardLink、LinkButton、Actions、Select、SelectOption、RadioSelect、Table、Image、Divider

モーダルコンポーネント：

• Modal、TextInput、Select、SelectOption、RadioSelect

await thread.post(
  <Card title="Order #1234">
    <CardText>Your order has been received.</CardText>
    <Actions>
      <Button id="approve" style="primary">Approve</Button>
      <Button id="reject" style="danger">Reject</Button>
    </Actions>
  </Card>
);

アダプター一覧

公式プラットフォームアダプター

プラットフォーム	パッケージ	ファクトリー
Slack	@chat-adapter/slack	createSlackAdapter
Microsoft Teams	@chat-adapter/teams	createTeamsAdapter
Google Chat	@chat-adapter/gchat	createGoogleChatAdapter
Discord	@chat-adapter/discord	createDiscordAdapter
GitHub	@chat-adapter/github	createGitHubAdapter
Linear	@chat-adapter/linear	createLinearAdapter
Telegram	@chat-adapter/telegram	createTelegramAdapter
WhatsApp Business Cloud	@chat-adapter/whatsapp	createWhatsAppAdapter

公式ステートアダプター

ステートバックエンド	パッケージ	ファクトリー
Redis	@chat-adapter/state-redis	createRedisState
ioredis	@chat-adapter/state-ioredis	createIoRedisState
PostgreSQL	@chat-adapter/state-pg	createPostgresState
メモリ	@chat-adapter/state-memory	createMemoryState

コミュニティアダプター

• chat-state-cloudflare-do
• @beeper/chat-adapter-matrix
• chat-adapter-imessage
• @bitbasti/chat-adapter-webex
• @resend/chat-sdk-adapter
• chat-adapter-baileys

今後追加予定のプラットフォーム

• Instagram
• Signal
• X
• Messenger

カスタムアダプターの構築

まず、以下の公開ドキュメントを読んでください：

• node_modules/chat/docs/contributing/building.mdx
• node_modules/chat/docs/contributing/testing.mdx
• node_modules/chat/docs/contributing/publishing.mdx

以下も確認してください：

• node_modules/chat/dist/index.d.ts — Adapter と関連インターフェース
• node_modules/@chat-adapter/shared/dist/index.d.ts — 共通のエラーとユーティリティ
• インストール済みの公式アダプターの dist/index.d.ts ファイル — 設定と API のリファレンス実装

カスタムアダプターには、リクエストの検証、Webhook の解析、メッセージ／スレッド／チャンネルの操作、ID のエンコード／デコード、フォーマット変換機能が必要です。chat の BaseFormatConverter と、@chat-adapter/shared の共通ユーティリティを使用してください。

Webhook の設定

登録された各アダプターは bot.webhooks.<name> を公開します。これらを HTTP フレームワークのルートに直接接続してください。フレームワークごとのルートパターンについては、node_modules/chat/docs/guides/slack-nextjs.mdx と node_modules/chat/docs/guides/discord-nuxt.mdx を参照してください。