Messaging API は、現在 β 版として提供しております。
そのため、商用サービスでの利用をご検討される際には、必ず事前にお問い合わせください。
本 β 版の利用料金は無料です。正式版は有償での提供を検討しておりますので、あらかじめご了承ください。
正式版を公開せずに β 版の公開を終了する、もしくは、正式 版では β 版から機能や仕様が変更される可能性がありますので、あらかじめご了承ください。
アプリクライアント用 API は、WebSocket 経由で手軽にメッセージを交換するための Messaging API である。
Live Streaming API と共通のクライアント情報で API の認可を行う。 ユーザはクライアントが別途認証したものを利用することとし、本 API ではユーザの認証は行わない。
エンドポイントは wss://messaging.livestreaming.mw.smart-integration.ricoh.com/messaging/ である。
送信メッセージについて記載する。メッセージを 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 | 接続するクライアントの ClientID。 |
access_token | 〇 | string | 登録済みクライアントの ClientSecret をキーとした、HS256 アルゴリズムで署名された Signed JWT。クレームに user_id, nbf, exp を含む。 |
extended_presence | 〇 | string | object | 拡張プレゼンス。同じ user_id ですでに接続がある場合は上書きされる。最大文字数は 2048。object の場合は文字列にエンコードして 2048 文字まで。 |
接続の確立に認証として Access Token を使用する。
Access Token は ClientID に対応する ClientSecret で HS256 で署名された JWT である。セキュリティ上 ClientSecret はアプリケーションのユーザに漏れてはならないため、アプリケーションが保有するサーバで生成することを想定する。
"alg"
属性および署名アルゴリズムは"HS256"
のみ可属性名 | 型 | 必須 | 説明 |
---|---|---|---|
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 以外を指定した場合、もしくは最長文字数を超えていた場合 |
サーバからの接続確認メッセージに対する応答メッセージ。接続しているクライアントは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 が指定されていた場合のみ存在する。指定された値と同じものが設定される。 |
access_token_info | 〇 | object | access_token の JWT クレームセット。 |
メッセージを作成するに成功すると送信される。該当チャンネルに所属し、接続中のユーザ全てに送信され、メッセージの中身、種類を含む。
要素名 | 必須 | 型 | 説明 |
---|---|---|---|
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 | 除外されたチャンネル。 |
サーバからの接続確認メッセージ。サーバから 30 秒ごとに送信されるため、それに対してPONGメッセージを返す必要がある。
要素名 | 必須 | 型 | 説明 |
---|---|---|---|
message_type | 〇 | "ping" | メッセージの種類。 |
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_id | 〇 | string | チャンネルの ID。 |
latest_seq | 〇 | int | チャンネルに送信されたメッセージの最後の seq。接続の成功通知かチャンネルへの招待通知のときのみ含まれる。 |
users | 〇 | Userの配列 | チャンネルに所属するユーザーの一覧。 |
メッセージを表すオブジェクト。
要素名 | 必須 | 型 | 説明 |
---|---|---|---|
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_id | 〇 | string | ユーザの ID。 |
presence | 〇 | string | ユーザの状態。"online"、もしくは"offline"。 |
extended_presence | - | string | object | null | 拡張プレゼンス。presence が"offline"の場合は null。 |
この情報は役に立ちましたか?