Messaging リファレンス

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_idstring接続するクライアントの ID。
access_tokenstring登録済みクライアントの client_secret をキーとした、HS256 アルゴリズムで署名された Signed JWT。クレームに user_id, nbf, exp を含む。
extended_presencestring | object拡張プレゼンス。同じ user_id ですでに接続がある場合は上書きされる。最大文字数は 2048。object の場合は文字列にエンコードして 2048 文字まで。
Access Token

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

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

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

メッセージを作成する

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

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

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

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

メッセージを更新する

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

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

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

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

メッセージを削除する

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

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

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

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

メッセージを検索する

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

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

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

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

プレゼンスを更新する

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

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

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

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

PONG

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

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

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

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

受信メッセージ

接続の成功通知

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

要素名必須説明
message_type"connect_success"メッセージの種類。
channelsChannelの配列紐づけられているチャンネルの配列。
id-string接続する に id が指定されていた場合のみ存在する。指定された値と同じものが設定される。

メッセージの作成通知

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

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

メッセージの更新通知

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

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

メッセージの削除通知

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

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

メッセージの検索結果

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

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

チャンネルの更新通知

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

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

チャンネルへの招待通知

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

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

チャンネルの除外通知

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

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

プレゼンスの更新通知

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

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

PING

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

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

エラー

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

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

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

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

切断を伴うエラー

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

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

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

共通オブジェクト

Channel

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

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

Message

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

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

User

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

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

アプリサーバ用 REST API

概要

アプリサーバ用 REST API は、ユーザが接続するチャンネルの操作を行うための Messaging API である。全て client_id, client_secret で Basic 認証を行う。

エンドポイントは https://messaging.livestreaming.mw.smart-integration.ricoh.com/ である。

共通仕様

データ型定義

IDString

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

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

成功レスポンス

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

チャンネルオブジェクト
要素名必須説明
namestringチャンネルの名前。
channel_idstringチャンネルの ID。
user_idsIDString の配列チャンネルに所属するユーザーの ID の一覧。
チャンネルユーザオブジェクト
要素名必須説明
user_idIDStringユーザーの ID。

チャンネル一覧の取得

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

リクエスト

GET /channels

レスポンス

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

個別チャンネルの取得

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

リクエスト

GET /channels/{channel_id}

レスポンス

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

チャンネルの作成

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

リクエスト

POST /channels

リクエストボディ

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

レスポンス

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

チャンネルの更新

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

リクエスト

PUT /channels/{channel_id}

リクエストボディ

要素名必須説明
namestringチャンネルの名前。
user_idsstring の配列チャンネルに所属するユーザーの 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_idstringAPI を利用するプログラムが機械的に分岐することを意図したエラー内容の ID。
messagestringAPI を利用するプログラムの開発者のデバッグ補助になるエラーメッセージ。
リクエストステータスコードerror_id理由
共通401invalid_credential認証エラー
共通405method_not_allowedPath と Method がマッチしていない
共通500internal_server_errorサーバ内部での未知のエラー
PUT/DELETE channel
DELETE channel_user
404not_found指定された channel_id の Channel が存在しない
DELETE channel_user404-指定された user が channel 内に存在しない
POST channels
PUT channel
400invalid_requestrequest body が指定されていない、JSON 形式でないなど
POST channels
PUT channel
400invalid_namename が最大文字数を超えている、文字列でない、POST で指定されていない
POST channels
PUT channel
400invalid_user_idsuser_id が最大文字数を超えている、文字列の配列でない、POST channels で指定されていない
PUT channel_user400invalid_user_iduser_id が最大文字数を超えている、文字列でない

シーケンス

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

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

シーケンス