Messaging アプリクラアント用 API

Messaging API について

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

アプリクライアント用 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 を使用する。

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

JWT 仕様

ヘッダの"alg"属性および署名アルゴリズムは"HS256"のみ可
クレームセット(署名される JSON オブジェクト)は以下のオブジェクトを含むこと。記載されていない属性が含まれていた場合無視される

オブジェクト

属性名	型	必須	説明
nbf	int	〇	このトークンの有効期限の開始時刻。Unixtime。RFC7519で定義されている。 exp - nbf <= 3600(exp と nbf の差は 1 時間以内)でなければならない。
exp	int	〇	このトークンの有効期限の終了時刻。Unixtime。RFC7519で定義されている
user_id	IDString	〇	接続するユーザーの ID