Messaging リファレンス

目次

Messaging APIについて

Messaging APIは、現在β版として提供しております。
そのため、商用サービスでの利用をご検討される際には、必ず事前にお問い合わせください。
本β版の利用料金は無料です。正式版は有償での提供を検討しておりますので、あらかじめご了承ください。
正式版を公開せずにβ版の公開を終了する、もしくは、正式版ではβ版から機能や仕様が変更される可能性がありますので、あらかじめご了承ください。

アプリクライアント用API

本 API は WebSocket 経由で手軽にメッセージを交換するための API である。

Live Streaming APIと共通のクライアント情報でAPIの認可を行う。
ユーザはクライアントが別途認証したものを利用することとし、本 API ではユーザの認証は行わない。

送信メッセージ

送信メッセージについて記載する。メッセージをJSON形式で送信することでメッセージの交換を行う。

送信するメッセージに id 要素を含めた場合、connect に対する connect_success、query_messages に対する query_result、エラーメッセージなど、送信ユーザのみに返されるメッセージには同じ値を持つ id 要素が含まれる。
これにより、一度に複数のメッセージを送って対応を取りたい場合、id 要素を含めることで確認することができる。
なお、id 要素の一意性はメッセージの送信側で担保する必要がある。

接続する

接続の確立を行い、現在所属しているチャンネルの情報を取得できる。接続に成功すると、接続の成功通知のメッセージを受信する。また、成功後は所属しているチャンネルに対するメッセージの追加、変更やユーザの参加などが通知されるようになる。

別のコネクションであれば user_id は重複しても構わないが、同一ユーザとして扱われ、extended_presence は共有される。

現時点では先に指定されているものが優先され、あとから connect したユーザの extended_presence がそれまでと違っていた場合、あとから来た方にそれまでの presence が presence_updated メッセージで通知される。

要素名 必須 説明
message_type "connect" メッセージの種類。
id - string メッセージのID。指定した場合、接続の成功通知エラーのメッセージに同じ値を持つid要素が含まれる。最大文字数は64。
client_id string 接続するクライアントのID。
access_token string 登録済みクライアントのclient_secretをキーとした、HS256 アルゴリズムで署名された Signed JWT。クレームにuser_id, nbf, expを含む。
extended_presence string |
object
拡張プレゼンス。同じuser_idですでに接続がある場合は上書きされる。最大文字数は2048。objectの場合は文字列にエンコードして2048文字まで。
Access Token

接続の確立に認証としてAccess Tokenを使用する。

Access Token は client_id に対応する client_secret で HS256 で署名された JWTである。セキュリティ上 client_secret はアプリケーションのユーザに漏れてはならないため、アプリケーションが保有するサーバで生成することを想定する。

JWT仕様
  • ヘッダの"alg"属性および署名アルゴリズムは"HS256"のみ可
  • クレームセット(署名されるJSONオブジェクト)は以下のオブジェクトを含むこと。記載されていない属性が含まれていた場合無視される
オブジェクト
属性名 必須 説明
nbf int このトークンの有効期限の開始時刻。Unixtime。RFC7519で定義されている。
exp - nbf <= 3600(expとnbfの差は1時間以内)でなければならない。
exp int このトークンの有効期限の終了時刻。Unixtime。RFC7519で定義されている
user_id IDString 接続するユーザーのID

メッセージを作成する

チャンネルにメッセージを作成する。成功すると該当チャンネルに所属し、接続中のユーザ全てに、メッセージの作成通知のメッセージが送信される。

要素名 必須 説明
message_type "create_message" メッセージの種類。
id - string メッセージのID。指定した場合、メッセージの作成通知エラーのメッセージに同じ値を持つid要素が含まれる。最大文字数は64。
channel_id string 作成するチャンネルのID。
body string | object メッセージの中身。stringの場合、最大文字数は4096文字。objectの場合、最大文字数は文字列にエンコードして 300 万文字。
type string textの種別を表す分類文字列。Image, URLなど。最大文字数は255文字。

プロパティが不正な場合、以下の error_code を持った error メッセージが返される。

error_code          理由
channel_id.invalid 指定された channel_id を持つ channel に所属していないか存在しない場合、もしくは channel_id が指定されていない場合
body.invalid body が指定されていない場合、文字列か object でない場合、もしくは最長文字数を超えていた場合
type.invalid type が指定されていない場合、もしくは最長文字数を超えていた場合

メッセージを更新する

チャンネルの作成済みのメッセージを更新する。成功すると該当チャンネルに所属し、接続中のユーザ全てに、メッセージの更新通知のメッセージが送信される。

要素名 必須 説明
message_type "update_message" メッセージの種類。
id - string メッセージのID。指定した場合、メッセージの更新通知エラーのメッセージに同じ値を持つid要素が含まれる。最大文字数は64。
channel_id string 作成するチャンネルのID。
seq int 更新するメッセージのシーケンス番号。
body string | object メッセージの中身。create_message で指定するものと同様。
type string textの種別を表す分類文字列。Image, URLなど。最大文字数は255文字。

プロパティが不正な場合、以下の error_code を持った error メッセージが返される。

error_code          理由
channel_id.invalid 指定された channel_id を持つ channel に所属していないか存在しない場合、もしくは channel_id が指定されていない場合
seq.invalid seq が指定されていない場合、もしくは指定された seq を持つメッセージが存在しない場合
body.invalid body が指定されていない場合、文字列か object でない場合、もしくは最長文字数を超えていた場合
type.invalid type が指定されていない場合、もしくは最長文字数を超えていた場合
ownership.invald 指定されたメッセージの author_id が自分でない場合

メッセージを削除する

チャンネルに作成済みのメッセージを削除する。成功すると該当チャンネルに所属し、接続中のユーザ全てに、メッセージの削除通知のメッセージが送信される。

要素名 必須 説明
message_type "delete_message" メッセージの種類。
id - string メッセージのID。指定した場合、メッセージの削除通知エラーのメッセージに同じ値を持つid要素が含まれる。最大文字数は64。
channel_id string 作成するチャンネルのID。
seq int 削除するメッセージのシーケンス番号。

プロパティが不正な場合、以下の error_code を持った error メッセージが返される。

error_code          理由
channel_id.invalid 指定された channel_id を持つ channel に所属していないか存在しない場合、もしくは channel_id が指定されていない場合
seq.invalid seq が指定されていない場合、もしくは指定された seq を持つメッセージが存在しない場合
ownership.invald 指定されたメッセージの author_id が自分でない場合

メッセージを検索する

指定した範囲のメッセージを取得する。成功するとメッセージの検索結果のメッセージを受信する。メッセージには from から seq をさかのぼって count 件のメッセージが seq の順に含まれる。seq が現在の最大値よりも大きい場合、最新のメッセージから count 件が取得できる。

要素名 必須 説明
message_type "query_messages" メッセージの種類。
id - string メッセージのID。指定した場合、メッセージの検索結果エラーのメッセージに同じ値を持つid要素が含まれる。最大文字数は64。
channel_id string 取得するメッセージのチャンネルID。
from int 取得したいメッセージの seq の起点。
count - int 取得したいメッセージの数。指定可能な値は 1 ~ 100。デフォルトは100。

プロパティが不正な場合、以下の error_code を持った error メッセージが返される。

error_code          理由
channel_id.invalid 指定された channel_id を持つ channel に所属していないか存在しない場合、もしくは channel_id が指定されていない場合
from.invalid from が指定されていない場合、数値でない場合、もしくは 0 以下の場合
count.invalid count を指定した上で数値でない場合、もしくは指定可能範囲を超えていた場合

プレゼンスを更新する

プレゼンスを更新する。成功すると該当チャンネルに所属し、接続中のユーザ全てに、プレゼンスの更新通知のメッセージが送信される。

要素名 必須 説明
message_type "update_presence" メッセージの種類。
id - string メッセージのID。指定した場合、エラーのメッセージに同じ値を持つid要素が含まれる。最大文字数は64。
extended_presence string | object 拡張プレゼンス。最大文字数は2048。objectの場合は文字列にエンコードして2048文字まで。

プロパティが不正な場合、以下の error_code を持った error メッセージが返される。

error_code                    理由
extended_presence.invalid extended_presence が指定されていない場合、string と object 以外を指定した場合、もしくは最長文字数を超えていた場合

PONG

サーバからの接続確認メッセージに対する応答メッセージ。接続しているクライアントはPINGのメッセージを受け取った場合、即座にPONGメッセージを返す必要がある。5秒以内に届かなかった場合、サーバはクライアントが停止しているとみなし、接続を切断する。

要素名 必須 説明
message_type "pong" メッセージの種類。
payload string ping に payload が含まれていた場合、同じ文字列を設定する。

プロパティが不正な場合、以下の error_code を持った error メッセージが返される。

error_code 理由
payload.invalid 該当する payload を持った ping メッセージをサーバが送信していない場合

受信メッセージ

接続の成功通知

接続するに成功すると送信される。接続したチャンネル、参加しているユーザの一覧および、そのプレゼンスが含まれる。

要素名 必須 説明
message_type "connect_success" メッセージの種類。
channels Channelの配列 紐づけられているチャンネルの配列。
id - string 接続する に id が指定されていた場合のみ存在する。指定された値と同じものが設定される。
api_token string アプリクライアント用 REST API を利用するための token

メッセージの作成通知

メッセージを作成するに成功すると送信される。該当チャンネルに所属し、接続中のユーザ全てに送信され、メッセージの中身、種類を含む。

要素名 必須 説明
message_type "message_created" メッセージの種類。
channel_id string メッセージが作成されたチャンネルのID。
message Message 作成されたメッセージ。
id - string メッセージを作成する に id が指定されていた場合のみ存在し、指定された値と同じものが設定される。送信者のみに届く。

メッセージの更新通知

メッセージを更新するに成功すると送信される。該当チャンネルに所属し、接続中のユーザ全てに送信され、メッセージの中身、種類を含む。

要素名 必須 説明
message_type "message_updated" メッセージの種類。
channel_id string 更新されたメッセージのチャンネルのID。
message Message 更新されたメッセージ。
id - string メッセージを更新する に id が指定されていた場合のみ存在し、指定された値と同じものが設定される。送信者のみに届く。

メッセージの削除通知

メッセージを削除するに成功すると送信される。該当チャンネルに所属し、接続中のユーザ全てに送信される。

要素名 必須 説明
message_type "message_deleted" メッセージの種類。
channel_id string 削除されたメッセージのチャンネルのID。
seq int 削除されたメッセージのシーケンス番号。
id - string メッセージを削除する に id が指定されていた場合のみ存在し、指定された値と同じものが設定される。送信者のみに届く。

メッセージの検索結果

メッセージを検索するに成功すると送信される。

要素名 必須 説明
message_type "query_result" メッセージの種類。
id - string メッセージを検索する に id が指定されていた場合のみ存在し、指定された値と同じものが設定される。
channel_id string メッセージを検索する で指定した channel_id。
messages Messageの配列 メッセージを検索する で要求した message のリスト。指定の件数が seq の昇順に含まれる。

チャンネルの更新通知

REST API で所属しているチャンネルが更新されると送信される。該当チャンネルに所属し、接続中のユーザ全てに送信される。

要素名 必須 説明
message_type "channel_updated" メッセージの種類。
channnel Channnel 更新されたチャンネル。

チャンネルへの招待通知

新しくチャンネルが作成され、そこに所属した場合、または更新により所属ユーザに追加された場合に、そのチャンネルの情報が通知される。

要素名 必須 説明
message_type "invited_channel" メッセージの種類。
channel Channnel 新しく所属したチャンネル。

チャンネルの除外通知

所属しているチャンネルが削除された場合、または更新により所属ユーザから削除された場合に、そのチャンネルの情報が通知される。

要素名 必須 説明
message_type "banned_channel" メッセージの種類。
channel_id string 除外されたチャンネル。

プレゼンスの更新通知

プレゼンスを更新するに成功、または他のユーザが接続するに成功すると送信される。該当チャンネルに所属し、接続中のユーザ全てに送信され、プレゼンスが更新されたユーザの情報を含む。

要素名 必須 説明
message_type "presence_updated" メッセージの種類。
user User 除外されたチャンネル。

PING

サーバからの接続確認メッセージ。サーバから30秒ごとに送信されるため、それに対してPONGメッセージを返す必要がある。

要素名 必須 説明
message_type "pong" メッセージの種類。
payload string 何らかの文字列。指定されていた場合、pong メッセージに同じものを入れて返す必要がある。

エラー

クライアントが送ったメッセージが不正な場合に送信される。

要素名 必須 説明
message_type "error" メッセージの種類。
client_message_type string エラーの原因となった client の送ったメッセージの message_type。
error_code string エラーを特定するためのエラーコード。
id - string 送信メッセージに id が指定されていた場合のみ存在する。指定された値と同じものが設定される。

message_type に共通で、以下の error_code が返りうる。

error_code       理由
invalid_message connect 後の connect、存在しない message_type など、不正な message_type のメッセージが送られた
id.invalid id が指定されているが、string でない、もしくは最長文字数を超えている場合

切断を伴うエラー

以下のエラー時には close フレームにより WebSocket の接続が切断され、close コードと理由が返される

エラー概要       close コード   理由 詳細
不正メッセージ 3400 BAD-ARGS メッセージが JSON でない場合、message_type が含まれていない場合、認証前に connect 以外の message を送った場合など
PONG タイムアウト 3401 PONG-TIMEOUT サーバが PONG を送出後、5 秒以内に対応する PING が届かなかった場合
不正フレーム 3402 BAD-FRAME websocket の binary フレームを送信した場合
内部エラー 3403 INTERNAL-ERROR サーバ内部で何らかのエラーが起きた場合
認証失敗 3404 ACCESS-TOKEN-VERIFICATION-FAILED connect メッセージの不備によりアクセストークンの検証に失敗した場合

上記の他に、WebSocket の Close イベントで定義されている Code 及び Reason が返る可能性がある

共通オブジェクト

Channel

チャンネルを表すオブジェクト。チャンネルに作成されたメッセージの一覧、所属するユーザの一覧を含む。

要素名        必須 型         説明
channel_id string チャンネルのID。
latest_seq int チャンネルに送信されたメッセージの最後の seq。接続の成功通知チャンネルへの招待通知のときのみ含まれる。
users Userの配列 チャンネルに所属するユーザーの一覧。

Message

メッセージを表すオブジェクト。

要素名 必須 説明
seq int チャンネル内で振られたシーケンス番号。
author_id string メッセージを書き込んだ User の user_id。
body string | object 書き込まれた中身。
type string textの種別を表す分類文字列。Image, URLなど。
revision int 改定された回数。
created_at int 作成時刻のUNIX time。サーバで登録が確定した時刻。
updated_at int 最終更新時刻のUNIX time。サーバで更新が確定した時刻。

User

ユーザを表すオブジェクト。

要素名 必須 説明
user_id string ユーザのID。
presence string ユーザの状態。"online"、もしくは"offline"。
extended_presence - string | object | null 拡張プレゼンス。presenceが"offline"の場合はnull。

アプリサーバ用 REST API

ユーザが接続するチャンネルの操作を行うREST API。全てclient_id, client_secretでBasic認証を行う。

共通仕様

データ型定義

IDString

主にアプリケーションが生成する ID で利用する。

  • 1 文字以上 255 文字以下
  • ASCII
  • 以下の文字のみ許可
    • 英数字
    • 次の記号: .%+^_"`{|}~<>\-

成功レスポンス

レスポンスは成功の場合JSON形式(application/json)で、以下のオブジェクトで返却される。

チャンネルオブジェクト
要素名 必須 説明
name string チャンネルの名前。
channel_id string チャンネルのID。
user_ids IDStringの配列 チャンネルに所属するユーザーのIDの一覧。
チャンネルユーザオブジェクト
要素名 必須 説明
user_id IDString ユーザーのID。

チャンネル一覧の取得

全てのチャンネルの情報を取得する。

リクエスト

GET /channels

レスポンス

HTTPステータスコード200と、ボディに全てのチャンネルの配列。

個別チャンネルの取得

指定したチャンネルの情報を取得する。

リクエスト

GET /channels/{channel_id}

レスポンス

HTTPステータスコード200と、ボディに指定したチャンネル。

チャンネルの作成

チャンネルを作成する。成功すると該当チャンネルに所属し、接続中のユーザ全てに、チャンネルへの招待通知のメッセージが送信される。

リクエスト

POST /channels

リクエストボディ

要素名 必須 説明
name string チャンネルの名前。
user_ids stringの配列 チャンネルに所属するユーザーのIDの一覧。

レスポンス

HTTPステータスコード201と、ボディに作成したチャンネル。

チャンネルの更新

チャンネルを更新する。成功すると新たに該当チャンネルに所属し、接続中のユーザ全てに、チャンネルへの招待通知のメッセージが送信される。また、削除された接続中のユーザ全てに、チャンネルの除外通知のメッセージが送信される。

リクエスト

PUT /channels/{channel_id}

リクエストボディ

要素名 必須 説明
name string チャンネルの名前。
user_ids stringの配列 チャンネルに所属するユーザーのIDの一覧。

レスポンス

HTTPステータスコード200と、ボディに作成したチャンネル。

チャンネルの削除

チャンネルを削除する。成功すると所属していた接続中のユーザ全てに、チャンネルの除外通知のメッセージが送信される。

リクエスト

DELETE /channels/{channel_id}

レスポンス

HTTPステータスコード204。

チャンネルへのユーザの追加

チャンネルにユーザを追加する。 成功すると新たに該当チャンネルに所属したユーザが接続中だったらチャンネルへの招待通知のメッセージが送信される。

リクエスト

PUT /channels/{channel_id}/users/{user_id}

リクエストボディ

なし

レスポンス

HTTPステータスコード200と、ボディに追加したユーザ。

チャンネルからのユーザの削除

チャンネルからユーザを削除する。成功すると削除されたユーザが接続中だったらチャンネルの除外通知のメッセージが送信される。

リクエスト

DELETE /channels/{channel_id}/users/{user_id}

レスポンス

HTTPステータスコード204。

エラー

リクエストに対し、失敗時には以下のエラーが返される。エラーコードがある場合、レスポンスボディに以下のスキーマの application/json として返る。

要素名 必須 説明
error_id string API を利用するプログラムが機械的に分岐することを意図したエラー内容の ID。
message string API を利用するプログラムの開発者のデバッグ補助になるエラーメッセージ。
リクエスト ステータスコード error_id 理由
共通 401 invalid_credential 認証エラー
共通 405 method_not_allowed Path と Method がマッチしていない
共通 500 internal_server_error サーバ内部での未知のエラー
PUT/DELETE channel
DELETE channel_user
404 not_found 指定された channel_id の Channel が存在しない
DELETE channel_user 404 - 指定された user が channel 内に存在しない
POST channels
PUT channel
400 invalid_request request body が指定されていない、JSON 形式でないなど
POST channels
PUT channel
400 invalid_name name が最大文字数を超えている、文字列でない、POST で指定されていない
POST channels
PUT channel
400 invalid_user_ids user_id が最大文字数を超えている、文字列の配列でない、POST channels で指定されていない
PUT channel_user 400 invalid_user_id user_id が最大文字数を超えている、文字列でない

シーケンス

アプリクライアント用 APIアプリサーバ用 REST APIを使用したシーケンスを以下に示す。

チャンネルの生成、接続、メッセージの作成などを行うシーケンスになっている。

シーケンス