Http api
概要
チャットサービスはHTTPを介して提供されます。APIは主にチャネルAPI、ユーザーAPI、およびメッセージAPIに分かれています。
- チャンネルAPI
- すべてのチャンネルリストAPIを取得
- チャンネルAPIを取得
- チャンネルメンバーAPIを取得
- チャンネルを作成するAPI
- チャンネルを削除するAPI
- チャンネルに入るAPI
- チャンネルから出るAPI
- ユーザーAPI
- ユーザートークンを発行するAPI
- ユーザーが参加したチャンネルを取得するAPI
- ユーザーブロックリストを取得するAPI
- ユーザーをブロックするAPI
- ユーザーのブロックを解除するAPI
- メッセージAPI
- チャンネル通知メッセージAPIを送信
- ユーザー通知メッセージAPIを送信
- チャンネルカスタムメッセージAPIを送信
- ユーザーカスタムメッセージAPIを送信
- チャンネルメッセージ履歴APIを取得
基本情報
このセクションでは、HTTP APIを使用する際に知っておくべき基本情報を提供します。
前提条件
HTTP APIを使用するには、以下のアイテムが必要です:
- Hive 認証キー: API呼び出し用の認証トークン
- Hive コンソール > アプリセンター > プロジェクト管理 > ゲーム詳細 > 基本情報 で見つけることができます
- ゲームインデックス: Hive コンソール > アプリセンター > プロジェクト管理 で作成されたゲームのインデックス
チャンネルの種類
HTTP APIを介して送信する際に使用されるチャネルタイプは次のとおりです。
タイプ | 説明 |
PUBLIC | 誰でも参加できるチャンネル |
PRIVATE | 参加するためにパスワードが必要なチャンネル |
GROUP | 特定のユーザー用のチャンネル(例:ギルド) |
リクエストURL
サーバー | URL |
LIVE | api-chat.withhive.com |
SANDBOX | sandbox-api-chat.withhive.com |
一般的なヘッダー
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しの認証トークン (Bearer ) | 文字列 | Y |
Content-Type | リクエストデータのタイプ (application/json ) | 文字列 | Y |
レスポンスコード
HTTP ステータスコード | コード | メッセージ | 説明 |
200 | 0 | 成功。 | 成功 |
400 | 100 | 不正なリクエスト。 | 無効なリクエスト |
401 | 101 | 無効なトークン。 | 無効なトークン |
403 | 102 | 禁止。 | 権限がありません |
404 | 103 | 見つかりません。 | 見つかりません |
405 | 104 | メソッドは許可されていません。 | メソッドは許可されていません |
500 | 105 | 内部サーバーエラー。 | 内部サーバーエラー |
HTTP ステータスコード | コード | メッセージ | 説明 |
400 | 200 | 重複したチャンネルIDです。 | 重複したチャンネルID |
| 201 | チャンネルが見つからないか、削除されています。 | チャンネルが見つからないか、削除されています。 |
| 202 | チャンネルが満杯です。 | チャンネルが満杯です。 |
| 203 | 無効なチャンネルパスワードです。 | 無効なチャンネルパスワードです。 |
| 204 | メッセージサイズが超過しました。最大サイズは200です。 | メッセージサイズが超過しました(最大200文字)。 |
| 300 | ユーザーはセッションに参加していません。 | ユーザーはセッションに参加していません(ソケットサーバーに接続されていません)。 |
| 301 | ユーザーはチャンネルに参加していません。 | ユーザーはチャンネルに参加していません。 |
| 302 | ユーザーはすでにチャンネルに参加しています。 | ユーザーはすでにチャンネルに参加しています。 |
| 303 | ユーザーはすでにブロックされています。 | ユーザーはすでにブロックされています。 |
| 304 | ブロックリストが満杯です。最大サイズは100です。 | ブロックリストが満杯です(最大100ユーザー)。 |
| 305 | ユーザーはブロックリストにいません。 | ユーザーはブロックリストにいません。 |
| 306 | ユーザーはブロックされています。 | ユーザーはブロックされています。 |
| 307 | ユーザーが参加できるチャンネルの最大数は10です。 | ユーザーが参加できるチャンネルの最大数を超えました(制限10)。 |
| 400 | カスタムメッセージサイズが超過しました。最大サイズは8,000バイトです。 | カスタムメッセージの最大サイズを超えました(最大8,000バイト)。 |
403 | 308 | ユーザーはチャンネルの所有者ではありません。 | ユーザーはチャンネルの所有者ではありません。 |
チャンネルAPI関数
このセクションでは、チャットサービスで使用されるチャネルAPIの各機能に対するAPIリクエスト、レスポンス、およびサンプルコードについて説明します。
すべてのチャンネルを取得
作成されたすべてのチャンネルのリストを取得します。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels |
HTTP METHOD | GET |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 整数 | Y |
ヘッダーパラメータ
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しの認証トークン (Bearer ) | 文字列 | Y |
クエリパラメータ
フィールド | 説明 | タイプ | 必須 |
type | チャンネルタイプ(PRIVATE , PUBLIC , GROUP ) | 文字列 | N |
channelId | このチャンネルIDで始まるチャンネルを取得 | 文字列 | N |
channelName | このチャンネル名を含むチャンネルを取得 | 文字列 | N |
sort | ソート基準(channelId , channelName , regTime ) (デフォルト regTime ) | 文字列 | N |
order | ソート順序(ASC , DESC ) (デフォルト DESC ) | 文字列 | N |
size | ページごとに取得するチャンネルの数 (最小 1 ~ 最大 10, デフォルト 10) | 整数 | N |
page | 取得するページ番号 (1から始まる, デフォルト 1) | 整数 | N |
レスポンスボディ
フィールド | 説明 | タイプ |
code | レスポンスコード | 整数 |
message | 結果メッセージ | 文字列 |
data | レスポンスデータ | オブジェクト |
レスポンスボディ > データ
フィールド | 説明 | タイプ |
content | チャンネルのリスト | オブジェクト配列 |
page | ページ情報 | オブジェクト |
レスポンスボディ > データ > コンテンツ
フィールド | 説明 | タイプ |
channelId | チャンネルID | 文字列 |
type | チャンネルタイプ(PRIVATE , PUBLIC , GROUP ) | 文字列 |
gameIndex | Hive ゲームインデックス | 整数 |
owner | チャンネルオーナーのプレイヤーID | 文字列 |
channelName | チャンネル名 | 文字列 |
memberCount | チャンネル内の現在のメンバー数 | 整数 |
maxMemberCount | チャンネル内で許可される最大メンバー数 | 整数 |
chatHistoryAllowed | メッセージ履歴が表示できるかどうか | ブール |
regTime | チャンネル作成日時(UTC+0 標準、yyyy-MM-dd'T'HH:mm:ss.SSSZ 形式) | 文字列 |
regTimeMillis | チャンネル作成日時(Unixタイムスタンプミリ秒) | 長整数 |
レスポンスボディ > データ > ページ
フィールド | 説明 | タイプ |
size | ページあたりのアイテム数 | 整数 |
currentPage | 現在のページ番号 | 整数 |
totalElements | アイテムの総数 | 整数 |
totalPages | ページの総数 | 整数 |
リクエストサンプル
curl --request GET 'https://api-chat.withhive.com/api/v1/games/1/channels?type=PUBLIC&sort=regTime&order=DESC&size=10&page=1' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'
レスポンスサンプル
{
"code": 0,
"message": "Success.",
"data": {
"content": [
{
"channelId": "open:12345",
"type": "PUBLIC",
"gameIndex": 1,
"owner": "1000",
"channelName": "Open Chat Room",
"memberCount": 2,
"maxMemberCount": 50,
"chatHistoryAllowed": true,
"regTime": "2024-12-30T15:01:01.004Z",
"regTimeMillis": 1731306364351
},
/// ... Channel information
],
"page": {
"size": 10,
"currentPage": 1,
"totalElements": 100,
"totalPages": 10
}
}
}
チャンネルを取得
チャンネルに関する詳細情報を取得します。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId} |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId} |
HTTP メソッド | GET |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 整数 | Y |
channelId | 取得するチャンネルのID | 文字列 | Y |
ヘッダーパラメータ
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しの認証トークン (Bearer ) | 文字列 | Y |
レスポンスボディ
フィールド | 説明 | タイプ |
code | レスポンスコード | 整数 |
message | 結果メッセージ | 文字列 |
data | レスポンスデータ | オブジェクト |
レスポンスボディ > データ
フィールド | 説明 | タイプ |
info | チャンネル情報 | オブジェクト |
members | メンバーのリスト | オブジェクト配列 |
レスポンスボディ > データ > 情報
フィールド | 説明 | タイプ |
channelId | チャンネルID | 文字列 |
type | チャンネルタイプ (PRIVATE , PUBLIC , GROUP ) | 文字列 |
gameIndex | Hive ゲームインデックス | 整数 |
owner | チャンネルオーナー | 文字列 |
channelName | チャンネル名 | 文字列 |
memberCount | チャンネル内の現在のメンバー数 | 整数 |
maxMemberCount | チャンネルに許可される最大メンバー数 | 整数 |
chatHistoryAllowed | メッセージ履歴が表示できるかどうか | ブール値 |
regTime | チャンネル作成日時 (UTC+0 標準, yyyy-MM-dd'T'HH:mm:ss.SSSZ 形式) | 文字列 |
regTimeMillis | チャンネル作成日時 (UnixTimestamp ミリ秒) | 長整数 |
レスポンスボディ > データ > メンバー
フィールド | 説明 | タイプ |
playerId | プレイヤーID | long |
connectedTime | 接続日時 (UTC+0 標準, yyyy-MM-dd'T'HH:mm:ss.SSSZ 形式) | string |
connectedTimeMillis | 接続日時 (UnixTimestamp ミリ秒) | long |
リクエストサンプル
curl --request GET 'https://api-chat.withhive.com/api/v1/games/1/channels/open:12345' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'
レスポンスサンプル
{
"code": 0,
"message": "Success.",
"data": {
"info": {
"channelId": "open:12345",
"type": "PUBLIC",
"gameIndex": 1,
"owner": "SYSTEM",
"channelName": "Open Chat Room",
"memberCount": 2,
"maxMemberCount": 50,
"chatHistoryAllowed": true,
"regTime": "2024-12-30T15:01:01.004Z",
"regTimeMillis": 1731306364351
},
"members": [
{
"playerId": 1,
"connectedTime": "2024-11-25T06:22:06.604Z",
"connectedTimeMillis": 1739328218507
},
{
"playerId": 2,
"connectedTime": "2024-11-25T06:22:16.233Z",
"connectedTimeMillis": 1731306364351
}
]
}
}
チャンネルメンバーを取得
チャンネルのメンバーに関する情報を取得します。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/members |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/members |
HTTP METHOD | GET |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 整数 | Y |
channelId | 取得するチャンネルのID | 文字列 | Y |
ヘッダーパラメータ
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しの認証トークン (Bearer ) | 文字列 | Y |
レスポンスボディ
フィールド | 説明 | タイプ |
コード | レスポンスコード | 整数 |
メッセージ | 結果メッセージ | 文字列 |
データ | レスポンスデータ | オブジェクト |
レスポンスボディ > データ
フィールド | 説明 | タイプ |
members | チャンネルメンバーのリスト | オブジェクト配列 |
レスポンスボディ > データ > メンバー
フィールド | 説明 | タイプ |
playerId | プレイヤーID | long |
connectedTime | 接続日時 (UTC+0 標準, yyyy-MM-dd'T'HH:mm:ss.SSSZ 形式) | string |
connectedTimeMillis | 接続日時 (Unixタイムスタンプミリ秒) | long |
リクエストサンプル
curl --request GET 'https://api-chat.withhive.com/api/v1/games/1/channels/open:12345/members' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'
応答サンプル
{
"code": 0,
"message": "Success.",
"data": {
"members": [
{
"playerId": 1,
"connectedTime": "2024-11-25T06:22:06.604Z",
"connectedTimeMillis": 1739328218507
},
{
"playerId": 2,
"connectedTime": "2024-11-25T06:22:16.233Z",
"connectedTimeMillis": 1731306364351
}
]
}
}
チャンネルを作成する
新しいチャンネルを作成します。
リクエストボディにplayerId
を入力すると、playerId
に対応するユーザーがチャンネルの所有者となり、チャンネルに入ります。playerId
を入力しない場合、SYSTEM
がチャンネルの所有者となります。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/channel |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channel |
HTTP メソッド | POST |
CONTENT-TYPE | application/json |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 整数 | Y |
ヘッダーパラメータ
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しの認証トークン(Bearer ) | 文字列 | Y |
Content-Type | リクエストデータのタイプ(application/json ) | 文字列 | Y |
リクエストボディ
チャンネルを作成するリクエストを送信する際に送信されるデータ。
フィールド | 説明 | タイプ | 必須 |
channelId | チャンネルID (英大文字と小文字、数字、いくつかの特殊文字(- , . , _ , ~ , : )を使用可能、最大100文字) | 文字列 | Y |
playerId | チャンネル作成者のプレイヤーID | 長整数 | N |
password | パスワード(PRIVATE チャンネルに必要) (最大50文字) | 文字列 | N |
channelName | チャンネル名 (最大50文字) | 文字列 | Y |
maxMemberCount | チャンネルに許可される最大メンバー数 (最小2〜最大5,000) | 整数 | Y |
type | チャンネルタイプ(PRIVATE , PUBLIC , GROUP ) | 文字列 | Y |
chatHistoryAllowed | メッセージ履歴を表示できるかどうか (デフォルトはfalse) | ブール値 | N |
レスポンスボディ
フィールド | 説明 | タイプ |
code | レスポンスコード | 整数 |
message | 結果メッセージ | 文字列 |
リクエストサンプル
curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/channel' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data'{
"channelId": "open:12345",
"playerId": 1000,
"channelName": "Open Chat Room",
"maxMemberCount": 100,
"type": "PUBLIC",
"chatHistoryAllowed": true
}'
レスポンスサンプル
{
"code": 0,
"message": "Success."
}
チャンネルを削除
チャンネルを削除します。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId} |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId} |
HTTP メソッド | DELETE |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 整数 | Y |
channelId | 削除するチャンネルのID | 文字列 | Y |
ヘッダー パラメータ
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しの認証トークン (Bearer ) | 文字列 | Y |
レスポンスボディ
フィールド | 説明 | タイプ |
コード | レスポンスコード | 整数 |
メッセージ | 結果メッセージ | 文字列 |
リクエストサンプル
curl --request DELETE 'https://api-chat.withhive.com/api/v1/games/1/channels/open:12345' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'
レスポンスサンプル
{
"code": 0,
"message": "Success."
}
チャンネルに入る
チャンネルを入力してください。
ユーザーごとに入力できる最大チャネル数は10です。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/enter |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/enter |
HTTP METHOD | POST |
CONTENT-TYPE | application/json |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 整数 | Y |
channelId | 入るチャンネルのID | 文字列 | Y |
ヘッダー パラメータ
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しの認証トークン (Bearer ) | 文字列 | Y |
Content-Type | リクエストデータのタイプ (application/json ) | 文字列 | Y |
リクエストボディ
チャンネルに入るためにリクエストする際に必要なデータ。
フィールド | 説明 | タイプ | 必須 |
playerId | 入力されるユーザーのプレイヤーID | long | Y |
password | パスワード(PRIVATE チャンネルに必要) | string | N |
レスポンスボディ
フィールド | 説明 | タイプ |
コード | レスポンスコード | 整数 |
メッセージ | 結果メッセージ | 文字列 |
リクエストサンプル
curl --request POST 'https://api-chat.withhive.com/api/v1/games/1/channels/guild:12345/enter' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data '{
"playerId": 1001,
"password": "guildPass123"
}'
レスポンスサンプル
{
"code": 0,
"message": "Success."
}
出口チャネル
チャンネルを退出します。
チャンネルの所有者が退出しても、チャンネルは維持されます。ただし、所有者がSYSTEM
でなく、チャンネルに参加者がいない場合、チャンネルは定期的に削除されます。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/exit |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/exit |
HTTP METHOD | POST |
CONTENT-TYPE | application/json |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 整数 | Y |
channelId | チャンネルのIDを終了する | 文字列 | Y |
ヘッダーパラメータ
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しの認証トークン (Bearer ) | 文字列 | Y |
Content-Type | リクエストデータのタイプ (application/json ) | 文字列 | Y |
リクエストボディ
チャネルを退出する際に要求されるデータ。
フィールド | 説明 | タイプ | 必須 |
playerId | 退出するユーザーのプレイヤーID | long | Y |
レスポンスボディ
フィールド | 説明 | タイプ |
コード | レスポンスコード | 整数 |
メッセージ | 結果メッセージ | 文字列 |
リクエストサンプル
curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/channels/guild:12345/exit' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data '{
"playerId": 1001
}'
レスポンスサンプル
{
"code": 0,
"message": "Success."
}
ユーザーAPI機能
このセクションでは、チャットサービスで使用されるユーザーAPIの各関数に対するAPIリクエスト、レスポンス、およびサンプルコードについて説明します。
ユーザートークンの発行
ソケットサーバーに接続するための認証トークンを発行します。
発行されたトークンを使用して、返されたソケットサーバーアドレスに接続します。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/token |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/token |
HTTP メソッド | POST |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 整数 | Y |
playerId | プレイヤーID | 長整数 | Y |
ヘッダーパラメータ
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しの認証トークン (Bearer ) | 文字列 | Y |
レスポンスボディ
フィールド | 説明 | タイプ |
code | レスポンスコード | 整数 |
message | 結果メッセージ | 文字列 |
data | レスポンスデータ | オブジェクト |
レスポンスボディ > データ
フィールド | 説明 | タイプ |
gameIndex | Hive ゲームインデックス | 整数 |
socketAddress | ソケットサーバーアドレス | 文字列 |
token | 発行されたトークン | 文字列 |
リクエストサンプル
curl --request POST 'https://api-chat.withhive.com/api/v1/games/1/users/1001/token' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'
レスポンスサンプル
{
"code": 0,
"message": "Success.",
"data": {
"gameIndex": 1,
"socketAddress": "wss://test-socket-chat.withhive.com/ws",
"token": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg"
}
}
ユーザーが参加しているチャンネルを取得
ユーザーが参加したチャンネルのリストを取得します。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/channels |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/channels |
HTTP METHOD | GET |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 整数 | Y |
playerId | プレイヤーID | 長整数 | Y |
ヘッダー パラメータ
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しの認証トークン (Bearer ) | 文字列 | Y |
レスポンスボディ
フィールド | 説明 | タイプ |
コード | レスポンスコード | 整数 |
メッセージ | 結果メッセージ | 文字列 |
データ | レスポンスデータ | オブジェクト |
レスポンスボディ > データ
フィールド | 説明 | タイプ |
gameIndex | Hive ゲームインデックス | 整数 |
playerId | プレイヤーID | 長整数 |
channels | チャンネルのリスト | オブジェクト配列 |
レスポンスボディ > データ > チャンネル
フィールド | 説明 | タイプ |
channelId | チャンネルID | 文字列 |
type | チャンネルタイプ (PRIVATE , PUBLIC , GROUP ) | 文字列 |
gameIndex | Hive ゲームインデックス | 整数 |
owner | チャンネルオーナー | 文字列 |
channelName | チャンネル名 | 文字列 |
memberCount | チャンネル内の現在のメンバー数 | 整数 |
maxMemberCount | チャンネル内で許可される最大メンバー数 | 整数 |
chatHistoryAllowed | メッセージ履歴が表示できるかどうか | ブール |
regTime | チャンネル作成日時 (UTC+0 標準, yyyy-MM-dd'T'HH:mm:ss.SSSZ 形式) | 文字列 |
regTimeMillis | チャンネル作成日時 (UnixTimestamp ミリ秒) | 長整数 |
リクエストサンプル
curl --request GET 'https://sandbox-api-chat.withhive.com/api/v1/games/1/users/1001/channels' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'
応答サンプル
{
"code": 0,
"message": "Success.",
"data": {
"gameIndex": 1,
"playerId": 1001,
"channels": [
{
"channelId": "guild:12345",
"type": "GROUP",
"gameIndex": 1,
"owner": "1000",
"channelName": "Guild Chat Room",
"memberCount": 1,
"maxMemberCount": 50,
"chatHistoryAllowed": true,
"regTime": "2023-12-19T15:01:01.004Z",
"regTimeMillis": 1731306364351
},
{
"channelId": "open:67890",
"type": "PUBLIC",
"gameIndex": 1,
"owner": "SYSTEM",
"channelName": "Open Chat Room",
"memberCount": 2,
"maxMemberCount": 100,
"chatHistoryAllowed": true,
"regTime": "2023-12-20T10:15:30.123Z",
"regTimeMillis": 1731302348750
}
// ... channels
]
}
}
ユーザーブロックリストを取得
ユーザーによってブロックされたユーザーのリストを取得します。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/blocks |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/blocks |
HTTP METHOD | GET |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 文字列 | Y |
playerId | プレイヤーID | 長整数 | Y |
ヘッダーパラメータ
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しの認証トークン (Bearer ) | 文字列 | Y |
レスポンスボディ
フィールド | 説明 | タイプ |
code | レスポンスコード | 整数 |
message | 結果メッセージ | 文字列 |
data | レスポンスデータ | オブジェクト |
レスポンスボディ > データ
フィールド | 説明 | タイプ |
gameIndex | Hive ゲームインデックス | 整数 |
playerId | プレイヤーID | 長整数 |
blockedUsers | ブロックされたユーザーリスト | オブジェクト配列 |
null | フィールド | 説明 | タイプ | | --------------- |------------------------------------------------------| ------ | | blockedPlayerId | ブロックされたユーザーのプレイヤーID | long | | blockedTime | ユーザーがブロックされた日時(UTC+0
標準、yyyy-MM-dd'T'HH:mm:ss.SSSZ
形式) | string | | blockedTimeMillis | ユーザーがブロックされた日時(Unixタイムスタンプミリ秒) | long |
リクエストサンプル
curl --request GET 'https://sandbox-api-chat.withhive.com/api/v1/games/1/users/1001/blocks' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'
レスポンスサンプル
{
"code": 0,
"message": "Success.",
"data": {
"gameIndex": 1,
"playerId": 1001,
"blockedUsers": [
{
"blockedPlayerId": 1002,
"blockedTime": "2023-12-20T10:15:30.123Z",
"blockedTimeMillis": 1739329550811
},
{
"blockedPlayerId": 1003,
"blockedTime": "2023-12-21T08:45:12.456Z",
"blockedTimeMillis": 1739329553137
},
// ... Blocked users list
]
}
}
ユーザーをブロックする
別のユーザーをブロックします。これにより、リアルタイムのメッセージの送受信が制限されます。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/block/{blockPlayerId} |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/block/{blockPlayerId} |
HTTP メソッド | POST |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 文字列 | Y |
playerId | プレイヤーID | 長整数 | Y |
blockPlayerId | ブロックするプレイヤーID | 長整数 | Y |
ヘッダーパラメータ
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しのための認証トークン(Bearer ) | 文字列 | Y |
レスポンスボディ
フィールド | 説明 | 種類 |
コード | レスポンスコード | 整数 |
メッセージ | 結果メッセージ | 文字列 |
リクエストサンプル
curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/users/1001/block/1002' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'
レスポンスサンプル
{
"code": 0,
"message": "Success."
}
ユーザーのブロック解除
ブロックされたユーザーのブロックを解除します。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/block/{blockedPlayerId} |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/block/{blockedPlayerId} |
HTTP METHOD | DELETE |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 文字列 | Y |
playerId | プレイヤーID | 長整数 | Y |
blockedPlayerId | アンブロックするプレイヤーID | 長整数 | Y |
ヘッダーパラメータ
フィールド | 説明 | 型 | 必須 |
Authorization | API呼び出しの認証トークン (Bearer ) | 文字列 | Y |
レスポンスボディ
フィールド | 説明 | 種類 |
code | レスポンスコード | 整数 |
message | 結果メッセージ | 文字列 |
リクエストサンプル
curl --request DELETE 'https://sandbox-api-chat.withhive.com/api/v1/games/1/users/1001/block/1002' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'
レスポンスサンプル
{
"code": 0,
"message": "Success."
}
メッセージAPI機能
特定のチャンネルに対して通知やカスタムメッセージを送信したり、メッセージ履歴を取得するためのAPI。
通知メッセージを送信
特定のチャンネルまたはすべてのユーザーに通知メッセージを送信します。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/notice |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/notice |
HTTP METHOD | POST |
CONTENT-TYPE | application/json |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 整数 | Y |
ヘッダー パラメータ
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しの認証トークン(Bearer ) | 文字列 | Y |
Content-Type | リクエストデータのタイプ(application/json ) | 文字列 | Y |
リクエストボディ
通知メッセージを送信するリクエスト時に送信されるデータ。
フィールド | 説明 | タイプ | 必須 |
channelId | メッセージを送信するチャンネルのID | 文字列 | N |
langCode | メッセージを受信するユーザーのハイブ言語コード(提供されていない場合は言語に関係なく送信) (ISO 639 alpha-2に基づき、ISO 639 alpha-2で分類されていない言語を区別するためにスクリプトタグを使用) | 文字列 | N |
message | 送信される通知メッセージの内容 (最大200文字) | 文字列 | Y |
チャンネルID
channelId
が提供されている場合、チャンネル通知メッセージがチャンネルに接続されているすべてのユーザーに送信されます。
channelId
が提供されていない場合、ユーザー通知メッセージが、対応するgameIndex
を持つアプリに接続されているすべてのユーザーに送信されます。
言語コード
langCode
が提供されていない場合、メッセージは言語に関係なくすべてのユーザーに送信されます。
langCode
が提供されている場合、メッセージはその langCode
が値と一致するユーザーにのみ送信されます。たとえば、langCode
が en
の場合、通知メッセージは クライアント接続時にリクエストボディの langCode
が en
のユーザーにのみ送信されます。
レスポンスボディ
フィールド | 説明 | タイプ |
コード | レスポンスコード | 整数 |
メッセージ | 結果メッセージ | 文字列 |
リクエストサンプル
curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/notice' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg' \
--header 'Content-Type: application/json' \
--data '{
"channelId": "open:12345",
"langCode": "en",
"message": "Server maintenance. Please reconnect later."
}'
レスポンスサンプル
{
"code": 0,
"message": "Success."
}
ユーザー通知メッセージを送信
ユーザーにユーザー通知メッセージを送信します。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/notice/users/{playerId} |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/notice/users/{playerId} |
HTTP メソッド | POST |
コンテンツタイプ | application/json |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 整数 | Y |
playerId | Hive プレイヤーID | 長整数 | Y |
ヘッダーパラメータ
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しの認証トークン(Bearer ) | 文字列 | Y |
Content-Type | リクエストデータのタイプ(application/json ) | 文字列 | Y |
リクエストボディ
ユーザーに通知メッセージを送信するリクエスト時に送信されるデータ。
フィールド | 説明 | タイプ | 必須 |
langCode | メッセージを受信するユーザーのHive言語コード(提供されていない場合は言語に関係なく送信) (ISO 639 alpha-2に基づき、ISO 639 alpha-2で分類されていない言語を区別するためにスクリプトタグを使用) | 文字列 | N |
message | 送信される通知メッセージの内容 (最大200文字) | 文字列 | Y |
langCode
langCode
が提供されていない場合、メッセージは言語に関係なくユーザーに送信されます。
langCode
が提供されている場合、通知メッセージは、接続時のクライアントのリクエスト内のlangCode
がこのAPIのlangCode
と一致する場合にのみ送信されます。たとえば、playerId=1111
のクライアントがlangCode=en
で接続されていて、このAPIがplayerId=1111, langCode=ja
で呼び出された場合、通知メッセージはこのユーザーには送信されません。
レスポンスボディ
フィールド | 説明 | タイプ |
code | レスポンスコード | 整数 |
message | 結果メッセージ | 文字列 |
リクエストサンプル
curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/notice/users/123123' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg' \
--header 'Content-Type: application/json' \
--data '{
"langCode": "en",
"message": "This is a notice message for user 123123."
}'
レスポンスサンプル
{
"code": 0,
"message": "Success."
}
チャンネルカスタムメッセージを送信
チャンネルに参加しているすべてのユーザーにカスタムメッセージを送信します。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/custom-message/channels/{channelId} |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/custom-message/channels/{channelId} |
HTTP METHOD | POST |
CONTENT-TYPE | application/json |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 整数 | Y |
channelId | メッセージを送信するチャンネルのID | 文字列 | Y |
ヘッダーパラメータ
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しの認証トークン(Bearer ) | 文字列 | Y |
Content-Type | リクエストデータのタイプ(application/json ) | 文字列 | Y |
リクエストボディ
カスタムメッセージを送信するリクエスト時に送信されるデータ。
フィールド | 説明 | タイプ | 必須 |
message | 送信されるカスタムメッセージの内容(UTF-8 標準) (最大8,000バイト) | 文字列 | Y |
レスポンスボディ
フィールド | 説明 | 型 |
code | レスポンスコード | 整数 |
message | 結果メッセージ | 文字列 |
リクエストサンプル
curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/custom-message/channels/public:123' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg' \
--header 'Content-Type: application/json' \
--data '{
"message": "This is a custom message."
}'
レスポンスサンプル
{
"code": 0,
"message": "Success."
}
ユーザーにカスタムメッセージを送信
ユーザーにカスタムメッセージを送信します。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/custom-message/users |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/custom-message/users |
HTTP メソッド | POST |
CONTENT-TYPE | application/json |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 整数 | Y |
ヘッダーパラメータ
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しの認証トークン (Bearer ) | 文字列 | Y |
Content-Type | リクエストデータのタイプ (application/json ) | 文字列 | Y |
リクエストボディ
ユーザーにカスタムメッセージを送信するリクエスト時に送信されるデータ。
フィールド | 説明 | タイプ | 必須 |
playerIds | メッセージを受信するアカウント識別子のリスト プレイヤーIDリスト (最大10ユーザー) | long array | Y |
message | 送信されるカスタムメッセージの内容(UTF-8 標準) (最大8,000バイト) | string | Y |
レスポンスボディ
フィールド | 説明 | タイプ |
コード | レスポンスコード | 整数 |
メッセージ | 結果メッセージ | 文字列 |
リクエストサンプル
curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/custom-message/users' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg' \
--header 'Content-Type: application/json' \
--data '{
"playerIds": [
123123
],
"message": "This is a custom message."
}'
レスポンスサンプル
{
"code": 0,
"message": "Success."
}
チャンネルメッセージ履歴を取得
チャンネルのメッセージ履歴を取得します。チャンネルメッセージ履歴はカーソルベースのページネーションで提供され、過去30日間のメッセージ履歴のみが取得可能です。このAPIは、チャンネル設定以前の会話履歴を表示するが有効になっている場合のみ使用できます。APIレスポンスで受け取ったチャンネルメッセージ履歴には、ブロックされたユーザーからのメッセージが含まれる場合があります。
ページネーション: サイズとインデックス
index
クエリパラメータを使用したページネーションが提供されています。index
のデフォルト値はなしであり、index
なしでリクエストが行われた場合、最も最近のメッセージがsize
に従って取得されます。
例えば、APIがindex
なしでsize=5
で呼び出された場合、5つの最新のメッセージ履歴がnextIndex
(例:68009c30780e4f2d9830d8a0
)と共に返されます。
その後、APIがindex=68009c30780e4f2d9830d8a0
およびsize=5
で呼び出されると、最後に返されたメッセージの前に発生した5つのメッセージが取得されます。
ページネーション: hasNext
レスポンス値hasNext
がtrue
の場合、さらにメッセージ履歴が利用可能です。言い換えれば、レスポンスで受け取ったnextIndex
は、チャネルの以前のメッセージ履歴を取得するためのindex
として使用できます。
リクエストURL
サーバー | URL |
LIVE | https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/messages |
SANDBOX | https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/messages |
HTTP メソッド | GET |
パスパラメータ
フィールド | 説明 | タイプ | 必須 |
gameIndex | Hive ゲームインデックス | 整数 | Y |
channelId | 取得するチャネルのID | 整数 | Y |
ヘッダーパラメータ
フィールド | 説明 | タイプ | 必須 |
Authorization | API呼び出しの認証トークン(Bearer ) | 文字列 | Y |
クエリパラメータ
チャネルメッセージ履歴を取得するために要求する際に必要なクエリ文字列データ。
フィールド | 説明 | タイプ | 必須 |
size | チャンネル履歴のサイズ (最小 1 ~ 最大 50) | 整数 | Y |
index | 取得に使用するインデックス(指定しない場合は最も最近のメッセージを取得) | 文字列 | N |
レスポンスボディ
フィールド | 説明 | タイプ |
コード | レスポンスコード | 整数 |
メッセージ | 結果メッセージ | 文字列 |
データ | レスポンスデータ | オブジェクト |
レスポンスボディ > データ
フィールド | 説明 | タイプ |
hasNext | さらにデータを取得できるかどうか | boolean |
nextIndex | 取得に使用する次のインデックス | string |
content | チャンネルメッセージの履歴 | オブジェクト配列 |
レスポンスボディ > データ > コンテンツ
フィールド | 説明 | タイプ |
gameIndex | Hive ゲームインデックス | 整数 |
from | メッセージを受信したアカウントの識別子 プレイヤーID | 長整数 |
extraData | 追加のユーザー情報(UTF-8 標準) (最大256バイト) | 文字列 |
to | メッセージが送信されたチャネルのID | 文字列 |
message | メッセージ内容 | 文字列 |
langCode | Hive 言語コード (ISO 639 alpha-2に基づく、ISO 639 alpha-2で分類されていない言語を区別するためにスクリプトタグを使用) | 文字列 |
timestamp | メッセージが送信された日時(UTC+0 標準、yyyy-MM-dd'T'HH:mm:ss.SSSZ 形式) | 文字列 |
timestampMillis | メッセージが送信された日時(UnixTimestampミリ秒) | 長整数 |
リクエストサンプル
curl --request GET 'https://test-api-chat.withhive.com/api/v1/games/1/channels/open:1/messages?size=50' \
--header 'Authorization: hivechat 005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76'
レスポンスサンプル
{
"code": 0,
"message": "Success.",
"data": {
"hasNext": true,
"nextIndex": "67c7d83336af25202c1c0ad4",
"content": [
// size=50이므로 아래와 같은 객체들을 50개 반환함.
{
"gameIndex": 1,
"from": 1111112,
"extraData": "Kim Hive",
"to": "open:10",
"message": "zzz",
"langCode": "ko",
"timestamp": "2025-03-05T04:50:59.757Z",
"timestampMillis": 1741150259757
},
{
"gameIndex": 1,
"from": 1111111,
"extraData": null,
"to": "open:10",
"message": "Hive2",
"langCode": "ko",
"timestamp": "2025-03-05T04:51:01.689Z",
"timestampMillis": 1741150261689
},
]
}
}