ゲームにチャットを統合する方法｜Tencent RTC

# ゲームにチャットを統合する方法｜Tencent RTC

マルチプレイゲームにおいて、インスタントメッセージは一般的な機能要件となり、インスタントチャットは必須の機能と言えます。ゲームプラットフォーム自体には、さまざまなグループタイプやカスタムメッセージタイプ（ゲーム内アイテムの贈与や取引など）、グローバルアクセスなど複雑な要件が含まれます。本ガイドでは、ゲーム内チャットを構築する際に頻繁に発生する要件の実装方法と、想定される問題や考慮事項を整理し、開発者がビジネス面の理解と要件の実装を素早く行えるようにサポートします。

## **事前準備**

### キーを使用して UserSig を計算する

Chat のアカウントシステムでは、ユーザがログインする際に必要となるパスワード（UserSig）は、Chat が提供するキーを用いてサーバーで計算します。詳細については[「UserSig の生成」](https://trtc.io/ja/document/34385)を参照してください。  
開発段階では、クライアント側の開発を止めないよう、[コンソール](https://console.trtc.io/usersig)で `UserSig` を計算することもできます。

### 管理者アカウントを設定する

ゲームのインスタントメッセージを管理するために、管理者（Admin）がゲームにメール告知を送信したり、チーム募集用メッセージを管理したりする場合があります。これらは [Chat のサーバーAPI](https://trtc.io/ja/document/34621) を通して行うことができます。これらのAPIを呼び出すには、[Chat の管理者アカウントを作成](https://trtc.io/login/redirect?s_url=https://console.tencentcloud.com/im/account-management)する必要があります。デフォルトでは `administrator` という UserID を持つアカウントが用意されていますが、必要に応じて複数の管理者アカウントを追加作成できます。上限は5アカウントです。

### コールバックアドレスの設定とコールバックの有効化

ゲーム内のマッチングなどを実装するには、特定のシナリオで Chat バックエンドがビジネス側バックエンドを呼び出す Webhook イベントを利用します。HTTP API をひとつ用意し、[**Webhook 設定**](https://trtc.io/login/redirect?s_url=https://console.tencentcloud.com/im/callback-setting) モジュールにそのアドレスを登録してください。

### クライアント SDK の統合

事前準備が完了したら、Chat クライアント SDK をプロジェクトに組み込みます。要件に合わせてさまざまな統合方法を選択できます。詳しくは [TUIKit の紹介](https://trtc.io/login/redirect?s_url=https://intl.cloud.tencent.com/document/product/1047/34547) を参照してください。

以下では、ゲームに統合すべき Chat の代表的な機能と、実装コードとともにベストプラクティスを説明します。

--------------------------------------------------------------------------------

## **ゲームチャットルーム機能開発ガイド**

### ユーザープロフィール

#### 一般的なユーザープロフィール

ゲームのビジネスで保存されるユーザープロフィールは、大きく「基本情報」と「その他情報」に分けられます。

| 基本情報 | その他情報 |
| --- | --- |
| ユーザー名、性別、生年月日、レベル、ロール、携帯番号など | ゲームで必要となるその他の情報 |

#### プロフィールの保存

ゲームではユーザー数が膨大になるため、大量のユーザーデータを保存することは容易ではありません。Tencent Cloud Chat はユーザープロフィールをホスティングする機能を提供し、包括的なプロフィールソリューションを利用できます。以下では Chat SDK に保存する場合と、ビジネス側サーバーに保存する場合を比較します。

| 項目 | Chat | ビジネス側サーバー |
| --- | --- | --- |
| ストレージ容量 | 自動スケーリング対応 | 容量制限があり、スケールが難しい |
| ユーザープロフィール | 標準フィールドとカスタムフィールドに対応（フィールドの長さや名称に制限あり） | より柔軟にカスタマイズ可能 |
| R/W（読み書き）| サービスAPIとガイドラインが整備済み | 独自開発が必要 |
| API呼び出し制限 | 1秒あたり最大200回まで | 要件に応じて独自実装可能 |
| セキュリティ | リモート災害復旧、地域分散デプロイ対応 | 自前で運用が必要 |

プロフィールの保存・読み書きが可能なだけでなく、Chat にプロフィールをホスティングする利点は以下のとおりです。

1. Chat はリモート災害復旧、地域分散デプロイ、自動スケーリングを備えており、サーバーダウンや多重コピーのプライマリ・セカンダリ切り替え、容量拡張などの複雑な処理をすべて任せられます。  
2. Chat が業界で一般的なビジネスフローを提供しており、ユーザープロフィールのビジネスロジックを気にせずに済みます。  
3. 専門運用体制とチームによって年間99.99%の高品質を保証し、安定性に優れるサービスを提供できます。  
4. 利用しやすいサービスAPIやガイドラインが整備され、サポートも充実しています。

#### Chat でのユーザープロフィール保存方法

Chat の保存方式は、ユーザープロフィール・フレンドプロフィール・拡張データをすべて `Key-Value` フォーマットで扱います。 `Key` は `String` 型で英数字＋アンダースコアのみ、 `Value` は以下の型をサポートします。

| **型**        | **説明**                       |
|---------------|--------------------------------|
| uint64_t      | 整数（カスタムフィールドでは利用不可） |
| string        | 文字列。最大500バイト以内        |
| bytes         | バッファ。最大500バイト以内      |
| string array  | 文字列配列。各文字列は最大500バイトまで。フレンド一覧の `Tag_SNS_IM_Group` でのみ使用可 |

- **ユーザープロフィール**: プロフィールには標準フィールドとカスタムフィールドがあります。カスタムフィールドの詳細は後述の拡張データを参照。[標準プロフィールフィールド](https://trtc.io/document/33520)も合わせて確認ください。  
- **フレンドプロフィール**: 標準のフレンドフィールドとカスタムフレンドフィールドがあります。Chat 上の連絡先リスト（フレンド）は最大3000人まで。標準フィールドは下記のとおりです：

  | **フィールド名**       | **型**   | **説明**             |
  |------------------------|---------|----------------------|
  | Tag_SNS_IM_Group       | Array   | フレンドリスト        |
  | Tag_SNS_IM_Remark      | String  | フレンドのメモ       |
  | Tag_SNS_IM_AddSource   | String  | フレンド追加のきっかけ |
  | Tag_SNS_IM_AddWording  | String  | フレンド追加の言葉    |
  | Tag_SNS_IM_AddTime     | Integer | フレンド追加のタイムスタンプ |

  詳細は[標準フレンドフィールド](https://trtc.io/document/33521)を参照してください。  

- **カスタムプロフィール**: カスタムフィールドを利用する場合、アプリ管理者が [Chat コンソール](https://console.trtc.io/chat/login-message) にログインし、「機能設定」に進んでカスタムプロフィール申請を行います。申請後、5分ほどで有効になります。  

ユーザープロフィール全般の詳細は[「プロフィール管理」](https://trtc.io/document/33520)を、リレーションシップチェーンのカスタムユーザープロフィール管理は[「カスタムフレンドフィールド」](https://trtc.io/document/33521)を参照してください。

#### Chat のユーザープロフィール保存に関する制限

- **サービス機能の制限**  
  - データ保存：文字列またはバッファは500バイト以内  
  - カスタムフィールド：フィールド名は英文字で最大8バイト。値は最大500バイト。
  - フレンド関係：1ユーザーあたり最大3000フレンド  

- **API に関する制限**  
  - アカウント管理：一度に最大100ユーザー名をインポート可。1回のリクエストで最大500ユーザーのステータス照会が可能  
  - その他呼び出し頻度：1秒あたり最大200回  

詳細は[「利用制限」](https://trtc.io/document/34381)も参照してください。

--------------------------------------------------------------------------------

### メールシステム

最近のゲームでは、いわゆる「メール機能」がほぼ必須です。メールにはテキストメッセージだけでなく、ゲーム内アイテムや報酬といった添付を含められます。また、一人のユーザー向けに送信する場合もあれば、複数のユーザーに一斉送信してイベント報酬を配るケースもあります。ここでは、メール受信、メールリスト、未読数表示、全ユーザーへのメール送信、有効期限管理など、多角的な視点からメールシステムの実装方法を説明します。

#### メールの受信と送信

- **プレイヤーがメールを受信する**  
  システムメールの送信が成功し、プレイヤーがオンラインであれば、問題なくメールを受信できます。過去または最新のメールは、メール用の会話（スレッド）からメッセージリストを取得することで取得可能です。また、あらゆる種類の新規メッセージ（テキスト、カスタム、リッチメディアなど）の受信リスナーを追加・削除できます。Unity のサンプルコードは以下のとおりです。

  ```jsx
  // メッセージ受信のイベントリスナーを登録
  TencentIMSDK.AddRecvNewMsgCallback((List<Message> messages, string user_data)=>{
    foreach(Message message in messages)
    {
      foreach (Elem elem in message.message_elem_array)
      {
        // 次の要素をチェック
        if (elem.elem_type == TIMElemType.kTIMElem_Text)
        {
           string text = elem.text_elem_content;
        }
      }
    }
  })
  // `RecvNewMsgCallback` コールバックで新着メッセージを受信
  // メッセージ受信を停止したい場合は `RemoveRecvNewMsgCallback` を呼び出してリスナーを削除：
  // 必要に応じて実施
  ```

  詳細は[Unity - メッセージ受信](https://trtc.io/document/48573)を参照してください。

- **システムがメールを送信する**  
  サーバー側のさまざまなAPIを使って、システムメールを特定ユーザーに送ることができます。主なAPIと特徴は以下のとおりです。

  | API                                                                           | 特徴                                                                                   | 適用シナリオ                                                                                                 |
  |-------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
  | [1対1メッセージを1ユーザーに送信](https://trtc.io/document/34919)             | 指定したアカウントにメッセージを送信。受信者からは sender が admin ではなく、指定したアカウントに見える。 | 特定ユーザーへのメッセージ送信（例：ゲーム報酬メールなど）                                                    |
  | [1対1メッセージを複数ユーザーに送信](https://trtc.io/document/34920)           | 最大500ユーザーまで同時送信可能で、呼び出し頻度は1秒あたり200回。                           | 特定ユーザーのみにメッセージ送信したいが、受信者が多い場合。グループ作成が不要。大量の場合はバッチ送信が必要。     |
  | [グループに通常メッセージを送信](https://trtc.io/document/34959)               | グループにメッセージを送るには、全受信者を同じグループに追加する必要がある。                           | 大人数（コミュニティグループは最大10万人）に送信したい場合                                                       |
  | [全ユーザーにプッシュ通知を送る](https://trtc.io/document/37165)               | アプリ内のすべてのユーザーへプッシュ。ユーザーのタグや属性による条件指定も可能。                    | アプリ内全員、または特定の属性を持つ大多数ユーザーにメッセージを配布したい場合（例：キャンペーンメールなど）     |

  **注**: 「全ユーザーへのプッシュ」は Pro / Pro Plus / Enterprise エディションで利用可能です。[購入](https://trtc.io/document/34577)してコンソールの[「機能設定」→「ログインとメッセージ」→「全員プッシュ」]から有効にする必要があります。

  下記は「グループに通常メッセージを送信」する場合のリクエスト例です。

  ```jsx
  {
      "GroupId": "@TGS#2C5SZEAEF",
      "Random": 8912345, // ランダム数字。5分以内に同じ数字なら同一メッセージ扱い
      "MsgBody": [ // メッセージ本文。要素の配列
          {
              "MsgType": "TIMTextElem", 
              "MsgContent":{
                "Text": "red packet"
              }
          },
          {
              "MsgType": "TIMCustomElem", 
              "MsgContent":{
                "Data": "message",
                "Desc": "notification",
                "Ext": "url",
                "Sound":"dingdong.aiff"
              }
          }
      ]
  }
  ```

  `MsgBody` はテキストやカスタムメッセージを含む配列で、ここに送信したい内容を追加できます。

#### メールリスト

メールの履歴リストはメッセージ履歴と同義です。1対1メッセージの履歴保存、またはグループチャットの履歴保存が該当します。グループチャットする場合は、admin が指定する送信元アカウントと、メールを受け取るユーザーを同一グループに入れることで履歴を管理できます。

**注**:  
- 無料版＆Standard エディション: 7日間保存  
- Pro エディション: 30日間保存  
- Pro Plus / Enterprise エディション: 90日間保存  

Pro / Pro Plus / Enterprise エディションでは保存期間の延長が可能です。詳細は[コンソール](https://trtc.io/login/redirect?s_url=https://console.tencentcloud.com/im)で設定できます。  
履歴メッセージの保存期間拡張は有料オプションとなります。課金情報は[Value-added Service Pricing](https://trtc.io/document/34350)を参照してください。

ネットワークが正常ならクラウド上の最新データを取得し、異常時にはローカルの履歴メッセージを返します。ページング取得も可能。以下は Unity での履歴メールリスト取得サンプルです。

```jsx
// 1対1メッセージの履歴取得
// 初回は `msg_getmsglist_param_last_msg` に `null` を指定
// 2回目以降は前回取得したメッセージの最後を設定
var get_message_list_param = new MsgGetMsgListParam
{
    msg_getmsglist_param_last_msg = LastMessage
};
TIMResult res = TencentIMSDK.MsgGetMsgList(conv_id, TIMConvType.kTIMConv_C2C, get_message_list_param, (int code, string desc, string user_data) => {
    // コールバックロジックを処理
});
```

詳細は[「履歴メッセージ - Unity」](https://trtc.io/document/48871)を参照。

#### 未読メール数

プレイヤーとシステム間のメッセージは1つの会話として扱われ、Chat の「会話未読数」を利用してユーザーに「未読がある」ことを示せます。ユーザーが会話を開いてリストに戻ると未読数がクリアされます。Unity のサンプルコードは以下のとおりです。

```jsx
// 総未読数を取得
TIMResult res = TencentIMSDK.ConvGetTotalUnreadMessageCount((int code, string desc, GetTotalUnreadNumberResult unread, string user_data)=>{
  // 非同期処理
});

// 未読数更新通知
TencentIMSDK.SetConvTotalUnreadMessageCountChangedCallback((int total_unread_count, string user_data)=>{
  // コールバック処理
});

// 全会話の未読数をクリア
TIMResult res = TencentIMSDK.MsgMarkAllMessageAsRead((int code, string desc, string user_data)=>{
  // 非同期処理
});
```

詳細は[「Unity - 会話未読数」](https://trtc.io/document/48846)を参照。

#### 全メンバーへのメール送信

全員へのメール送信とは、ゲーム内すべてのプレイヤーにメールを送ることを指します。Chat はサーバーサイドで「全員プッシュ」機能を提供しています。以下はサンプルコードです。

```jsx
https://console.tim.qq.com/v4/all_member_push/im_push?usersig=xxx&identifier=admin&sdkappid=88888888&random=99999999&contenttype=json
```

サンプルリクエスト：

```jsx
{
    "From_Account": "admin",
    "MsgRandom": 56512,
    "MsgLifeTime": 120, // オフライン保存120秒（2分）
    "MsgBody":[
        {
        "MsgType": "TIMTextElem",
        "MsgContent":{
            "Text": "hi, beauty"
            }
        }
    ]
}
```

全員プッシュでは `MsgLifeTime`（単位：秒）を指定し、その期間だけオフラインユーザーにもメッセージを保持できます。最大604,800秒（7日）まで設定可能。デフォルトは `0`（オフライン保存なし）。

詳細は[「全員プッシュ」](https://trtc.io/document/37166)を参照してください。

#### メールの有効期限

- 無料版＆Standard エディション: 7日間保存  
- Pro エディション: 30日間保存  
- Pro Plus / Enterprise エディション: 90日間保存  

Pro / Pro Plus / Enterprise エディションは保存期間を延長できます。詳細は[「履歴メッセージ保存期間設定」](https://trtc.io/document/34419)を参照してください。また、サーバー側でメッセージを送信するとき、 `MsgLifeTime` を設定することで、オフラインへの保持期間（最大7日）を指定できます。これを `0` にした場合はオンラインユーザーにのみ送られ、オフライン保存されません。[詳細](https://trtc.io/document/34919)

--------------------------------------------------------------------------------

### 一時的なチーム結成

オンラインマルチプレイゲームには「一時的なチーム（パーティー）」機能が重要です。この章では、チーム結成シナリオと、バックエンドやチームメンバーがチーム情報を取得する方法を説明します。

#### チームシナリオ

チームシナリオには以下のようなイベントがあります。
- チームの作成  
- 一時チームからの離脱  
- チームリーダーへの昇格  
- 仲間の勧誘  
- チーム解散

以下のコード例では、各種シナリオの実装イメージを示します。

#### ゲーム開始前にチームを作成

最初のプレイヤーがゲームに入室するとき、サーバー側で自動的にグループを生成し、最大人数を設定できます。リクエストでグループオーナーやメンバーを指定すると、作成時に自動でメンバーに追加されます。サンプルURL：

```jsx
https://console.tim.qq.com/v4/group_open_http_svc/create_group?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
```

基本的なサンプルリクエスト：

```jsx
{
  "Owner_Account": "leckie", // (オプション) グループオーナーのUserId
  "Type": "Public", // グループタイプ: Private, Public, ChatRoom, AVChatRoom, Community
  "Name": "TestGroup", // (必須) グループ名
  "MaxMemberCount":5 // (オプション) グループの最大人数
}
```

**注**:  
1つのアプリで作成できるグループ数は最大100,000個です。超過分は[料金設定](https://trtc.io/document/34350)のとおり追加費用がかかります。サーバー側のグループ作成APIについては[「グループ作成」](https://trtc.io/document/34895)を参照。

#### グループメンバー追加

チーム（グループ）作成後に新規プレイヤーが参加する際は、既存グループにメンバーを追加します。サンプルURL：

```jsx
https://console.tim.qq.com/v4/group_open_http_svc/add_group_member?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
```

サンプルリクエスト：

```jsx
{
  "GroupId": "@TGS#2J4SZEAEL", // (必須) 追加先のグループID
  "MemberList": [             // 一度に最大300人追加可能
      {
          "Member_Account": "tommy" // (必須) 追加対象
      },
      {
          "Member_Account": "jared"
      }
  ]
}
```

詳細は[「グループメンバー追加」](https://trtc.io/document/34921)を参照。

#### チーム人数が揃ったときの Webhook

グループ作成時に最大メンバー数を設定している場合、指定人数が全員揃った（満員になった）タイミングでゲームを開始できます。この「満員後のWebhook」を受け取ってゲーム開始へ進みます。サンプルURL：

```jsx
https://www.example.com?SdkAppid=$SDKAppID&CallbackCommand=$CallbackCommand&contenttype=json&ClientIP=$ClientIP&OptPlatform=$OptPlatform
```

サンプルリクエスト：

```jsx
{
  "CallbackCommand": "Group.CallbackAfterGroupFull", // Webhookコマンド
  "GroupId": "@TGS#2J4SZEAEL" // グループID
}
```

詳細は[「満員後のコールバック」](https://trtc.io/document/34376)を参照。

#### 新メンバー参加の通知

新しいプレイヤーがゲーム（グループ）に参加したら、Chat は `Group.CallbackAfterNewMemberJoin` の Webhook を発行し、他のメンバーへ加入を通知します。サンプルURL：

```jsx
https://www.example.com?SdkAppid=$SDKAppID&CallbackCommand=$CallbackCommand&contenttype=json&ClientIP=$ClientIP&OptPlatform=$OptPlatform
```

サンプルリクエスト：

```jsx
{
  "CallbackCommand": "Group.CallbackAfterNewMemberJoin",
  "GroupId" : "@TGS#2J4SZEAEL",
  "Type": "Public", 
  "JoinType": "Apply", 
  "Operator_Account": "leckie",
  "NewMemberList": [
      {
          "Member_Account": "jared"
      },
      {
          "Member_Account": "tommy"
      }
  ]
}
```

**注**: Webhook を有効にするには、対応するURLを設定し、該当イベントをオンにしてください。設定手順は[「Webhook 設定」](https://trtc.io/document/34520)、コールバック詳細は[「メンバーがグループに加入した後」](https://trtc.io/document/34372)を参照。

#### ゲーム中のチーム離脱

プレイヤーが任意で離脱、またはネットワーク切断などでゲームを離れた場合、サーバー側は `Group.CallbackAfterMemberExit` の Webhook を使って他メンバーへ通知できます。サンプルURL例は[「メンバーがグループを退出した後」](https://trtc.io/document/34373)を参照：

```jsx
https://www.example.com?SdkAppid=$SDKAppID&CallbackCommand=$CallbackCommand&contenttype=json&ClientIP=$ClientIP&OptPlatform=$OptPlatform
```

サンプルリクエスト：

```jsx
{
  "CallbackCommand": "Group.CallbackAfterMemberExit",
  "GroupId": "@TGS#2J4SZEAEL",
  "Type": "Public",
  "ExitType": "Kicked",
  "Operator_Account": "leckie",
  "ExitMemberList": [
      {
          "Member_Account": "jared"
      },
      {
          "Member_Account": "tommy"
      }
  ]
}
```

`ExitType` が `"Kicked"` なら追放、`"Quit"` なら任意離脱を表します。

#### ゲーム終了後のグループ解散

ゲーム終了後、サーバー側でグループを解散できます。サンプルURL例は[「グループ解散」](https://trtc.io/document/34896):

```jsx
https://console.tim.qq.com/v4/group_open_http_svc/destroy_group?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
```

サンプルリクエスト：

```jsx
{
  "GroupId": "@TGS#2J4SZEAEL"
}
```

音声/映像チャットが絡む場合は、後述の説明を参照してください。

--------------------------------------------------------------------------------

### バックエンドでチーム情報を取得する

- **グループ詳細の取得**: サーバーAPI「グループ情報の取得」を呼び出すことで、グループメンバー数やプロフィールなど詳細を取得できます。 `Filter` フィールドで必要情報を絞り込み可能。サンプルURL：

  ```jsx
  https://console.tim.qq.com/v4/group_open_http_svc/get_group_info?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
  ```

  サンプルリクエスト：
  ```jsx
  {
    "GroupIdList": [
        "@TGS#1NVTZEAE4",
        "@TGS#1CXTZEAET"
    ]
  }
  ```
  詳細は[「グループ情報の取得」](https://trtc.io/document/34961)を参照。

- **グループメンバー詳細の取得**: 「メンバー情報の取得」APIを呼び出し、メンバーの詳細やカスタムフィールドを取得。サンプルURL：

  ```jsx
  https://console.tim.qq.com/v4/group_open_http_svc/get_group_member_info?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
  ```

  サンプル：
  ```jsx
  {  "GroupId":"@TGS#1NVTZEAE4"}  
  ```

  応答内の `MemberNum` はメンバー総数、 `AppMemberDefinedData` はカスタムフィールドを示します。  
  **注**: AVChatRoom（音声ビデオグループ）には非対応。詳細は[「グループメンバー情報の取得」](https://trtc.io/document/34948)。

--------------------------------------------------------------------------------

### チームメンバーがチーム情報を取得する

ユーザー自身が「メンバー情報の取得」をコールして、他メンバーのロールやステータスなどを取得できます。

```jsx
GroupGetMemberInfoListParam param = new GroupGetMemberInfoListParam
{
  group_get_members_info_list_param_group_id = "group_id",
  group_get_members_info_list_param_identifier_array = new List<string>
  {
    "user_id"
  }
};
TIMResult res = TencentIMSDK.GroupGetMemberInfoList(param, (int code, string desc, GroupGetMemberInfoListResult result, string user_data)=>{
 // 非同期処理
});
```

**注**:  
詳細は[「Unity - グループメンバー情報の取得」](https://trtc.io/document/50320)を参照。  
満員状態のゲーム開始やチーム加入・離脱などの情報は、[「チームシナリオ」](https://trtc.io/document/52717?platform=web&product=chat&menulabel=uikit#team_scene)で示したようにグループのコールバックで通知されます。  
グループの種類や選択については[「グループシステム」](https://trtc.io/document/33529)、コンソールでの管理は[「コンソールガイド - グループ管理」](https://trtc.io/document/34578)を参照。

--------------------------------------------------------------------------------

### 不適切表現のフィルタリング

ゲームにおいて不適切（センシティブ）な内容を除去することは重要です。以下のプロセスで実装可能です。

1. グループメッセージ送信前の Webhook をバインド。  
2. Webhook データに含まれるメッセージタイプを判定し、Tencent Cloud Securityなど外部検知サービスに依頼。  
3. 通常のテキストメッセージなら検知結果を待ち、コンプライアンスに反するかどうかを Chat バックエンドに返却。

送信前 Webhook のサンプルデータ：

```jsx
{
    "CallbackCommand": "Group.CallbackBeforeSendMsg",
    "GroupId": "@TGS#2J4SZEAEL",
    "Type": "Public",
    "From_Account": "jared",
    "Operator_Account":"admin",
    "Random": 123456,
    "OnlineOnlyFlag": 1,
    "MsgBody": [
        {
            "MsgType": "TIMTextElem",
            "MsgContent":{
                "Text": "red packet"
            }
        }
    ],
    "CloudCustomData": "your cloud custom data"
}
```

**注**: `MsgBody` 内の `MsgType` でメッセージ種別を識別。詳細は[「グループメッセージ送信前」](https://trtc.io/document/34374)。

問題メッセージをどう取り扱うかは返信パケットで制御可能です。

```jsx
{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0 
}
```

| ErrorCode | 意味                                                                       |
|----------|----------------------------------------------------------------------------|
| 0        | 発言許可、メッセージ正常送信                                                 |
| 1        | 発言拒否、クライアント側に `10016` 返却                                      |
| 2        | サイレント破棄、クライアント側は通常通り受信した形をとり、実際には表示しない等 |

--------------------------------------------------------------------------------

### メッセージタイプのカスタマイズ（アイテム贈与や取引など）

ゲームチャットではテキストや絵文字、ボイスなどの基本メッセージ以外に、開発者が自由に定義できるカスタムメッセージが必要になる場合があります。これにより、ゲーム内アイテムの贈答やトレードなど拡張的なチャットルーム機能を実装できます。

Tencent Cloud Chat が提供する標準メッセージタイプは以下の9つ：テキスト、絵文字、位置情報、画像、音声、ファイル、短編動画（UGSV）、システム通知、カスタムメッセージ。カスタムメッセージ以外は形式が固定されており、必要事項だけを設定すればよいのが特徴です。  
詳細は[「1対1メッセージタイプ」](https://trtc.io/document/33523)、メッセージフォーマットは[「メッセージフォーマット」](https://trtc.io/document/33527)を参照。

サーバー側から送る場合は [１対１メッセージ（単一）](https://trtc.io/document/34919)、[１対１メッセージ（複数）](https://trtc.io/document/34920)、[グループへの通常メッセージ送信](https://trtc.io/document/34959) を呼び出せます。以下はグループに通常メッセージを送信する際のリクエスト例です：

```jsx
{
    "GroupId": "@TGS#2C5SZEAEF",
    "Random": 8912345,
    "MsgBody": [
        {
            "MsgType": "TIMTextElem",
            "MsgContent":{
                "Text": "red packet"
            }
        },
        {
            "MsgType": "TIMFaceElem",
            "MsgContent":{
            "Index": 6,
            "Data": "abc\u0000\u0001"
            }
        }
    ],
    "CloudCustomData": "your cloud custom data",
    "SupportMessageExtension": 0
}
```

`CloudCustomData` を使うことでクラウド上に独自データを保存したり、`MsgBody` にカスタムメッセージを記述したりできます。

--------------------------------------------------------------------------------

### チーム内の音声/映像チャット

ゲーム内での音声やビデオ通話も重要な機能です。Tencent Cloud Chat アプリは、[Tencent Real-Time Communication (TRTC)](https://www.tencentcloud.com/document/product/647) と TUICallKit を組み合わせることでリアルタイム音声／ビデオ通話を実装できます。

**注**:  
- TUICallKit との統合手順は[「UI 付き音声/ビデオ通話ソリューション」](https://www.tencentcloud.com/document/product/1047/50025)を参照。

--------------------------------------------------------------------------------

### ゲームのチャットルームタイプ

ゲームのチャットルームには、主に以下の用途があります。

| タイプ              | 特徴                                                                                     |
|---------------------|------------------------------------------------------------------------------------------|
| チャンネル (Channel)       | 大規模ユーザー参加が想定され、固定メンバーリストを持たず、ユーザーは自由に出入り可。オフライン通知は不要。                |
| ライブゲームロビー (Live)  | 多数ユーザーが参加可能。自由に入退室し、履歴メッセージの取得をサポート。                                        |
| チーム (Team)             | 少人数で構成され、多人数フレンド関係は不要。ゲーム終了時には解散。オフライン通知不要。                               |
| フレンド (Friend)          | 1対1チャット。履歴は保存され、フレンドのみメッセージを送ることが可能。                                            |
| プライベートメッセージ (Private)   | 1対1チャットだが、ユーザー同士はフレンドでなくともやりとり可能。                                              |
| 音声ビデオグループ (AVChatRoom) | メンバー数無制限、自由に出入り可能。                                                                             |

Tencent Cloud Chat のグループタイプは以下のとおりです。

| タイプ        | 特徴                                                                                                                                                               |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Work グループ    | メンバーのフレンド招待によって加入可能。招待者の承諾なしで入室できる。                                                                                                                                    |
| Public グループ   | グループオーナーが管理者を指定可能。ユーザーが検索してリクエストし、オーナーまたは管理者が承認後に参加できる。                                                                                          |
| Meeting グループ  | ユーザーが自由に参加・退室可能で、過去のメッセージを閲覧できる。TRTCとの統合(音声/ビデオ会議やオンライン教育)に最適。旧版の ChatRoom に相当。                                                               |
| AVChatRoom    | 音声ビデオ用グループ。ユーザーは自由参加・退出OK。メッセージ履歴は非保存。Cloud Streaming Services (CSS) と連携してコメント機能（弾幕）などを実装可能。                                                   |
| Community グループ | 最大10万人が参加でき、自由参加・退出やメッセージ履歴保存に対応。参加申請は可能だが、管理者承認は不要。                                                                                                 |

ゲームの要件に応じて、上記グループの特徴を踏まえ、以下のようなサンプル適用例を考えられます。

| タイプ                        | ソリューション                   | 特徴                                                                                                                                                   |
|-------------------------------|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| チャンネル / ライブゲームロビー | Community グループ               | 大規模参加を想定し、承認なしで自由参加が可能。                                                                                                          |
| フレンド (Friend)             | 1対1チャット + 権限管理（フレンド間のみ） | フレンド同士だけが1対1メッセージを送れる。                                                                                                              |
| プライベートメッセージ       | 1対1チャット + 権限管理（アプリ全ユーザー）   | お互いがフレンドでなくてもメッセージを送れる。                                                                                                          |
| チーム（パーティ）            | Public / Meeting グループ         | ゲーム内のチームメンバーだけが参加できるグループチャット。音声・ビデオチャットが可能。                                                                 |
| Audio-video グループ         | AVChatRoom                        | メンバー数無制限。ユーザーは自由に出入り可能。                                                                                                          |

以上のように、ゲーム内チャットを要件に応じて柔軟に組み合わせることで、より豊かで便利なコミュニケーション機能を提供できます。