QQ

公式 Bot API を使用して PRX を QQ に接続し、プライベートメッセージ、グループチャット、ギルド、メディア添付ファイルをサポートします。

前提条件

• QQ アカウント（個人またはエンタープライズ）
• QQ Open Platform に登録されたボットアプリケーション
• デベロッパーコンソールから取得した App ID と App Secret
• ボットが承認・公開済み（テスト用にサンドボックスモードが利用可能）

クイックセットアップ

1. QQ ボットの作成

1. QQ Open Platform にアクセスし、QQ アカウントでサインイン
2. 「アプリケーション」に移動して新しいボットアプリケーションを作成
3. ボット名、説明、アバターを入力
4. 「開発設定」で App ID と App Secret をコピー
5. ボットのインテント（受信するメッセージタイプ）を設定
6. テスト用にはサンドボックスモードを有効化（ボットを指定テストギルドに制限）

2. 設定

PRX 設定ファイルに以下を追加:

[channels_config.qq]
app_id = "102012345"
app_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
allowed_users = ["user_openid_1", "user_openid_2"]
sandbox = true

ボットが本番使用に承認されたら sandbox = false に設定します。

3. 検証

prx channel doctor qq

設定リファレンス

フィールド	型	デフォルト	説明
app_id	String	必須	QQ Open Platform デベロッパーコンソールのアプリケーション ID
app_secret	String	必須	デベロッパーコンソールのアプリケーションシークレット
allowed_users	[String]	[]	許可するユーザー OpenID。空 = ペアリングモード。"*" = すべて許可
sandbox	bool	false	true の場合、テスト用のサンドボックスゲートウェイに接続
intents	[String]	["guilds", "guild_messages", "direct_messages"]	サブスクライブするイベントインテント
stream_mode	String	"none"	ストリーミングモード: "none" または "typing"。typing モードでは生成中に入力中インジケーターを送信
interrupt_on_new_message	bool	false	true の場合、同じ送信者からの新しいメッセージが処理中のリクエストをキャンセル
mention_only	bool	false	true の場合、グループまたはギルドチャネルではメンション時のみ応答。DM は常に処理
ack_reactions	bool	継承	グローバル ack_reactions 設定のオーバーライド。未設定の場合は [channels_config].ack_reactions にフォールバック

仕組み

PRX は WebSocket ベースのイベントストリームを使用して QQ Bot API に接続します。接続ライフサイクルは以下の通り:

1. 認証 -- PRX は App ID と App Secret を使用して OAuth2 クライアント資格情報でアクセストークンを取得
2. ゲートウェイ検出 -- ボットが QQ API から WebSocket ゲートウェイ URL をリクエスト
3. セッション確立 -- アクセストークンを使用してゲートウェイへの WebSocket 接続を開設
4. インテントサブスクリプション -- ボットが受信したいイベントタイプを宣言
5. イベントループ -- 受信メッセージが PRX エージェントループにディスパッチされ、返信は REST API で送信

QQ Gateway (WSS) ──► PRX Channel Handler ──► Agent Loop
                                                │
QQ REST API ◄───── Reply with message ◄────────┘

機能

• ギルドとグループメッセージング -- QQ ギルド（チャネル）とグループチャットのメッセージに応答
• ダイレクトメッセージ -- ユーザーとの 1:1 プライベート会話を処理
• ペアリングモード -- 許可ユーザーが未設定の場合のセキュアなワンタイムコードバインディング
• メディア添付ファイル -- 画像、ファイル、リッチメディアカードの送受信をサポート
• Markdown レスポンス -- QQ ボットは返信で Markdown フォーマットのサブセットをサポート
• 確認リアクション -- 有効時に受信メッセージにリアクションで受信確認
• サンドボックスモード -- 本番デプロイ前に分離されたギルド環境でボットをテスト
• 自動トークン更新 -- アクセストークンは期限切れ前に自動更新
• クロスプラットフォーム -- QQ デスクトップ、モバイル、QQ for Linux で動作

メッセージタイプ

QQ Bot API はいくつかのメッセージコンテンツタイプをサポート:

タイプ	方向	説明
テキスト	送受信	プレーンテキストメッセージ、最大 2,048 文字
Markdown	送信	QQ の Markdown サブセットによるフォーマットテキスト
画像	送受信	画像添付ファイル（JPEG、PNG、GIF）
ファイル	受信	ユーザーからのファイル添付
リッチエンベッド	送信	タイトル、説明、サムネイル付きの構造化カードメッセージ
Ark テンプレート	送信	QQ の Ark システムを使用したテンプレートベースのリッチメッセージ

インテント

インテントはボットが受信するイベントを制御します。利用可能なインテント:

インテント	イベント	備考
guilds	ギルドの作成・更新・削除	ギルドメタデータの変更
guild_members	メンバーの追加・更新・削除	昇格した権限が必要
guild_messages	ギルドテキストチャネルのメッセージ	最も一般的なインテント
guild_message_reactions	ギルドでのリアクション追加/削除	絵文字リアクション
direct_messages	ボットとのプライベート DM	常に推奨
group_and_c2c	グループチャットと C2C メッセージ	別途承認が必要
interaction	ボタンクリックとインタラクション	インタラクティブメッセージコンポーネント用

制限事項

• QQ Bot API はリージョン制限あり。ボットは主に中国本土で利用可能
• サンドボックスモードではボットが少数メンバーの単一テストギルドに制限される
• 本番ボットには QQ Open Platform レビューチームの承認が必要
• グループチャットと C2C メッセージングには別途権限申請が必要
• ファイルアップロードは添付ファイルあたり 20 MB に制限
• コンテンツモデレーションは QQ が実施。禁止コンテンツを含むメッセージはサイレントにドロップ
• レート制限あり: ギルドあたり約 5 メッセージ/秒、DM は 2 メッセージ/秒
• ボットは会話を開始できない。ユーザーまたは管理者がまずボットを追加する必要あり

トラブルシューティング

ボットが QQ ゲートウェイに接続できない

• prx channel doctor qq で app_id と app_secret が正しいことを確認
• サンドボックスモードを使用する場合は sandbox = true が設定されていることを確認（サンドボックスと本番は異なるゲートウェイを使用）
• api.sgroup.qq.com と WebSocket ゲートウェイへのアウトバウンド接続がブロックされていないことを確認

ボットは接続するがメッセージを受信しない

• 使用ケースに対して正しい intents が設定されていることを確認
• ギルドチャネルでは、ボットにギルド管理者から「メッセージ受信」権限が付与されている必要がある場合あり
• 送信者の OpenID が allowed_users に含まれていることを確認、または allowed_users = ["*"] を設定

返信が配信されない

• QQ はコンテンツモデレーションを実施。PRX ログで API からの拒否レスポンスを確認
• ボットが対象ギルドまたはグループで「メッセージ送信」権限を持っていることを確認
• DM の返信では、ユーザーがまずボットにメッセージを送信して会話を開いている必要あり

トークン更新の失敗

• デベロッパーコンソールで App Secret がローテーションされた可能性あり。設定を新しいシークレットで更新
• ネットワークの問題でトークン更新が妨げられる場合あり。bots.qq.com への接続を確認

関連ページ

• チャネル概要
• DingTalk -- DingTalk プラットフォーム向けの類似セットアップ
• Lark -- Lark / 飛書向けの類似セットアップ
• セキュリティ: ペアリング -- ワンタイムバインドコードペアリングの詳細