APIについて

外部サービス連携APIについて

DiSCUS を外部システムから利用する手段として、Webhookや外部連携用APIと言った機能が用意されています。本記事では外部連携 API について説明します。

外部連携 API は、前述通り DiSCUS の機能を外部のシステムから利用するためのAPIです。
外部連携 API を利用することにより、以下のようなシステム間連携を行う事が出来ます。

・任意の外部システムからの出力を、DiSCUS のチャット上に表示する
・DiSCUS のチャットに入力された内容を、任意の外部システムへの入力に用いる

 

※API機能はサービス開始後5営業日以降に利用いただけます。

 

【この記事の内容】

 

 

認証系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		アカウントのメールアドレス アクセストークンに紐づくスコープに"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にあった場合、アカウント情報のプロフィール（姓、名、ミドルネーム、タイムゾーン）を返却
email	e-mail	・認可リクエストで同スコープが指定された場合、アクセストークンでユーザの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 の少なくとも一方は指定する必要がある
	Member			〇	Object
			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-member
Content-Type	application/json

 

リクエストボディ（JSON）

						必須	形式	内容	補足
Param						〇	Object
	ToData					〇	Object
	TalkID					〇	UUID	変更対象トークのトークID
	UtilizationControl					〇	Object	トークの参加者指定	UserList、OrganizationList の少なくとも一方は指定する必要がある
		Member				〇	Object	トークの参加メンバー
					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-location
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文字まで拡張できる

トークの参加人数
組織の所属人数に制限が無いので、実質的には上限は設けられていない