外部サービス連携APIについて
DiSCUS を外部システムから利用する手段として、Webhookや外部連携用APIと言った機能が用意されています。本記事では外部連携 API について説明します。
外部連携 API は、前述通り DiSCUS の機能を外部のシステムから利用するためのAPIです。
外部連携 API を利用することにより、以下のようなシステム間連携を行う事が出来ます。
・任意の外部システムからの出力を、DiSCUS のチャット上に表示する
・DiSCUS のチャットに入力された内容を、任意の外部システムへの入力に用いる
※API機能はサービス開始後5営業日以降に利用いただけます。
【この記事の内容】
■API一覧
・認証系API
ー認可エンドポイント
ートークンエンドポイント（トークン新規発行）
ートークンエンドポイント（アクセストークン再発行）
ートークン無効化エンドポイント
ーユーザー情報エンドポイント
ーROBOTID OpenIdConnect スコープ仕様
・実行系API
ートークの作成
ートークの削除
ートークの参加メンバー更新
ーテキストメッセージの作成
ーファイルメッセージの作成
ー動画メッセージの作成
ー位置情報メッセージの作成
・参照系API
ートークの取得
ートーク一覧の取得
ーメッセージ一覧の取得
認証系API（OpenIdConnect API仕様）
認可エンドポイント
クライアント情報をもとにユーザーの認証・認可を行うエンドポイントです。
リクエストURL
https://robotid.jp/oidc-auth/authorize
リクエストHTTPメソッド
GET
リクエストパラメタ
| パラメタ名 | 必須 | 説明 |
|---|---|---|
| client_id | ○ | OpenId管理コンソールのクライアント情報登録で登録したクライアントID |
| redirect_uri | ○ | 認可処理完了後に、認可コードをリダイレクトするためのURI OpenId管理コンソールのクライアント情報登録で登録した承認済みリダイレクトURIを指定 |
| response_type | ○ | 認可フロータイプ "code"を固定で指定（Authorization Code Flow） |
| scope | ○ | 要求するアクセス権限を表すスコープID 複数指定する場合は半角スペース区切りで指定 指定可能なスコープIDおよびスコープの詳細については、「OpenIdConnect スコープ仕様」シートに記載 |
| state | CSRF対策として同一のセッションである事を確認するために使用するパラメータ 同パラメタが指定された場合に、レスポンスにstateパラメタを含め、値としてリクエストで受け取ったstate値と同じ値を設定して返却 |
|
| nonce | リプレイアタック攻撃に対する対策を実施するために使用するパラメタ リクエストで同パラメタが指定された場合に、IDトークンにリクエストで送られてきたnonce値と同じ値を設定する。クライアント側でIDトークンに含まれるnonce値と認可リクエスト時に送信したnonce値が同一かを検証する事でリプレイアタック攻撃を防止する |
リクエスト具体例
GET /oidc-auth/authorize?
client_id=client_sample
&redirect_uri=https://example.com/home
&response_type=code
&scope=ks3_user_tenant%20address%20phone%20openid%20profile%20offline_access
&state=bd83xwghJW
&nonce=roWfwEbRU0G8HO0WpuR7R2GTCE5uru
HTTP/1.1
Host: robotid.jp
レスポンス形式
リダイレクト
レスポンスデータ
| パラメタ名 | 必須 | 説明 |
|---|---|---|
| code | ○ | アクセストークン発行時に使用する認可コード |
| state | リクエストでstateパラメタが指定された場合に、値としてリクエストで受け取ったstate値と同じ値を設定して返却 |
レスポンス具体例
HTTP/1.1 302 Found
Location: https://example.com/home?
code=teqRmyiGXkSqb0Hbjpqnnz
&state=bd83xwghJW
トークンエンドポイント（トークン新規発行）
アクセストークン・リフレッシュトークンの新規発行を行いたい場合に、リクエストパラメタに認可コードの識別子および認可コードを指定し、トークンエンドポイントにリクエストを行い、トークンの新規発行をします。
リクエストURL
https://robotid.jp/oidc-auth/token
リクエストHTTPメソッド
POST
リクエストヘッダ
| ヘッダ名 | 必須 | 説明 |
|---|---|---|
| Authorization | △※1 | クライアント認証用のBasic認証値 値としてOpenId管理コンソールのクライアント情報登録で登録したクライアント情報（IDとシークレット）をBase64エンコードしたものを指定する （指定例）Authorization: Basic XXXXX ※ XXXXXの箇所にクライアントIDとシークレットを":"(コロン)で連結してBase64エンコードした値を指定 |
リクエストボディ
| パラメタ名 | 必須 | 説明 |
|---|---|---|
| grant_type | ○ | "authorization_code"を固定で設定 |
| code | ○ | 認可エンドポイントのリクエストで取得した認可コードを指定 |
| redirect_uri | ○ | トークン発行処理完了後に、トークンをリダイレクトするためのURI OpenId管理コンソールのクライアント情報登録で登録した承認済みリダイレクトURIを指定 |
| client_id | △※ | OpenId管理コンソールのクライアント情報登録で登録したクライアントID クライアント認証で使用 |
| client_secret | △※ | OpenId管理コンソールのクライアント情報登録で登録したクライアントシークレット クライアント認証で使用 |
※リクエスト時にクライアント認証を行うため、ヘッダのAuthorization設定、もしくはリクエストボディのclient_id,client_secretのいずれかが必須となります。いずれかが設定されている場合はもう一方のほうは設定不要です。
リクエスト具体例
POST /oidc-auth/token HTTP/1.1
Host: robotid.jp
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=teqRmyiGXkSqb0Hbjpqnnz
&redirect_uri=https://example.com/home
&client_id=client_sample
&client_secret=L3bukGfVnG_AlAGs3gHmVti1tXppcnMjYjpv_kqG0OBvy8b0GY
レスポンス形式
JSON
レスポンスデータ
| パラメタ名 | 必須 | 説明 |
|---|---|---|
| access_token | ○ | アクセストークン 外部連携APIを実行する際の認証で使用 |
| token_type | ○ | 発行されたトークンタイプ Bearer固定 |
| refresh_token | アクセストークン再発行時に使用するリフレッシュトークン 同トークンが必要な場合、認可リクエスト時のスコープで"offline_access"を指定する必要がある |
|
| expires_in | ○ | アクセストークンの有効期限（秒単位） |
| scope | ○ | アクセストークンに紐づくスコープ スコープが複数ある場合は半角スペース区切りでスコープを返却 |
| id_token | IDトークン OpenIdConnectで認証した際に付与される、個人を識別可能なトークン |
レスポンス具体例
HTTP/1.1 200 OK
cache-control: no-store
pragma: no-cache
content-type: application/json;charset=UTF-8
{
"access_token": "3L5qQWVP0J",
"token_type": "Bearer",
"refresh_token": "cr2R5fEf2y",
"expires_in": 3599,
"scope": "ks3_user_tenant address phone openid offline_access profile",
"id_token": "KoFFk1gEaxjc6b0cTTa2yAwgpoIuYR"
}
トークンエンドポイント（アクセストークン再発行）
アクセストークンの再発行（リフレッシュ）を行いたい場合に、リクエストパラメタに再発行の識別子およびリフレッシュトークンを指定し、トークンエンドポイントにリクエストを行って再発行します。
リクエストURL
https://robotid.jp/oidc-auth/token
リクエストHTTPメソッド
POST
リクエストヘッダ
| ヘッダ名 | 必須 | 説明 |
|---|---|---|
| Authorization | △※ | クライアント認証用のBasic認証値 値としてOpenId管理コンソールのクライアント情報登録で登録したクライアント情報（IDとシークレット）をBase64エンコードしたものを指定する （指定例）Authorization: Basic XXXXX ※ XXXXXの箇所にクライアントIDとシークレットを":"(コロン)で連結してBase64エンコードした値を指定 |
リクエストボディ
| パラメタ名 | 必須 | 説明 |
|---|---|---|
| grant_type | ○ | "refresh_token"を固定で設定 |
| refresh_token | ○ | トークン新規発行リクエストで取得したリフレッシュトークンを指定 |
| client_id | △※ | OpenId管理コンソールのクライアント情報登録で登録したクライアントID クライアント認証で使用 |
| client_secret | △※ | OpenId管理コンソールのクライアント情報登録で登録したクライアントシークレット クライアント認証で使用 |
※リクエスト時にクライアント認証を行うため、ヘッダのAuthorization設定、もしくはリクエストボディのclient_id,client_secretのいずれかが必須となります。いずれかが設定されている場合はもう一方のほうは設定不要
リクエスト具体例
POST /oidc-auth/token HTTP/1.1
Host: robotid.jp
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token=cr2R5fEf2y
&client_id=client_sample
&client_secret=L3bukGfVnG_AlAGs3gHmVti1tXppcnMjYjpv_kqG0OBvy8b0GY
レスポンス形式
JSON
レスポンスデータ
| パラメタ名 | 必須 | 説明 |
|---|---|---|
| access_token | ○ | アクセストークン 外部連携APIを実行する際の認証で使用 |
| token_type | ○ | 発行されたトークンタイプ Bearer固定 |
| refresh_token | アクセストークン再発行時に使用するリフレッシュトークン 同トークンが必要な場合、認可リクエスト時のスコープで"offline_access"を指定する必要がある |
|
| expires_in | ○ | アクセストークンの有効期限（秒単位） |
| scope | ○ | アクセストークンに紐づくスコープ スコープが複数ある場合は半角スペース区切りでスコープを返却 |
| id_token | IDトークン OpenIdConnectで認証した際に付与される、個人を識別可能なトークン |
トークン無効化エンドポイント
アクセストークンまたはリフレッシュトークンの無効化を行いたい場合に、リクエストパラメタにトークンを指定し、トークン無効化エンドポイントにリクエストを行ってトークンを無効化します。
リクエストURL
https://robotid.jp/oidc-auth/revoke
リクエストHTTPメソッド
POST
リクエストヘッダ
| ヘッダ名 | 必須 | 説明 |
|---|---|---|
| Authorization | △※ | クライアント認証用のBasic認証値 値としてOpenId管理コンソールのクライアント情報登録で登録したクライアント情報（IDとシークレット）をBase64エンコードしたものを指定する （指定例）Authorization: Basic XXXXX ※ XXXXXの箇所にクライアントIDとシークレットを":"(コロン)で連結してBase64エンコードした値を指定 |
リクエストボディ
| パラメタ名 | 必須 | 説明 |
|---|---|---|
| token | ○ | 無効化したいアクセストークンまたは無効化したいリフレッシュトークンを指定 |
| client_id | △※ | OpenId管理コンソールのクライアント情報登録で登録したクライアントID クライアント認証で使用 |
| client_secret | △※ |
OpenId管理コンソールのクライアント情報登録で登録したクライアントシークレット クライアント認証で使用 |
※リクエスト時にクライアント認証を行うため、ヘッダのAuthorization設定、もしくはリクエストボディのclient_id,client_secretのいずれかが必須となります。いずれかが設定されている場合はもう一方は設定不要です。
リクエスト具体例
POST /oidc-auth/revoke HTTP/1.1
Host: robotid.jp
Content-Type: application/x-www-form-urlencoded
token=3L5qQWVP0J
&client_id=client_sample
&client_secret=L3bukGfVnG_AlAGs3gHmVti1tXppcnMjYjpv_kqG0OBvy8b0GY
レスポンスデータ
HTTPステータスコード（正常終了時：200(OK)、エラー時：403(Forbidden)）のみ返却
レスポンス具体例
HTTP/1.1 200 OK
cache-control: no-store
pragma: no-cache
ユーザー情報エンドポイント
トークンポイントのリクエストで取得したアクセストークンをもとに、ユーザー情報を取得するためのエンドポイント
リクエストURL
https://robotid.jp/oidc-auth/userinfo
リクエストHTTPメソッド
GET
リクエストヘッダ
| ヘッダ名 | 必須 | 説明 |
|---|---|---|
| Authorization | ○ | トークンポイントのリクエストで取得したアクセストークンを値として設定して認証 （指定例）Authorization: Bearer XXXXX ※ XXXXXの箇所にアクセストークンを指定 |
リクエスト具体例
GET /oidc-auth/userinfo HTTP/1.1
Host: robotid.jp
Authorization: Bearer 3L5qQWVP0J
レスポンス形式
JSON
レスポンスデータ
| パラメタ名 | 必須 | 説明 |
|---|---|---|
| sub | アカウントのログインID アクセストークンに紐づくスコープに"openid"が存在する場合に同情報を返却 |
|
| name | アカウントの姓＋名 アクセストークンに紐づくスコープに"profile"が存在する場合に同情報を返却 |
|
| given_name | アカウントの名 アクセストークンに紐づくスコープに"profile"が存在する場合に同情報を返却 |
|
| family_name | アカウントの姓 アクセストークンに紐づくスコープに"profile"が存在する場合に同情報を返却 |
|
| middle_name | アカウントのミドルネーム アクセストークンに紐づくスコープに"profile"が存在する場合に同情報を返却 |
|
| アカウントのメールアドレス アクセストークンに紐づくスコープに"email"が存在する場合に同情報を返却 |
||
| phone_number | アカウントの電話番号 アクセストークンに紐づくスコープに"phone"が存在する場合に同情報を返却 |
|
| address | トークン発行時のクライアントが所属する企業の住所（都道府県＋市区町村＋番地・建物名） アクセストークンに紐づくスコープに"address"が存在する場合に同情報を返却 |
|
| ks3_custom_attribute | トークン発行時のクライアントが所属する企業のカスタム属性について、配列形式（配列の中身はカスタム属性の名前・値を設定したJSON）で設定 アクセストークンに紐づくスコープに"ks3_custom_attribute"が存在する場合に同情報を返却 |
|
| ks3_tenant_id | トークン発行時のクライアントが所属する企業の企業UID アクセストークンに紐づくスコープに"ks3_user_tenant"が存在する場合に同情報を返却 |
|
| ks3_tenant_name | トークン発行時のクライアントが所属する企業の企業名 アクセストークンに紐づくスコープに"ks3_user_tenant"が存在する場合に同情報を返却 |
|
| ks3_tenant_phone | トークン発行時のクライアントが所属する企業の電話番号 アクセストークンに紐づくスコープに"ks3_user_tenant"が存在する場合に同情報を返却 |
|
| ks3_tenant_email | トークン発行時のクライアントが所属する企業のメールアドレス アクセストークンに紐づくスコープに"ks3_user_tenant"が存在する場合に同情報を返却 |
※各スコープの詳細については、「OpenIdConnect スコープ仕様」シートに記載
レスポンス具体例
HTTP/1.1 200 OK
cache-control: no-store
pragma: no-cache
content-type: application/json;charset=UTF-8
{
"sub": "yamadatest",
"address": "東京都港区1-2-3テストビル5F",
"ks3_tenant_name": "ABC株式会社",
"ks3_tenant_phone": "0312345678",
"name": "太郎 山田",
"ks3_custom_attribute": [
{
"value": "yamada001@example.co.jp",
"key": "サンプルサイト用メールアドレス"
},
{
"value": "1",
"key": "サンプルサイトユーザー権限"
}
],
"given_name": "太郎",
"middle_name": "",
"family_name": "山田",
"email": "tarou.yamada@example.co.jp",
"ks3_tenant_id": "ro7jrw"
}
ROBOTID OpenIdConnect スコープ仕様
スコープとして、大きく以下の3種類を登録・使用可能です、
①システムスコープ（デフォルト）
OpenIDConnectの仕様で定義されているスコープ。デフォルトでDBに登録しておき、ユーザが使用可能にする。
②システムスコープ（ユーザ定義）
システムスコープについて、ユーザが独自にスコープを登録・編集可能とする。
③APIスコープ
ユーザが利用するAPIのスコープ。システム管理者がスコープを管理画面上から登録。ユーザは管理画面上からAPIの有効設定をする事により利用可能となる。
デフォルトのシステムスコープ一覧
RobotID OpenIdConnectにデフォルトで登録されているシステムスコープは以下となります。
| パラメタ名 | 表示名 | 説明 |
|---|---|---|
| openid | OpenID | OpenID Connectの要求スコープ。指定無しの場合もエラーとはしないが、指定無しの場合、IDトークンを返却しない |
| profile | プロフィール | ・認可リクエストで同スコープが指定された場合、アクセストークンでユーザのプロフィール情報の取得を可能とする。 ・同スコープ権限を持つアクセストークンにて、ユーザ情報取得要求がRobotIDにあった場合、アカウント情報のプロフィール（姓、名、ミドルネーム、タイムゾーン）を返却 |
| ・認可リクエストで同スコープが指定された場合、アクセストークンでユーザのe-mail情報の取得を可能とする。 ・同スコープ権限を持つアクセストークンにて、ユーザ情報取得要求がRobotIDにあった場合、アカウント情報のe-mail情報（メールアドレス、通知用メールアドレス）を返却 |
||
| address | 住所 | ・認可リクエストで同スコープが指定された場合、アクセストークンでユーザの住所情報の取得を可能とする。 ・同スコープ権限を持つアクセストークンにて、ユーザ情報取得要求がRobotIDにあった場合、企業情報の住所情報（国、郵便番号、都道府県、市区郡、町名・番地・建物名）を返却 |
| phone | 電話番号 | ・認可リクエストで同スコープが指定された場合、アクセストークンでユーザの電話番号情報の取得を可能とする。 ・同スコープ権限を持つアクセストークンにて、ユーザ情報取得要求がRobotIDにあった場合、アカウント情報の電話番号情報（会社電話番号、携帯電話番号）を返却 |
| offline_access | オフラインアクセス | ユーザがオフライン（RobotIDに未ログイン）の状態でもアクセストークンの再発行・トークン利用によるAPIアクセスを可能にするスコープ。 具体的にはリフレッシュトークンを発行する事によりユーザにオフライン状態でのアクセストークン再発行を可能にさせる。同スコープが指定された場合、RobotIDは以下の挙動とする。 ・同スコープが認可リクエストで指定された場合にリフレッシュトークンを発行する ・同スコープが認可リクエストで指定された場合、同意画面を表示するが、同意画面は初回リクエスト時のみ表示し、以降はリフレッシュトークン有効期限まで表示しない。期限切れの場合は同意画面を再度表示 |
実行系API
トークの作成
| URL(パス) | /api/chat/create-talk |
|---|---|
| Content-Type | multipart/form-data |
リクエストボディ（multipart/form-data）
| 必須 | name | 形式 | 内容・補足 | |
|---|---|---|---|---|
| 第１パート | 〇 | "Control" | JSONデータ | トーク作成パラメータ（後述） |
| 第２パート |
|
"Original" | 画像ファイルデータ | トーク画像ファイル。 有効な形式は jpg / jpeg / gif / png |
※第１パート（Control）に指定するJSON内容詳細
| 必須 | 形式 | 概要 | 補足 | |||
|---|---|---|---|---|---|---|
| Talk | 〇 | Object | ||||
| Properties | 〇 | Object | ||||
| TalkName | 〇 | String | トーク名 | 最大 100 文字まで | ||
| TalkDescription |
― |
String | トーク説明 | 最大 500 文字まで | ||
| TalkLabel | ― | String | トークのラベル色 | 16進数のカラーコード形式で指定 | ||
| TalkIconFileName | ― | String | トーク画像を設定する場合に指定 | multipart の第２パート（Original）に指定するファイルのファイル名 | ||
| TalkTagList | ― | String[] | タグ。複数を指定可能 | |||
| UtilizationControl | 〇 | Object | トークの参加者指定 | UserList、OrganizationList の少なくとも一方は指定する必要がある | ||
| UserList | ― | UUID[] | ユーザ単位でのトーク参加者指定 | ユーザIDで指定。最大100ユーザまで | ||
| OrganizationList | ― | UUID[] | 組織単位でのトーク参加者指定 | 組織IDで指定。最大100組織まで | ||
レスポンス JSON
| 必須 | 形式 | 概要 | ||
|---|---|---|---|---|
| AppStatus | 〇 | Object | ― | |
| Code | 〇 | String | ― | |
| Message | ― | String | ― | |
| CreateTalkResult | ― | Object | API が正常終了した場合のみ、値が存在する | |
| TalkID | ― | UUID | 作成されたトークのID | |
※固有の終了コード
| Code | Message | 概要 | 補足（主な原因など） |
|---|---|---|---|
| E041 | INVALID_PARAMETER | パラメータ異常 | multipart/form-data 形式でのアクセスになっていない |
| Control パートが存在しない | |||
| トーク名等の必須項目が指定されていない | |||
| トーク参加者に問題がある（未指定、上限数を超えている、など） | |||
| トーク画像ファイルが正しく送信されていない | |||
| E051 | NOT_EXIST_DATA | 存在しないデータ | トーク参加者に問題がある（存在しないユーザ、組織） |
| E199 | REQUEST_FAILURE | その他のエラー | ― |
トークの削除
| URL(パス) | /api/chat/delete-talk |
|---|---|
| Content-Type | application/json |
リクエストボディ（JSON）
| 必須 | 形式 | 内容 | 補足 | ||||
|---|---|---|---|---|---|---|---|
| Param | 〇 | Object | |||||
| ToData | 〇 | Object | |||||
| TalkID | 〇 | UUID | 削除対象トークのトークID | ||||
レスポンス（JSON）
| 必須 | 形式 | 内容 | 補足 | ||||
|---|---|---|---|---|---|---|---|
| AppStatus | 〇 | Object | API の実行情報 | ||||
| Code | 〇 | String | 終了コード | ||||
| Message | String | メッセージ | |||||
API 固有の終了コード
| Code | Message | 概要 | 補足（主な原因など） |
| E041 | INVALID_PARAMETER | パラメータ異常 | multipart/form-data 形式でのアクセスになっていない |
| Control パートが存在しない | |||
| Original パートが存在しない | |||
| トークIDなどの必須項目が指定されていない | |||
| 指定されている返信元メッセージIDが不適当（存在しない、削除済み、など） | |||
| 添付ファイルが正しく送信されていない | |||
| テナントの設定で許可されていないファイル形式 | |||
| E021 | NO_PERMISSION | 権限エラー | テナントの設定で添付メッセージの作成が認められていない |
| E051 | NOT_EXIST_DATA | 存在しないデータ | 対象のトークが存在しない（対象トークに参加していない場合含む） |
| E199 | REQUEST_FAILURE | その他のエラー |
トーク参加メンバーの更新
| URL(パス) | /api/chat/update-talk-mamber |
|---|---|
| Content-Type | application/json |
リクエストボディ（JSON）
| 必須 | 形式 | 内容 | 補足 | |||||
|---|---|---|---|---|---|---|---|---|
| Param | 〇 | Object | ||||||
| ToData | 〇 | Object | ||||||
| TalkID | 〇 | UUID | 変更対象トークのトークID | |||||
| UtilizationControl | 〇 | Object | トークの参加者指定 | UserList、OrganizationList の少なくとも一方は指定する必要がある | ||||
| UserList | UUID[] | ユーザ単位でのトーク参加者指定 | ユーザIDで指定。最大100ユーザまで | |||||
| OrganizationList | UUID[] | 組織単位でのトーク参加者指定 | 組織IDで指定。最大100組織まで | |||||
レスポンス JSON
| 必須 | 形式 | 内容 | 補足 | ||||
|---|---|---|---|---|---|---|---|
| AppStatus | 〇 | Object | API の実行情報 | ||||
| Code | 〇 | String | 終了コード | ||||
| Message | String | メッセージ | |||||
API 固有の終了コード
| Code | Message | 概要 | 補足（主な原因など） | ||
|---|---|---|---|---|---|
| E041 | INVALID_PARAMETER | パラメータ異常 | トーク参加者に問題がある（未指定、上限数を超えている、など） | ||
| E051 | NOT_EXIST_DATA | 存在しないデータ |
変更対象トークが存在しない（該当トークの参加者でない場合含む）
トーク参加者に問題がある（存在しないユーザ、組織） |
||
| E056 | CANNOT_REDUCE_MEMBER_TO_ZERO | 参加者０名には出来ない | ※参加者が０名になるとトークを制御できるユーザがいなくなるため | ||
| E199 | REQUEST_FAILURE | その他のエラー | |||
テキストメッセージの作成
| URL(パス) | /api/chat/post-message |
|---|---|
| Content-Type | application/json |
リクエストボディ（JSON）
| 必須 | 形式 | 内容 | 補足 | ||
|---|---|---|---|---|---|
| Param | 〇 | Object | |||
| ToData | 〇 | Object | |||
| TalkID | 〇 | UUID | 対象トークのトークID | ||
| MentionList | Object[] | メンション指定のリスト | リストの各要素は MentionString か LoginID のどちらか一方を指定 | ||
| MentionString | String | メンション文字列 | 全トーク参加者へのメンションの場合に "all" と指定 | ||
| LoginID | UUID | ログインID | メンション対象ユーザのログインIDを指定 | ||
| ReplyMessageID | UUID | 返信元メッセージID | 対象トーク内の別メッセージに対する返信メッセージであるときに指定 | ||
| MessageData | 〇 | Object | |||
| Text | 〇 | String | メッセージ本文 | 最大500文字まで（※DiSCUS管理画面にて上限を2000文字まで拡張できます） | |
| OgpLinkList | String[] | OGPリンクのリスト | メッセージ本文に含まれるURLの内、 OGP リンクとして扱う物のリスト | ||
| RecordReadFlag | Boolean | 既読確認フラグ | true の場合、トークの最新メッセージまでを既読とみなす（省略時 false 扱い） | ||
◆メンションについての補足事項
MentionList に "all" やメンション対象ログインIDを指定することで、作成するメッセージはメンション付きメッセージとなり通知の制御などが変わってきますが、DiSCUS のチャット画面上におけるメッセージの見た目は通常の（メンションのつかない）メッセージと変わりません。
画面上 "@all"、"@ユーザ名" のようなメンション表示を行うためには、メッセージ本文（MessageData.Text）にメンション対象者に対応する形で下記形式の文字列を含めてください。
| 全体メンションの場合 | @all | |
|---|---|---|
| ユーザ指定メンションの場合 | @表示名(ログインID)# | |
上記のメンション文字列は行頭・改行・半角スペースのいずれかで他の分と区切られている必要があります。また、表示名、ログインID ともに正確な値でないとメンション表示になりません。
レスポンス JSON
| 必須 | 形式 | 内容 | 補足 | ||
|---|---|---|---|---|---|
| AppStatus | 〇 | Object | API の実行情報 | ||
| Code | 〇 | String | 終了コード | ||
| Message | String | メッセージ | |||
| PostMessageResult | Object | メッセージ作成結果情報 | API が正常終了した場合のみ値を格納 | ||
| MessageID | UUID | 作成されたメッセージのID | |||
API 固有の終了コード
| Code | Message | 概要 | 補足（主な原因など） | ||
|---|---|---|---|---|---|
| E041 | INVALID_PARAMETER | パラメータ異常 | トークIDなどの必須項目が指定されていない | ||
| メッセージ本文の最大文字数超過 | |||||
| 指定されている返信元メッセージIDが不適当（存在しない、削除済み、など） | |||||
| E051 | NOT_EXIST_DATA | 存在しないデータ | 対象のトークが存在しない（対象トークに参加していない場合含む） | ||
| E199 | REQUEST_FAILURE | その他のエラー | |||
画像メッセージの作成
| URL(パス) | /api/chat/post-message-image |
|---|---|
| Content-Type | multipart/form-data |
リクエストボディ（multipart/form-data）
| 必須 | name | 形式 | 内容・補足 | |
|---|---|---|---|---|
| 第１パート | 〇 | "Control" | JSONデータ | メッセージ作成パラメータ（後述） |
| 第２パート | 〇 | "Original" | 添付ファイルデータ | メッセージ添付ファイル |
| 第３パート | "Thumbnail" | サムネイルファイルデータ | サムネイル画像ファイル。有効な形式は jpg / jpeg / gif / png |
第１パート（Control）のJSON指定内容
| 必須 | 形式 | 内容 | 補足 | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| TalkID | 〇 | UUID | 対象トークのトークID | ||||||||
| ReplyMessageID | UUID | 返信元メッセージID | 対象トーク内の別メッセージに対する返信メッセージであるときに指定 | ||||||||
| FileName | 〇 | String | メッセージ画像のファイル名 | ||||||||
| HasThumbnail | Boolean | サムネイル画像有無フラグ | multipart の第３パートが存在する場合、true を指定する | ||||||||
| RecordReadFlag | Boolean | 既読確認フラグ | true の場合、トークの最新メッセージまでを既読とみなす（省略時 false 扱い） | ||||||||
レスポンス JSON
| 必須 | 形式 | 内容 | 補足 | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| AppStatus | 〇 | Object | API の実行情報 | ||||||||
| Code | 〇 | String | 終了コード | ||||||||
| Message | String | メッセージ | |||||||||
| PostMessageResult | Object | メッセージ作成結果情報 | API が正常終了した場合のみ値を格納 | ||||||||
| MessageID | UUID | 作成されたメッセージのID | |||||||||
API 固有の終了コード
| Code | Message | 概要 | 補足（主な原因など） | ||
|---|---|---|---|---|---|
| E041 | INVALID_PARAMETER | パラメータ異常 | multipart/form-data 形式でのアクセスになっていない | ||
| Control パートが存在しない | |||||
| Original パートが存在しない | |||||
| トークIDなどの必須項目が指定されていない | |||||
| 指定されている返信元メッセージIDが不適当（存在しない、削除済み、など） | |||||
| 画像ファイルが正しく送信されていない | |||||
| E021 | NO_PERMISSION | 権限エラー | テナントの設定で画像メッセージの作成が認められていない | ||
| E051 | NOT_EXIST_DATA | 存在しないデータ | 対象のトークが存在しない（対象トークに参加していない場合含む） | ||
| E199 | REQUEST_FAILURE |
その他のエラー |
|||
ファイルメッセージの作成
| URL(パス) | /api/chat/post-message-attached |
|---|---|
| Content-Type | multipart/form-data |
リクエストボディ（multipart/form-data）
| 必須 | name | 形式 | 内容・補足 | |||
|---|---|---|---|---|---|---|
| 第１パート | 〇 | "Control" | JSONデータ | メッセージ作成パラメータ（後述） | ||
| 第２パート | 〇 | "Original" | 添付ファイルデータ | メッセージ添付ファイル | ||
| 第３パート | "Thumbnail" | サムネイルファイルデータ | サムネイル画像ファイル。有効な形式は jpg / jpeg / gif / png | |||
第１パート（Control）のJSON指定内容
| 必須 | 形式 | 内容 | 補足 | |
|---|---|---|---|---|
| TalkID | 〇 | UUID | 対象トークのトークID | |
| ReplyMessageID | UUID | 返信元メッセージID | 対象トーク内の別メッセージに対する返信メッセージであるときに指定 | |
| FileName | 〇 | String | 添付ファイル名 | |
| HasThumbnail | Boolean | サムネイル画像有無フラグ | multipart の第３パートが存在する場合、true を指定する | |
| RecordReadFlag | Boolean | 既読確認フラグ | true の場合、トークの最新メッセージまでを既読とみなす（省略時 false 扱い） |
レスポンス JSON
| 必須 | 形式 | 内容 | 補足 | ||||
|---|---|---|---|---|---|---|---|
| AppStatus | 〇 | Object | API の実行情報 | ||||
| Code | 〇 | String | 終了コード | ||||
| Message | String | メッセージ | |||||
| PostMessageResult | Object | メッセージ作成結果情報 | API が正常終了した場合のみ値を格納 | ||||
| MessageID | UUID | 作成されたメッセージのID | |||||
API 固有の終了コード
| Code | Message | 概要 | 補足（主な原因など） | ||
|---|---|---|---|---|---|
| E041 | INVALID_PARAMETER | パラメータ異常 | multipart/form-data 形式でのアクセスになっていない | ||
| Control パートが存在しない | |||||
| Original パートが存在しない | |||||
| トークIDなどの必須項目が指定されていない | |||||
| 指定されている返信元メッセージIDが不適当（存在しない、削除済み、など） | |||||
| 添付ファイルが正しく送信されていない | |||||
| テナントの設定で許可されていないファイル形式 | |||||
| E021 | NO_PERMISSION | 権限エラー | テナントの設定で添付メッセージの作成が認められていない | ||
| E051 | NOT_EXIST_DATA | 存在しないデータ | 対象のトークが存在しない（対象トークに参加していない場合含む） | ||
| E199 | REQUEST_FAILURE | その他のエラー | |||
動画メッセージの作成
| URL(パス) | /api/chat/post-message-movie |
|---|---|
| Content-Type | multipart/form-data |
リクエストボディ（multipart/form-data）
| 必須 | name | 形式 | 内容・補足 | |||
|---|---|---|---|---|---|---|
| 第１パート | 〇 | "Control" | JSONデータ | メッセージ作成パラメータ（後述） | ||
| 第２パート | 〇 | "Original" | 動画ファイルデータ | メッセージ動画ファイル。有効な形式は mp4 | ||
| 第３パート | "Thumbnail" | サムネイルファイルデータ | サムネイル画像ファイル。有効な形式は jpg / jpeg / gif / png | |||
第１パート（Control）のJSON指定内容
| 必須 | 形式 | 内容 | 補足 | ||||
|---|---|---|---|---|---|---|---|
| TalkID | 〇 | UUID | 対象トークのトークID | ||||
| ReplyMessageID | UUID | 返信元メッセージID | 対象トーク内の別メッセージに対する返信メッセージであるときに指定 | ||||
| FileName | 〇 | String | 動画ファイル名 | ||||
| HasThumbnail | Boolean | サムネイル画像有無フラグ | multipart の第３パートが存在する場合、true を指定する | ||||
| RecordReadFlag | Boolean | 既読確認フラグ | true の場合、トークの最新メッセージまでを既読とみなす（省略時 false 扱い） | ||||
レスポンス JSON
| 必須 | 形式 | 内容 | 補足 | ||
|---|---|---|---|---|---|
| AppStatus | 〇 | Object | API の実行情報 | ||
| Code | 〇 | String | 終了コード | ||
| Message | String | メッセージ | |||
| PostMessageResult | Object | メッセージ作成結果情報 | API が正常終了した場合のみ値を格納 | ||
| MessageID | UUID | 作成されたメッセージのID | |||
API 固有の終了コード
| Code | Message | 概要 | 補足（主な原因など） | ||
|---|---|---|---|---|---|
| E041 | INVALID_PARAMETER | パラメータ異常 | multipart/form-data 形式でのアクセスになっていない | ||
| Control パートが存在しない | |||||
| Original パートが存在しない | |||||
| トークIDなどの必須項目が指定されていない | |||||
| 指定されている返信元メッセージIDが不適当（存在しない、削除済み、など） | |||||
| 動画ファイルが正しく送信されていない | |||||
| E021 | NO_PERMISSION | 権限エラー | テナントの設定で動画メッセージの作成が認められていない | ||
| E051 | NOT_EXIST_DATA | 存在しないデータ | 対象のトークが存在しない（対象トークに参加していない場合含む） | ||
| E199 | REQUEST_FAILURE | その他のエラー | |||
位置情報メッセージの作成
| URL(パス) | /api/chat/post-message-movie |
|---|---|
| Content-Type | multipart/form-data |
リクエストボディ（multipart/form-data）
| 必須 | name | 形式 | 内容・補足 | |||
|---|---|---|---|---|---|---|
| 第１パート | 〇 | "Control" | JSONデータ | メッセージ作成パラメータ（後述） | ||
| 第２パート | 〇 | "Original" | 地図画像ファイルデータ | 地図画像ファイル。有効な形式は jpg / jpeg / gif / png | ||
| 第３パート | "Thumbnail" | サムネイルファイルデータ | サムネイル画像ファイル。有効な形式は jpg / jpeg / gif / png | |||
第１パート（Control）のJSON指定内容
| 必須 | 形式 | 内容 | 補足 | ||||
|---|---|---|---|---|---|---|---|
| TalkID | 〇 | UUID | 対象トークのトークID | ||||
| ReplyMessageID | UUID | 返信元メッセージID | 対象トーク内の別メッセージに対する返信メッセージであるときに指定 | ||||
| MessageData | Object | ||||||
| Coordinates | Object | 座標情報 | |||||
| Latitude | float | 緯度 | |||||
| Longitude | float | 経度 | |||||
| Altitude | float | 高度 | データがない場合は 0.0 を指定 | ||||
| Accuracy | float | 精度 | データがない場合は 0.0 を指定 | ||||
| AddressText | 〇 | String | 住所テキスト | ||||
| FileName | 〇 | String | 地図画像ファイル名 | ||||
| HasThumbnail | Boolean | サムネイル画像有無フラグ | multipart の第３パートが存在する場合、true を指定する | ||||
| RecordReadFlag | Boolean | 既読確認フラグ | true の場合、トークの最新メッセージまでを既読とみなす（省略時 false 扱い） | ||||
レスポンス JSON
| 必須 | 形式 | 内容 | 補足 | ||
|---|---|---|---|---|---|
| AppStatus | 〇 | Object | API の実行情報 | ||
| Code | 〇 | String | 終了コード | ||
| Message | String | メッセージ | |||
| PostMessageResult | Object | メッセージ作成結果情報 | API が正常終了した場合のみ値を格納 | ||
| MessageID | UUID | 作成されたメッセージのID | |||
API 固有の終了コード
| Code | Message | 概要 | 補足（主な原因など） | ||
|---|---|---|---|---|---|
| E041 | INVALID_PARAMETER | パラメータ異常 | multipart/form-data 形式でのアクセスになっていない | ||
| Control パートが存在しない | |||||
| Original パートが存在しない | |||||
| トークIDなどの必須項目が指定されていない | |||||
| 指定されている返信元メッセージIDが不適当（存在しない、削除済み、など） | |||||
| 地図画像ファイルが正しく送信されていない | |||||
| E021 | NO_PERMISSION | 権限エラー | テナントの設定で動画メッセージの作成が認められていない | ||
| E051 | NOT_EXIST_DATA | 存在しないデータ | 対象のトークが存在しない（対象トークに参加していない場合含む） | ||
| E199 | REQUEST_FAILURE | その他のエラー | |||
参照系API
トークの取得
| URL(パス) | /api/chat/get-talk-info |
|---|---|
| Content-Type | application/json |
リクエストボディ（JSON）
| 必須 | 形式 | 内容 | 補足 | |||
|---|---|---|---|---|---|---|
| Param | 〇 | Object | ||||
| Conditions | 〇 | Object | ||||
| TalkID | 〇 | UUID | 取得対象トークのトークID | |||
レスポンス JSON
| 必須 | 形式 | 内容 | 補足 | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| AppStatus | 〇 | Object | API の実行情報 | ||||||||
| Code | 〇 | String | 終了コード | ||||||||
| Message | String | メッセージ | |||||||||
| TalkResponse | Object | トーク取得結果情報 | API が正常終了した場合のみ値を格納 | ||||||||
| Contents | 〇 | Object | |||||||||
| Talk | 〇 | Object | |||||||||
| TalkID | 〇 | UUID | トークID | ||||||||
| CategoryCode | 〇 | String | トーク種別 | "TALK"（通常トーク）もしくは "ANNOUNCE"（一斉同報） | |||||||
| AuthorID | 〇 | UUID | トーク作成ユーザのユーザID | ||||||||
| CreateDateTime | 〇 | DateTime | トーク作成日時 | ||||||||
| UpdateDateTime | 〇 | DateTime | トーク更新日時 | ||||||||
| Properties | 〇 | Object | トークプロパティ | ||||||||
| TalkName | 〇 | String | |||||||||
| TalkDescription | String | ||||||||||
| TalkLabel | String | 16進数のカラーコード形式で指定 | |||||||||
| TalkIconPath | String | トークアイコン画像アクセスのためのURL（パス部） | |||||||||
| Permission | 〇 | Object | トークに対するユーザの権限情報 | ||||||||
| TalkMetaPermissionFlag | 〇 | Boolean | ※現在の API では true 固定 | ||||||||
| TalkMemberPermissionFlag | 〇 | Boolean | ※現在の API では true 固定 | ||||||||
| TalkFreePostingFlag | 〇 | Boolean | ※現在の API では true 固定 | ||||||||
| TalkTagList | 〇 | String[] | トークタグのリスト | タグが設定されていない場合空リスト | |||||||
| AccessMemberList | 〇 | Object[] | トークアクセス者情報 | 自分以外のトーク参加者のアクセス情報（直近の最大１０件） | |||||||
| UserID | UUID | ユーザID | |||||||||
| LoginID | String | ログインID | |||||||||
| UserViewName | String | ユーザ表示名 | |||||||||
| UserIconFileURLPath | String | ユーザのアイコン画像アクセスのためのURL（パス部） | |||||||||
| LastReadDateTime | DateTime | トークへの最終アクセス時刻 | |||||||||
| TalkFavoriteFlag | 〇 | Boolean | お気に入りフラグ | 個人設定。 | |||||||
| TalkNotificationSetting | 〇 | String | トークの通知設定 | 個人設定。”ALL"（通知ON）、"OFF"（通知OFF）、"MENTION"（メンションのみ通知）のいずれか | |||||||
| TalkLastAccess | 〇 | Object | トーク最終アクセス状態 | 自分自身の、このトークに対する最終アクセス情報 | |||||||
| TalkLastAccessMessageCount | 〇 | Integer | 最終アクセス時のトーク内投稿メッセージ数 | ||||||||
| TalkLastAccessDateTime | 〇 | DateTime | 未アクセスの場合、EPOC 0 の日時 | ||||||||
| IsMemberFlag | 〇 | Boolean | トーク参加者フラグ | 自分がトークの参加者であるかどうかのフラグ※現在のAPIでは true 固定 | |||||||
| CanExitTalkFlag | 〇 | Boolean | 退室可能フラグ | 自分が退室操作可能であるかどうかのフラグ | |||||||
| Link | Object | 連携コンテンツ情報 | ※現在のAPIでは null 固定 | ||||||||
| UtilizationControl | 〇 | Object | トークの参加者情報 | ||||||||
| Disclosing | 〇 | Object | トークの全体公開情報 | ||||||||
| ContentsDisclosingID | 〇 | UUID | |||||||||
| ContentsDisclosingFlag | 〇 | Boolean | ※このAPIでは false 固定 | ||||||||
| Member | 〇 | Object | トークのメンバー情報 | ||||||||
| MemberDefinitionID | 〇 | UUID | |||||||||
| UserList | 〇 | Object[] | ユーザ単位でのメンバー設定リスト | ||||||||
| UserID | 〇 | UUID | |||||||||
| LoginID | 〇 | String | |||||||||
| UserViewName | 〇 | String | |||||||||
| UserIconFileURLPath | String | アイコン画像へのアクセスURL（パス部） | |||||||||
| OrganizationList | 〇 | Object[] | 組織単位でのメンバー設定リスト | ||||||||
| OrganizationID | 〇 | UUID | |||||||||
| OrganizationName | 〇 | String | |||||||||
| OrganizationIconFileURLPath | String | 組織アイコン画像へのアクセスURL（パス部） | |||||||||
API 固有の終了コード
| Code | Message | 概要 | 補足（主な原因など） | ||
|---|---|---|---|---|---|
| E041 | INVALID_PARAMETER | パラメータ異常 | トークIDなどの必須項目が指定されていない | ||
| E051 | NOT_EXIST_DATA | 存在しないデータ | 対象のトークが存在しない（対象トークに参加していない場合含む） | ||
| E199 | REQUEST_FAILURE | その他のエラー | |||
トーク一覧の取得
| URL(パス) | /api/chat/get-talk-list |
|---|---|
| Content-Type | application/json |
リクエストボディ（JSON）
| 必須 | 形式 | 内容 | 補足 | |||||
|---|---|---|---|---|---|---|---|---|
| Param | 〇 | Object | ||||||
| Options | 〇 | Object | ||||||
| TalkFilteringOption | Object | トーク絞り込み条件 | ||||||
| IsArchived | Boolean | アーカイブされたトークのみを取得対象とするフラグ | ||||||
| IsFavorite | Boolean | お気に入りトークのみを取得するフラグ | ||||||
| TalkTagList | String[] | タグによる絞り込み条件（複数タグを指定する場合、OR 結合） | ||||||
| TalkLabelColorList | String[] | トークラベル色による絞り込み条件（複数ラベル色を指定する場合、OR結合） | ||||||
| PeriodOption | Object | 取得期間条件 | 取得期間条件 | |||||
| StartingTime | DateTime | トーク取得の起点となる時刻。この時刻ちょうどのトークは取得対象に含まない。 | ||||||
| Direction | String | "BACKWARD"（過去方向に順次取得）、または "FORWARD"（未来方向に順次取得）。省略時は BACKWORD となる | ||||||
| MaxCount | Integer | 未指定の場合は 20 とみなします | ||||||
| SearchKeyword | String | 検索キーワード | 検索対象はトーク名、トーク説明 | |||||
◆取得期間条件について
本APIは、API実行者が参照可能なトークの一覧をトーク更新日時の新しい順もしくは古い順に指定数だけ取得するAPIです。実行にあたっては、取得の起点となる時刻および、そこから過去方向にトークを検索していくか、未来方向にトークを検索していくかを指定することができます。
※未指定の場合、現在時刻を基準に過去方向にトークを検索（＝更新の新しい順に一定数のトークを検索）します。
◆アーカイブ取得フラグについて
一定期間メッセージ投稿の無いトークは自動的に "アーカイブ" に移され、基本的には本APIの取得対象外となります。アーカイブされたトークを取得したい場合には TalkFilteringOption.IsArchived パラメータに true を指定して本API を実行してください。その場合アーカイブされたトークのみが取得対象となります。
※アーカイブされているトークに新たにメッセージが投稿されると、そのトークは非アーカイブ状態に復帰します。
◆お気に入りトーク取得フラグについて
TalkFilteringOption.IsFavorite パラメータを指定しないか、false を指定した状態で本APIを実行した場合、お気に入り設定されていないトークのみが取得対象となります。TalkFilteringOption.IsFavorite パラメータに true を指定した状態で本APIを実行した場合、お気に入り設定されたトークのみが取得対象となります。
※一度の API 実行でお気に入りトークとそうでないトークを両方取得することは出来ません。
| IsFavorite パラメータ | 取得対象 | 補足 | |||
|---|---|---|---|---|---|
| 未指定 / "false" | お気に入り設定されていないトークのみ取得 | ||||
| "true" | お気に入り設定されているトークのみ取得 | ※アーカイブ状態のトークでも、お気に入り設定されていれば取得対象 | |||
レスポンス JSON
| 必須 | 形式 | 内容 | 補足 | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| AppStatus | 〇 | Object | API の実行情報 | ||||||||
| Code | 〇 | String | 終了コード | ||||||||
| Message | String | メッセージ | |||||||||
| TalkListResponse | 〇 | Object | トーク一覧取得結果情報 | API が正常終了した場合のみ値を格納 | |||||||
| Contents | 〇 | Object | |||||||||
| TalkList | 〇 | Object[] | トークリスト | 取得トークの一覧 | |||||||
| TalkID | 〇 | UUID | トークID | トークID | |||||||
| CategoryCode | 〇 | String | トーク種別 | "TALK"（通常トーク）もしくは "ANNOUNCE"（一斉同報） | |||||||
| AuthorID | 〇 | UUID | トーク作成ユーザのユーザID | ||||||||
| CreateDateTime | 〇 | DateTime | トーク作成日時 | ||||||||
| UpdateDateTime | 〇 | DateTime | トーク更新日時 | ||||||||
| Properties | 〇 | Object | トークプロパティ | ||||||||
| TalkName | 〇 | String | トーク名 | ||||||||
| TalkDescription | String | ||||||||||
| TalkLabel | String | 16進数のカラーコード形式で指定 | |||||||||
| TalkIconPath | String | トークアイコン画像アクセスのためのURL（パス部） | |||||||||
| LastStatus | 〇 | Object | トーク最終状態 | トークに最後に投稿されたメッセージの情報 | |||||||
| LastMessageCount | 〇 | Integer | 現時点でトークに投稿されているメッセージ数 | ||||||||
| LastMessageDateTime | 〇 | DateTime | トークに最後にメッセージ投稿された日時 | ||||||||
| LastMessageUserID | UUID | トークに最後にメッセージを投稿したユーザのユーザID | |||||||||
| LastMessageUserViewName | String | トークに最後にメッセージを投稿したユーザの表示名 | |||||||||
| LastMessageType | String | トークに最後に投稿されたメッセージの種別 | |||||||||
| LastMessage | String | トークに最後に投稿されたメッセージのJSONデータ | |||||||||
| LastMessageDeletedFlag | 〇 | Boolean | 最終メッセージが削除されているかどうか | ||||||||
| TalkFavoriteFlag | 〇 | Boolean | お気に入りフラグ | 個人設定。 | |||||||
| TalkNotificationSetting | 〇 | String | トーク通知設定 | 個人設定。”ALL"（通知ON）、"OFF"（通知OFF）、"MENTION"（メンションのみ通知）のいずれか | |||||||
| TalkLastAccess | 〇 | Object | トーク最終アクセス状態 | 自分自身の、このトークに対する最終アクセス情報 | |||||||
| TalkLastAccessMessageCount | 〇 | Integer | 最終アクセス時のトーク内投稿メッセージ数 | ||||||||
| TalkLastAccessDateTime | 〇 | DateTime | 未アクセスの場合、EPOC 0 の日時 | ||||||||
| GetMoreFlag | 〇 | Boolean | 追加取得フラグ | 追加で取得できるトークが存在しているかどうかのフラグ | |||||||
API 固有の終了コード
| Code | Message | 概要 | 補足（主な原因など） | ||
|---|---|---|---|---|---|
| E041 | INVALID_PARAMETER | パラメータ異常 | 必須項目が指定されていない | ||
| E199 | REQUEST_FAILURE | その他のエラー | |||
◆追加取得フラグについて
レスポンスJSON の GetMoreFlag が true である場合、取得最大件数を超えたため返却しきれなかったトークが残っている事を示します。本APIを下記のパラメータで実行することで、未取得となっているトークリストの続きを取得することができます
| パラメータ | 設定内容 | ||
|---|---|---|---|
| PeriodOption | |||
| StartingTime | 今回の API 実行で取得したトークリストの末尾のトークの UpdateDateTime を指定 | ||
| Direction | 今回の API 実行と同じ値を指定 | ||
| MaxCount | 任意値（未指定の場合 20 となる） | ||
メッセージ一覧の取得
| URL(パス) | /api/chat/get-message-list |
| Content-Type | application/json |
リクエストボディ（JSON）
| 必須 | 形式 | 内容 | 補足 | |||||
|---|---|---|---|---|---|---|---|---|
| Param | 〇 | Object | ||||||
| Conditions | 〇 | Object | ||||||
| TalkID | 〇 | UUID | トークID | 取得対象トークのトークID | ||||
| Options | 〇 | Object | ||||||
| PeriodOption | Object | 取得期間条件 | 取得期間条件 | |||||
| StartingTime | DateTime | 取得の起点となる時刻。この時刻ちょうどに投稿されたメッセージは取得対象に含まない。 | ||||||
| Direction | String | "BACKWARD"（過去方向に順次取得）、または "FORWARD"（未来方向に順次取得）。省略時は BACKWORD となる | ||||||
| MaxCount | Integer | 未指定の場合は 20 とみなします | ||||||
| SearchKeyword | String | 検索キーワード | 検索キーワード | |||||
| MessageID | UUID | 取得起点メッセージ | メッセージ取得の起点とするメッセージ。このメッセージを取得対象に含む。PeriodOption.StartingTime とは排他。 | |||||
| RecordReadFlag | Boolean | 既読確認フラグ | true の場合、トークの最新メッセージまでを既読とみなす（省略時 false 扱い） | |||||
◆取得期間条件について
本ＡＰＩは、指定のトーク上のメッセージ一覧をメッセージ投稿日時の新しい順もしくは古い順に指定数だけ取得するＡＰＩです。実行にあたっては、取得の起点となる時刻および、そこから過去方向にメッセージを検索していくか、未来方向にメッセージを検索していくかを指定することができます。
※未指定の場合、現在時刻を基準に過去方向にメッセージを検索（＝更新の新しい順に一定数のメッセージを検索）します。
◆取得起点メッセージIDについて
前述通り、基本的に本API ではメッセージ取得の起点となる日時を PeriodOption.StartingTime パラメータで指定する仕様となっていますが、既知のメッセージを起点としてメッセージ一覧を取得する事も出来ます。そのように取得したい場合には PeriodOption.StartingTime パラメータは指定せず、MessageID パラメータに起点となるメッセージのメッセージIDを指定してください。
注意点として、PeriodOption.StartingTime を用いた通常の API 実行では StartingTime 丁度の時刻のメッセージを取得結果に含みませんが、MessageID を用いた既知メッセージ起点での API 実行では MessageID が示すメッセージそれ自体を取得対象に含みます。
レスポンス JSON
| 必須 | 形式 | 内容 | 補足 | ||||||
|---|---|---|---|---|---|---|---|---|---|
| AppStatus | 〇 | Object | API の実行情報 | ||||||
| Code | 〇 | String | 終了コード | ||||||
| Message | String | メッセージ | |||||||
| MessageListResponse | 〇 | Object | |||||||
| MessageList | 〇 | Object[] | 取得メッセージのリスト | 取得メッセージのリスト | |||||
| Message | 〇 | Object | 取得メッセージ | ||||||
| MessageID | 〇 | UUID | メッセージID | ||||||
| User | 〇 | Object | 送信ユーザ情報 | ||||||
| UserID | 〇 | UUID | |||||||
| LoginID | 〇 | String | |||||||
| UserViewName | 〇 | String | |||||||
| UserIconFileURLPath | 〇 | String | メッセージ送信ユーザのアイコン画像アクセス用URL（パス部） | ||||||
| MentionList | Object[] | メンションリスト | |||||||
| UserID | UUID | ||||||||
| LoginID | String | ||||||||
| UserViewName | String | ||||||||
| UserIconFileURLPath | String | ||||||||
| MessageType | 〇 | String | メッセージ種別 | "PLAIN"（テキストメッセージ）、"IMAGE"（画像メッセージ）、"MOVIE"（動画メッセージ）、"ATTACHED"（添付ファイルメッセージ）、"STAMP"（スタンプメッセージ）、"LOCATION"（位置情報メッセージ）、"SYSPLAIN"（システムメッセージ）のいずれかの値 | |||||
| CreateDateTime | 〇 | DateTime | メッセージ投稿日時 | ||||||
| Reply | UUID | 返信元メッセージID | このメッセージがトーク内の別メッセージへの返信である場合のみ値が存在する | ||||||
| IsDeleted | 〇 | Boolean | 削除済みフラグ | 削除されている場合、メッセージ種別およびメッセージの具体的なデータは null となる | |||||
| ReactionSummaryList | Object[] | リアクションリスト | このメッセージに対するリアクションのリスト | ||||||
| Emoji | String | 絵文字を表すコードポイント文字列 | |||||||
| Count | Integer | ||||||||
| UserList | Object[] | ||||||||
| UserID | UUID | ||||||||
| LoginID | String | ||||||||
| UserViewName | String | ||||||||
| UserIconFileURLPath | String | ||||||||
| MyReactionFlag | Boolean | 自分（API実行者）がこのリアクションを取ったかどうかのフラグ | |||||||
| Plain | Object | テキストメッセージデータ | MessageType が PLAIN の場合のみ値が設定され、それ以外の場合は null | ||||||
| Text | String | メッセージ本文 | |||||||
| OgpLinkList | String[] | メッセージ本文に含まれる Ogp リンクのリスト | |||||||
| Image | Object | 画像メッセージデータ | MessageType が IMAGE の場合のみ値が設定され、それ以外の場合は null | ||||||
| MessageFileAttribute | Object | ||||||||
| FileName | String | ||||||||
| FileSize | Integer | ||||||||
| MimeType | String | ||||||||
| MessageFileInfo | Object | ||||||||
| VirtualFileID | UUID | ||||||||
| ThumbnailVirtualFileID | UUID | ||||||||
| FileUriPath | String | 画像ファイルへのアクセスURL（パス部） | |||||||
| ThumbnailFileUriPath | String | サムネイルファイルへのアクセスURL（パス部） | |||||||
| Attached | Object | 添付ファイルメッセージデータ | MessageType が IMAGE の場合のみ値が設定され、それ以外の場合は null | ||||||
| MessageFileAttribute | Object | ||||||||
| FileName | String | ||||||||
| FileSize | Integer | ||||||||
| MimeType | String | ||||||||
| MessageFileInfo | Object | ||||||||
| VirtualFileID | UUID | ||||||||
| ThumbnailVirtualFileID | UUID | ||||||||
| FileUriPath | String | 添付ファイルへのアクセスURL（パス部） | |||||||
| ThumbnailFileUriPath | String | サムネイルファイルへのアクセスURL（パス部） | |||||||
| Movie | Object | 動画メッセージデータ | MessageType が MOVIE の場合のみ値が設定され、それ以外の場合は null | ||||||
| MessageFileAttribute | Object | ||||||||
| FileName | String | ||||||||
| FileSize | Integer | ||||||||
| MimeType | String | ||||||||
| MessageFileInfo | Object | ||||||||
| VirtualFileID | UUID | ||||||||
| ThumbnailVirtualFileID | UUID | ||||||||
| FileUriPath | String | 動画ファイルへのアクセスURL（パス部） | |||||||
| ThumbnailFileUriPath | String | サムネイルファイルへのアクセスURL（パス部） | |||||||
| Location | Object | 位置情報メッセージデータ | MessageType が LOCATION の場合のみ値が設定され、それ以外の場合は null | ||||||
| Coordinates | Float[] | 座標情報の配列。要素数は２または３で、経度、緯度、高度（省略の場合あり）の順に格納。 | |||||||
| MessageFileInfo | Object | 地図画像ファイルの情報 | |||||||
| VirtualFileID | UUID | ||||||||
| ThumbnailVirtualFileID | UUID | ||||||||
| FileUriPath | String | 地図画像ファイルへのアクセスURL（パス部） | |||||||
| ThumbnailFileUriPath | String | サムネイルファイルへのアクセスURL（パス部） | |||||||
| Address | String | 住所テキスト | 住所テキスト | ||||||
| Stamp | Object | スタンプメッセージデータ | MessageType が STAMP の場合のみ値が設定され、それ以外の場合は null | ||||||
| StampInfo | Object | ||||||||
| PackageID | UUID | ||||||||
| StampID | UUID | ||||||||
| MessageFileInfo | Object | ||||||||
| VirtualFileID | UUID | ||||||||
| ThumbnailVirtualFileID | UUID | ||||||||
| FileUriPath | String | スタンプ画像ファイルへのアクセスURL（パス部） | |||||||
| ThumbnailFileUriPath | String | サムネイルファイルへのアクセスURL（パス部） | |||||||
| SysPlain | Object | システムメッセージデータ | MessageType が SYSPLAIN の場合のみ値が設定され、それ以外の場合は null | ||||||
| Text | String | ||||||||
| ReplyMessage | Object | 返信元メッセージ | 返信元メッセージがある場合のみ値が設定される（※構造は Message と同一） | ||||||
| GetMoreFlag | 〇 | Boolean | 追加取得フラグ | 追加で取得できるメッセージが残っているかどうかのフラグ | |||||
API 固有の終了コード
| Code | Message | 概要 | 補足（主な原因など） | ||
|---|---|---|---|---|---|
| E041 | INVALID_PARAMETER | パラメータ異常 | トークIDなどの必須項目が指定されていない | ||
| E051 | NOT_EXIST_DATA | 存在しないデータ | 対象のトークが存在しない（対象トークに参加していない場合含む） | ||
| E199 | REQUEST_FAILURE | その他のエラー | |||
追加取得フラグについて
レスポンスJSON の GetMoreFlag が true である場合、取得最大件数を超えたため返却しきれなかったメッセージが残っている事を示します。本APIを下記のパラメータで実行することで、未取得となっているメッセージリストの続きを取得することができます
| パラメータ | 設定内容 | ||
|---|---|---|---|
| PeriodOption | |||
| StartingTime | 今回の API 実行で取得したメッセージリストの末尾のメッセージの CreateDateTime を指定 | ||
| Direction | 今回の API 実行と同じ値を指定 | ||
| MaxCount | 任意値（未指定の場合 20 となる） | ||
外部連携APIで利用可能なチャット機能
実行系API
| トークの作成 | multipart※1 | トーク名などのプロパティ、メンバー設定、アイコンファイルなどを指定してトークを１件作成する |
|---|---|---|
| トークの削除 | ― | トークIDを指定して、指定トーク一件を削除する |
| トーク参加メンバーの更新 | ― | トークIDと参加者情報（増減ではなく、変更後の全体情報）を指定して、指定トークの参加メンバー構成を変更する |
| テキストメッセージの作成※2 | multipart | |
| ファイルメッセージの作成 | multipart | |
| 動画メッセージの作成 | multipart | |
| 位置情報メッセージの作成 | multipart |
参照系API
| トークの取得 | トークIDを指定して、トークを一件取得する |
|---|---|
| トーク一覧の取得 | トーク更新時刻、取得方向、最大取得数を指定して、トーク一覧を取得する |
| メッセージ一覧の取得 | トークID、メッセージ投稿時刻、取得方向、最大取得数を指定して、メッセージ一覧を取得する |
※1 multipart について
multipart とついている物は POST リクエストを multipart-formdata 形式で送信する必要があります
※2 テキストメッセージの作成について
メンション時、本文に一定の文言を入れないと画面上メンションに見える形式に表示されません。
API利用に関わる共通事項
各APIのURLに HTTPS の POST メソッドでアクセスすることで利用可能です。
リクエスト
API へのリクエストには以下の HTTP ヘッダを付与してください。
| ヘッダ項目 | 設定内容 | 補足 |
|---|---|---|
| Content-Type | application/json または multipart/form-data | ファイルの送信を伴うAPIでは multipart/form-data |
| Origin | 送信URL のホスト部まで | |
| Authorization | Bearer [アクセス用トークン] |
レスポンス
APIからのレスポンスは JSON 文字列として返却されます。レスポンス JSON の内容は基本的にAPI毎に異なりますが、AppStatus という項目はどのAPIのレスポンスにも含まれます。AppStatus の内容を参照することで API の成否についての情報を得る事が出来ます。
| 必須 | 形式 | 概要 | |
|---|---|---|---|
| AppStatus | 〇 | Object | API の実行情報 |
| Code | 〇 | String | API の終了コード |
| Message | ― | String | API 終了コードに関連するメッセージ |
AppStatus.Code について
レスポンスの AppStatus.Code にはAPIの終了コードが格納されます。
API の実行が成功している場合は "S000" という値が格納されます。
一方、API がエラー終了した場合は API・失敗原因毎にエラーの原因を表すコード※が格納されます。
※コードの詳細は各 API の個別説明を参照してください。
AP利用にかかわる共通事項
全API共通の終了コード
下記の終了コードについては、全API共通です。
| コード | メッセージ | 概要 |
|---|---|---|
| S000 | ー | 正常終了 |
| E280 | テナントが正しくありません | URL に問題がある可能性があります |
| E281 | トークンが不正です | アクセス時のヘッダ要素に Bearer トークンが存在していません |
| E282 | トークンが不正です | アクセストークンの内容が正しくありません |
| E283 | トークンの有効期限が切れています | アクセストークンの有効期限が切れています |
| E284 | トークンのスコープ外です | ご指定のアクセストークンでは利用できないAPIです |
| E380 | テナントの企業IDが一致しませんでした | ご指定のテナント企業IDが正しくない可能性があります |
AP利用にかかわる共通事項
APIについて補足情報
CategoryCode：トーク種別
関連API：トーク取得API、トーク一覧取得API
トーク種別は "TALK"（通常トーク）と "ANNOUNCE"（一斉同報）の2種類が存在します。
一斉同報はトーク作成者のみがメッセージ投稿を行う事が出来る特別なトークですが、
現時点では未対応のため、実質 "TALK" のみとなります。
※トーク作成APIで作成したトークのトーク種別は "TALK"（通常トーク）となります
TalkLabel：トークラベル色
関連API：トーク作成API、トーク取得API、トーク一覧取得API
トークラベル色は16進数のカラーコードで表されます。透明度は含みません。
例）赤の場合 "#ff0000"
MessageType：メッセージ種別
関連API：トーク一覧取得API、メッセージ一覧取得API
テキスト、画像、といったメッセージの種別を表します。
| "PLAIN" | テキストメッセージ | |
| "IMAGE" | 画像メッセージ | |
| "MOVIE" | 動画メッセージ | |
| "ATTACHED" | 添付ファイルメッセージ | |
| "STAMP" | スタンプメッセージ | |
| "LOCATION" | 位置情報メッセージ | |
| "SYSPLAIN" |
システムメッセージ |
|
Emoji：リアクション絵文字
関連API：メッセージ一覧取得API
リアクション絵文字を Unicode のコードポイント文字列で表します。
複数のコードポイントで１文字を形成する絵文字の場合、コードポイントを "-" で連結して表現します。
（例）
😀 → "1f600"
🙆♂️ → "1f646-200d-2642-fe0f"
関連API：トーク取得API、トーク一覧取得API、メッセージ一覧取得API
| TalkIconPath：トークアイコンへのアクセスURL（パス部） | ||
| UserIconFileURLPath：へのアクセスURL（パス部） | ||
| OrganizationIconFileURLPath：へのアクセスURL（パス部） | ||
| FileUriPath：へのアクセスURL（パス部） | ||
| ThumbnailFileUriPath：へのアクセスURL（パス部） |
これらのパスが示すファイルには、以下のパターンの URL でアクセスしてください。
https://（API実行時のホスト）/（アクセスURL（パス部））
この際、サーバ側ではファイルへのアクセス権限を確認するためにセッション情報を参照するため、フロントUIと同様の認証情報をHTTPヘッダに付与する必要があります。
※すでにDiSCUSログイン中のブラウザからURLへアクセスすることで、上記の条件をクリアできます
各種上限値について
テキストメッセージの最大文字数
500文字。管理画面の「チャット設定」にて最大2000文字まで拡張できる
トークの参加人数
組織の所属人数に制限が無いので、実質的には上限は設けられていない