Chat Message
概要
チャットのメッセージを操作する API です。
- 1 ユーザにつき、1 チャットルームを作成し、特定ユーザーのみにメッセージ(ゲームからのお知らせ)を送る行為は禁止されています。
- 1アプリケーションにつき生成できるチャンネルの最大エントリ数は 1,000,000 件 になります。
ゲームチャットの使い方に関しては、こちらのチュートリアルをご確認下さい。
ChatMessage オブジェクトフィールド
メッセージを表すオブジェクトです。
| 値 | 説明 | 型 | 名前空間 | 補足 |
|---|---|---|---|---|
| id | メッセージ ID | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | – |
| actor | 送信者 | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | ChatMessageActor オブジェクト |
| payload | ペイロード | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | ChatMessagePayload オブジェクト |
| published | 送信日時 | xs:date | http://ns.dena.jp/mbga/gameapi/v1 | 送信日時 (ISO8601, GMT表記) |
ChatMessageActor オブジェクトフィールド
メッセージを表すオブジェクトです。
| 値 | 説明 | 型 | 名前空間 | 補足 |
|---|---|---|---|---|
| id | グローバルオブジェクト ID | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | id = objectType + ':' + localId というフォーマット |
| objectType | ChatMember オブジェクトの型 | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | POST 時は "application" のみ指定可能 |
| localId | ローカル ID | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | objectType ごとにユニークに割り当てられた識別子(People の userId の localId と同義) |
ChatMessagePayload オブジェクトフィールド
メッセージを表すオブジェクトです。
| 値 | 説明 | 型 | 名前空間 | 補足 |
|---|---|---|---|---|
| message | メッセージ | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | – |
| stamp | スタンプ | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | ChatMessageStamp オブジェクト、POST時は指定不可 |
ChatMessageStamp オブジェクトフィールド
メッセージを表すオブジェクトです。
| 値 | 説明 | 型 | 名前空間 | 補足 |
|---|---|---|---|---|
| id | スタンプ ID | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | – |
| imageUrl | スタンプ画像の URL | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | – |
API リクエスト
HTTP メソッド
Trusted モデル
- GET
- メッセージ一覧の取得
- メッセージの取得
- POST
-
メッセージの投稿
warning
-
日本プラットーフォームでは、生年月日が未登録のユーザに関してはエラー 403 が返されます :::
チャットのメッセージの保存期間は、約 30 日となります。
エンドポイント URL
-
Sandbox 環境
http://sb.sp.app.mbga.jp/social/api/restful/v2/chat/{appId}/channels/{channelId}/messages/{-prefix|/|id} -
本番環境
http://sp.app.mbga.jp/social/api/restful/v2/chat/{appId}/channels/{channelId}/messages/{-prefix|/|id}
URI Template パラメータ
appId
appId パラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| @app | 現在実行中のアプリケーション ID | 必須 |
channelId
channelId パラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| {channelId} | チャンネル ID | 必須 |
id
id パラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| {id} | ChatMessage オブジェクトのメッセージ ID | 任意 |
クエリパラメータ
下記のクエリパラメータを指定する事が出来ます。
format
レスポンス形式を指定する事が出来ます。
| 値 | 説明 | 備考 |
|---|---|---|
| json | "application/json; charset=utf8" | 任意、デフォルト値 |
fields
取得したいチャンネル情報を指定する事が出来ます。指定可能なフィールド名については ChatMember オブジェクトフィールドを参照して下さい。
複数指定する場合はスペース無しのカンマ (,) 区切りで指定します。
fields パラメータを省略した場合、下記の属性情報全てを取得します。
パフォーマンス向上の為に、必要な属性のみを取得するようにして下さい。
count
コレクションリソースとしてレスポンスを取得する際に、最大何件のエントリリソースを取得するかを指定出来ます。
デフォルト値は 50 件で、最大 1000 件まで指定出来ます。
パフォーマンス向上の為に、必要な件数のみを取得するようにして下さい。
startIndex
コレクションリソースの開始値を指定します。省略時は 1 が指定されます。
sortBy
sortBy は ChatMember コレクションの取得時にのみ使う事が出来ます。
sortBy と sortOrder を指定すると、レスポンスとして返って来る ChatMember オブジェクトのコレクションに対してソート条件を加える事が出来ます。sortBy 値はソートのキーとなるフィールドを指定する事が出来ます。
現在指定可能な sortBy 値は以下の表になります。
| sortBy | 説明 |
|---|---|
| published | ChatMessage の送信日時 |
sortBy を指定する場合、sortOrder も指定されている必要があります。
sortOrder
sortOrder は Channel コレクションの取得時にのみ使う事が出来ます。
sortBy と sortOrder を指定すると、レスポンスとして返って来る ChatMember オブジェクトのコレクションに対してソート条件を加える事が出来ます。sortOrder 値はソート時の昇順、降順を指定する事が出来ます。
現在指定可能な sortOrder 値は以下の表になります。
| sortOrder | 説明 |
|---|---|
| ascending | 昇順 |
| descending | 降順 |
sortOrder を指定する場合、sortBy も指定されている必要があります。
API レスポンス
レスポンスコード
API のレスポンスコードは以下のいずれかになります。
| リクエスト HTTP メソッド | レスポンスコード | レスポンスメッセージ | 説明 |
|---|---|---|---|
| GET | 200 | OK | メッセージの取得に成功した場合 |
| POST | 201 | Created | メッセージの投稿が成功した場合 |
| GET/POST | 400 | Bad Request | データ形式が不正な場合 |
| GET/POST | 401 | Unauthorized | 不正な Authorization ヘッダの場合 |
| GET/POST | 403 | Forbidden | 実行しようと操作の権限がない場合 |
| GET/POST | 404 | Not Found | 存在しない appId, channelId, id が指定された場合 |
| GET/POST | 500 | Internal Server Error | サーバー側の処理でエラーが発生した場合 |
| GET/POST | 503 | Service Unavailable | サーバー側が一時的にサービス停止している場合 |
サンプル
メッセージ一覧の取得
リクエスト形式
GET /social/api/restful/v2/chat/@app/channels/100/messages?count=50&fields=id%2Cactor%2Cpayload%2Cpublished&sortBy=published&sortOrder=descending&startIndex=1
レスポンス形式
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry" : [
{
"id" : "10234123",
"actor" : {
"id" : "person:11241",
"objectType" : "person",
"localId" : "11241"
},
"payload" : {
"message" : "ぉぅぃぇーぃ"
},
"published" : "2013-04-04T15:22:43"
},
{
"id" : "10212981",
"actor" : {
"id" : "person:11241",
"objectType" : "person",
"localId" : "11241"
},
"payload" : {
"message" : "ょーぅ"
},
"published" : "2013-04-04T16:46:03"
}
],
"itemsPerPage" : 50,
"startIndex" : 1,
"totalResults" : 2
}
メッセージの取得
リクエスト形式
GET /social/api/restful/v2/chat/@app/channels/100/messages/12345612?fields=id%2Cactor%2Cpayload%2Cpublished
レスポンス形式
200 OK HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"id" : "100",
"actor" : {
"id" : "person:12345",
"objectType" : "person",
"localId" : "12345"
},
"payload" : {
"message" : "dollar underscore"
},
"published" : "2013-04-04T09:03:21"
}
メッセージの投稿
リクエスト形式
POST /social/api/restful/v2/chat/@app/channels/110/messages
Content-Type: application/json; charset=utf8
{
"actor" : {
"objectType" : "application",
"localId" : "12000001"
},
"payload" : {
"message" : "Hello world!"
}
}
レスポンス形式
201 Created
Content-Type: application/json; charset=utf-8
{
"id" : "123413563",
"actor" : {
"objectType" : "application",
"localId" : "12000001"
},
"payload" : {
"message" : "Hello world!"
},
"published" : "2013-04-04T09:48:17"
}
参考資料
The OAuth 1.0 Protocol (RFC 5849)
URI Template (RFC6570)
5.6. Internet Date/Time Format - Date and Time on the Internet: Timestamps (RFC 3339)
7.3.1. date-time - JSON Schema: interactive and non interactive validation draft-fge-json-schema-validation-00
更新履歴
- 2019/09/04
- ChatMessageStamp オブジェクトフィールドからlocalIdを削除しました。
- 2013/10/01
- OAuth Signed Request (xoauth_requestor_id) に関する記述を削除しました。
- 2013/08/13, 2013/08/23
- 生年月日が未登録のユーザに関する仕様変更。
- 2013/06/20
- サンプルの誤植の修正
- 2013/05/16
- stamp は POST 時に指定不可の旨を追記
- 2013/04/25
- 新規作成