コンテンツにスキップ

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

レスポンスコード

  • APIレスポンスコード
HTTP ステータスコード コード メッセージ 説明
200 0 成功。 成功
400 100 不正なリクエスト。 無効なリクエスト
401 101 無効なトークン。 無効なトークン
403 102 禁止。 権限がありません
404 103 見つかりません。 見つかりません
405 104 メソッドは許可されていません。 メソッドは許可されていません
500 105 内部サーバーエラー。 内部サーバーエラー
  • 詳細なエラーコード (400, 403)
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 が値と一致するユーザーにのみ送信されます。たとえば、langCodeen の場合、通知メッセージは クライアント接続時にリクエストボディの langCodeen のユーザーにのみ送信されます

レスポンスボディ

フィールド 説明 タイプ
コード レスポンスコード 整数
メッセージ 結果メッセージ 文字列

リクエストサンプル

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

レスポンス値hasNexttrueの場合、さらにメッセージ履歴が利用可能です。言い換えれば、レスポンスで受け取った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
      },
    ]
  }
}