API Specifications for ULIZA Sidetalk (v1.6.0)
本書は ULIZA Sidetalk が提供する API 仕様について記述しています。ULIZA Sidetalk の機能や管理画面の操作方法については ULIZA Sidetalk ユーザーガイド を参照してください。
なお、本書に掲載しているコードサンプル（Request samples）は、具体的な実装例を示すことで開発者を支援することを目的としていますが、掲載しているコードがすべての環境において正常に動作することを保証するものではありません。また、コードサンプル内で使用している関数やライブラリの安全性に関して、弊社は何ら責任を負うものではありません。
| バージョン | 改版日 | 改版内容 |
|---|---|---|
| v1.0.0 | 2020/10/21 | 初版 |
| v1.1.0 | 2021/04/05 |
|
| v1.2.0 | 2021/08/10 |
|
| v1.3.0 | 2021/08/31 |
|
| v1.4.0 | 2022/03/22 |
|
| v1.6.0 | 2022/08/08 |
|
特に断りのない限り、本書に記載されている全ての API に対するリクエストの Authorization ヘッダに下記の形式で有効な API 認証キーを含める必要があります。API 認証キーの取得方法については ULIZA プロダクトアカウントユーザーガイド を参照してください。リクエストに有効な API 認証キーが含まれていない場合は、401 Unauthorized が返却されます。
Authorization: Bearer <api-credential>ルーム全取得 API
すべてのルームを取得します。リクエスト送信者が ルームの取得 権限を持っていない場合は、403 Forbidden が返却されます。
query Parameters
| statistics | string^\d+:\d+$ 統計情報の粒度（1, 5, 10, 30 または 60 の倍数。秒単位）および現在から起算した取得範囲（データの個数）を |
Responses
Response Schema: application/json
Array of objects (Room) ルーム情報 |
Request samples
- SHELL
- PHP
- Node.js
curl \ -H 'Authorization: Bearer <your-token>' \ 'https://sidetalk-api.p.uliza.jp/v1/rooms'
Response samples
- 200
- 401
- 403
- 500
Content type
application/json
{- "data": [
- {
- "id": "d88c41e1-eefb-4251-85d6-5bfd85c755c4",
- "name": "sample-room",
- "status": "open",
- "max_clients": 1000,
- "disable_username": false,
- "embeddable_domains": [
- "www.example.com"
], - "show_clients_count": true,
- "custom_styles": ".message.moderator { color: red; }",
- "profanities": [
- "coronavirus",
- "COVID-19"
], - "profanities_method": "reject",
- "blacklist_ipv4": [
- "192.168.11.1"
], - "cooldown_seconds": 3,
- "allow_client_deletes": true,
- "allow_repeated_posts": true,
- "allow_post_links": true,
- "signing_key": "DqtSOLRu1ZzpUeqmr6VTesspHJ0hMGxJ",
- "statistics": [
- {
- "timestamp": "2020-10-21 10:42:00",
- "clients_count": 523,
- "messages_sent": 14
}
], - "realtime_data": {
- "clients_count": 523,
- "total_messages": 187
}, - "created_at": "2020-10-21 10:41:17",
- "updated_at": "2020-10-21 10:41:17"
}
]
}ルーム登録 API
ルームを登録します。リクエスト送信者が ルームの登録 権限を持っていない場合は、403 Forbidden が返却されます。
Request Body schema: application/json
| name required | string <= 200 characters ルームの名前 |
| max_clients required | integer <= 100000 ユーザー接続可能数 |
| disable_username | boolean Default: false ユーザー名を収集および表示しない（匿名チャット） |
| embeddable_domains | Array of strings <= 10 items Default: ["*"] 埋め込み許可ドメイン（ワイルドカード |
| show_clients_count | boolean Default: false 現在のユーザー数を表示 |
| custom_styles | string <CSS> <= 5000 characters カスタム CSS 設定 |
| profanities | Array of strings <= 1000 items NG ワード |
| profanities_method | string Default: "replace" Enum: "replace" "reject" "sender_only" NG ワードや URL の処理方法
|
| blacklist_ipv4 | Array of strings <IPv4> <= 1000 items ブロックする IP アドレス |
| cooldown_seconds | integer >= 0 Default: 0 クールダウン時間（秒） |
| allow_client_deletes | boolean Default: false 送信者によるメッセージ削除を許可 |
| allow_repeated_posts | boolean Default: false 同一メッセージの連続送信を許可 |
| allow_post_links | boolean Default: false URL の送信を許可 |
Responses
Response Schema: application/json
| id | string <UUID> 登録されたルーム ID |
Request samples
- Payload
- SHELL
- PHP
- Node.js
Content type
application/json
{- "name": "sample-room",
- "max_clients": 1000,
- "disable_username": false,
- "embeddable_domains": [
- "www.example.com"
], - "show_clients_count": true,
- "custom_styles": ".message.moderator { color: red; }",
- "profanities": [
- "coronavirus",
- "COVID-19"
], - "profanities_method": "reject",
- "blacklist_ipv4": [
- "192.168.11.1"
], - "cooldown_seconds": 3,
- "allow_client_deletes": true,
- "allow_repeated_posts": true,
- "allow_post_links": true
}Response samples
- 201
- 400
- 401
- 403
- 422
- 500
Content type
application/json
{- "id": "d88c41e1-eefb-4251-85d6-5bfd85c755c4"
}ルーム取得 API
指定したルームの情報を取得します。リクエスト送信者が ルームの取得 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
| room-id required | string <UUID> ルーム ID |
query Parameters
| statistics | string^\d+:\d+$ 統計情報の粒度（1, 5, 10, 30 または 60 の倍数。秒単位）および現在から起算した取得範囲（データの個数）を |
Responses
Response Schema: application/json
| id | string <UUID> ルーム ID |
| name | string <= 200 characters ルームの名前 |
| status | string 以下のいずれかの状態
|
| max_clients | integer <= 100000 ユーザー接続可能数 |
| disable_username | boolean ユーザー名を収集および表示しない（匿名チャット） |
| embeddable_domains | Array of strings <= 10 items 埋め込み許可ドメイン（ワイルドカード |
| show_clients_count | boolean 現在のユーザー数を表示 |
| custom_styles | string <CSS> <= 5000 characters カスタム CSS 設定 |
| profanities | Array of strings <= 1000 items NG ワード |
| profanities_method | string Enum: "replace" "reject" "sender_only" NG ワードや URL の処理方法
|
| blacklist_ipv4 | Array of strings <IPv4> <= 1000 items ブロックする IP アドレス |
| cooldown_seconds | integer >= 0 クールダウン時間（秒） |
| allow_client_deletes | boolean 送信者によるメッセージ削除を許可 |
| allow_repeated_posts | boolean 同一メッセージの連続送信を許可 |
| allow_post_links | boolean URL の送信を許可 |
| signing_key | string 32 characters URL 発行用署名鍵 |
Array of objects (Statistics) Nullable 統計情報 | |
object (RealtimeData) リアルタイム統計情報 | |
| created_at | string <YYYY-MM-DD HH:MM:SS> ルーム登録日時 |
| updated_at | string <YYYY-MM-DD HH:MM:SS> ルーム最終更新日時 |
Request samples
- SHELL
- PHP
- Node.js
curl \ -H 'Authorization: Bearer <your-token>' \ 'https://sidetalk-api.p.uliza.jp/v1/rooms/d88c41e1-eefb-4251-85d6-5bfd85c755c4'
Response samples
- 200
- 401
- 403
- 404
- 500
Content type
application/json
{- "id": "d88c41e1-eefb-4251-85d6-5bfd85c755c4",
- "name": "sample-room",
- "status": "open",
- "max_clients": 1000,
- "disable_username": false,
- "embeddable_domains": [
- "www.example.com"
], - "show_clients_count": true,
- "custom_styles": ".message.moderator { color: red; }",
- "profanities": [
- "coronavirus",
- "COVID-19"
], - "profanities_method": "reject",
- "blacklist_ipv4": [
- "192.168.11.1"
], - "cooldown_seconds": 3,
- "allow_client_deletes": true,
- "allow_repeated_posts": true,
- "allow_post_links": true,
- "signing_key": "DqtSOLRu1ZzpUeqmr6VTesspHJ0hMGxJ",
- "statistics": [
- {
- "timestamp": "2020-10-21 10:42:00",
- "clients_count": 523,
- "messages_sent": 14
}
], - "realtime_data": {
- "clients_count": 523,
- "total_messages": 187
}, - "created_at": "2020-10-21 10:41:17",
- "updated_at": "2020-10-21 10:41:17"
}ルーム更新 API
指定したルームを更新します。リクエスト送信者が ルームの更新 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
| room-id required | string <UUID> ルーム ID |
Request Body schema: application/json
| name | string <= 200 characters ルームの名前 |
| max_clients | integer <= 100000 ユーザー接続可能数 |
| disable_username | boolean Default: false ユーザー名を収集および表示しない（匿名チャット） |
| embeddable_domains | Array of strings <= 10 items Default: ["*"] 埋め込み許可ドメイン（ワイルドカード |
| show_clients_count | boolean Default: false 現在のユーザー数を表示 |
| custom_styles | string <CSS> <= 5000 characters カスタム CSS 設定 |
| profanities | Array of strings <= 1000 items NG ワード |
| profanities_method | string Default: "replace" Enum: "replace" "reject" "sender_only" NG ワードや URL の処理方法
|
| blacklist_ipv4 | Array of strings <IPv4> <= 1000 items ブロックする IP アドレス |
| cooldown_seconds | integer >= 0 Default: 0 クールダウン時間（秒） |
| allow_client_deletes | boolean Default: false 送信者によるメッセージ削除を許可 |
| allow_repeated_posts | boolean Default: false 同一メッセージの連続送信を許可 |
| allow_post_links | boolean Default: false URL の送信を許可 |
Responses
Request samples
- Payload
- SHELL
- PHP
- Node.js
Content type
application/json
{- "name": "sample-room",
- "max_clients": 1000,
- "disable_username": false,
- "embeddable_domains": [
- "www.example.com"
], - "show_clients_count": true,
- "custom_styles": ".message.moderator { color: red; }",
- "profanities": [
- "coronavirus",
- "COVID-19"
], - "profanities_method": "reject",
- "blacklist_ipv4": [
- "192.168.11.1"
], - "cooldown_seconds": 3,
- "allow_client_deletes": true,
- "allow_repeated_posts": true,
- "allow_post_links": true
}Response samples
- 400
- 401
- 403
- 404
- 500
Content type
application/json
{- "code": "INVALID_REQUEST",
- "message": null
}ルーム削除 API
指定したルームを削除します。リクエスト送信者が ルームの削除 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
| room-id required | string <UUID> ルーム ID |
Responses
Request samples
- SHELL
- PHP
- Node.js
curl \ -X DELETE \ -H 'Authorization: Bearer <your-token>' \ 'https://sidetalk-api.p.uliza.jp/v1/rooms/d88c41e1-eefb-4251-85d6-5bfd85c755c4'
Response samples
- 401
- 403
- 404
- 500
Content type
application/json
{- "code": "REQUEST_UNAUTHORIZED",
- "message": "Invalid credentials."
}メッセージ履歴取得 API
指定したルームのメッセージ履歴を取得します。リクエスト送信者が ルームの取得 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
| room-id required | string <UUID> ルーム ID |
query Parameters
| page | integer >= 1 Default: 1 取得するページ番号 |
| per_page | integer <= 100 Default: 100 1 ページあたりの取得件数 |
| sort | string Default: "timestamp|desc" ソートする列名および方向（昇順
|
Responses
Response Schema: application/json
Array of objects (Message) メッセージ履歴 | |
| current_page | integer >= 1 現在のページ番号 |
| per_page | integer <= 100 1 ページあたりの取得件数 |
| total | integer >= 0 メッセージ総数 |
Request samples
- SHELL
- PHP
- Node.js
curl \ -H 'Authorization: Bearer <your-token>' \ 'https://sidetalk-api.p.uliza.jp/v1/rooms/d88c41e1-eefb-4251-85d6-5bfd85c755c4/messages?page=1&per_page=25&sort=timestamp|desc'
Response samples
- 200
- 401
- 403
- 404
- 500
Content type
application/json
{- "data": [
- {
- "timestamp": "2020-10-21 10:41:17.571",
- "type": "guest",
- "userid": "Guest0001",
- "username": "Guest0001",
- "text": "Hello, World!"
}
], - "current_page": 1,
- "per_page": 25,
- "total": 187
}メッセージ履歴消去 API
指定したルームのメッセージ履歴を消去します。リクエスト送信者が ルームの更新 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
| room-id required | string <UUID> ルーム ID |
Responses
Request samples
- SHELL
- PHP
- Node.js
curl \ -X DELETE \ -H 'Authorization: Bearer <your-token>' \ 'https://sidetalk-api.p.uliza.jp/v1/rooms/d88c41e1-eefb-4251-85d6-5bfd85c755c4/messages'
Response samples
- 401
- 403
- 404
- 500
Content type
application/json
{- "code": "REQUEST_UNAUTHORIZED",
- "message": "Invalid credentials."
}リアルタイム統計情報取得 API
指定したルームのリアルタイム統計情報情報を取得します。リクエスト送信者が ルームの取得 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
| room-id required | string <UUID> ルーム ID |
Responses
Response Schema: application/json
| clients_count | integer >= 0 ユーザー数 |
| total_messages | integer >= 0 メッセージ総数 |
Request samples
- SHELL
- PHP
- Node.js
curl \ -H 'Authorization: Bearer <your-token>' \ 'https://sidetalk-api.p.uliza.jp/v1/rooms/d88c41e1-eefb-4251-85d6-5bfd85c755c4/realtime-data'
Response samples
- 200
- 401
- 403
- 404
- 500
Content type
application/json
{- "clients_count": 523,
- "total_messages": 187
}Request samples
- SHELL
- PHP
- Node.js
curl \ -X POST \ -H 'Authorization: Bearer <your-token>' \ 'https://sidetalk-api.p.uliza.jp/v1/rooms:open/d88c41e1-eefb-4251-85d6-5bfd85c755c4'
Response samples
- 401
- 403
- 404
- 500
Content type
application/json
{- "code": "REQUEST_UNAUTHORIZED",
- "message": "Invalid credentials."
}Request samples
- SHELL
- PHP
- Node.js
curl \ -X POST \ -H 'Authorization: Bearer <your-token>' \ 'https://sidetalk-api.p.uliza.jp/v1/rooms:close/d88c41e1-eefb-4251-85d6-5bfd85c755c4'
Response samples
- 401
- 403
- 404
- 500
Content type
application/json
{- "code": "REQUEST_UNAUTHORIZED",
- "message": "Invalid credentials."
}アンケート全取得 API
指定したルームのすべてのアンケートを取得します。リクエスト送信者が ルームの取得 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
| room-id required | string <UUID> ルーム ID |
Responses
Response Schema: application/json
Array of objects (Poll) アンケート情報 |
Request samples
- SHELL
- PHP
- Node.js
curl \ -H 'Authorization: Bearer <your-token>' \ 'https://sidetalk-api.p.uliza.jp/v1/rooms/d88c41e1-eefb-4251-85d6-5bfd85c755c4/polls'
Response samples
- 200
- 401
- 403
- 404
- 500
Content type
application/json
{- "data": [
- {
- "id": "4a366ca5-37c3-4464-9cd7-fba2149a82f0",
- "room_id": "d88c41e1-eefb-4251-85d6-5bfd85c755c4",
- "query": "今日の天気は？",
- "time_to_answer": 30,
- "publish_result": true,
- "time_for_result": 15,
- "display_format": "percent",
- "show_correctness": false,
- "options": [
- {
- "id": 0,
- "text": "晴れ",
- "correct": true,
- "number_of_votes": 163
}, - {
- "id": 1,
- "text": "くもり",
- "correct": false,
- "number_of_votes": 37
}
], - "created_at": "2020-10-21 10:41:17",
- "updated_at": "2020-10-21 10:41:17",
- "opened_at": "2020-10-21 10:41:17",
- "closed_at": "2020-10-21 10:41:17"
}
]
}アンケート登録 API
指定したルームにアンケートを登録します。リクエスト送信者が ルームの更新 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
| room-id required | string <UUID> ルーム ID |
Request Body schema: application/json
| query required | string <= 200 characters 質問文 |
| time_to_answer | integer >= 5 Nullable Default: null 自動締切時間（秒） |
| publish_result | boolean Default: false 集計結果をチャット画面に表示 |
| time_for_result | integer >= 5 Default: 30 集計結果表示時間（秒） |
| display_format | string Default: "percent" Enum: "percent" "number" "number_percent" 集計結果表示形式
|
| show_correctness | boolean Default: false 集計結果画面に正解/不正解を表示 |
required | Array of objects [ 2 .. 10 ] items 選択肢 |
Responses
Response Schema: application/json
| id | string <UUID> 登録されたアンケート ID |
Request samples
- Payload
- SHELL
- PHP
- Node.js
Content type
application/json
{- "query": "今日の天気は？",
- "time_to_answer": 30,
- "publish_result": true,
- "time_for_result": 15,
- "display_format": "percent",
- "show_correctness": false,
- "options": [
- {
- "text": "晴れ",
- "correct": true
}, - {
- "text": "くもり",
- "correct": false
}
]
}Response samples
- 201
- 400
- 401
- 403
- 404
- 500
Content type
application/json
{- "id": "4a366ca5-37c3-4464-9cd7-fba2149a82f0"
}アンケート取得 API
指定したアンケートの情報を取得します。リクエスト送信者が ルームの取得 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
| room-id required | string <UUID> ルーム ID |
| poll-id required | string <UUID> アンケート ID |
Responses
Response Schema: application/json
| id | string <UUID> アンケート ID |
| room_id | string <UUID> ルーム ID |
| query | string <= 200 characters 質問文 |
| time_to_answer | integer >= 5 Nullable 自動締切時間（秒） |
| publish_result | boolean 集計結果をチャット画面に表示 |
| time_for_result | integer >= 5 集計結果表示時間（秒） |
| display_format | string Enum: "percent" "number" "number_percent" 集計結果表示形式
|
| show_correctness | boolean 集計結果画面に正解/不正解を表示 |
Array of objects [ 2 .. 10 ] items 選択肢 | |
| created_at | string <YYYY-MM-DD HH:MM:SS> アンケート登録日時 |
| updated_at | string <YYYY-MM-DD HH:MM:SS> アンケート最終更新日時 |
| opened_at | string <YYYY-MM-DD HH:MM:SS> 回答受付開始日時 |
| closed_at | string <YYYY-MM-DD HH:MM:SS> 回答締切日時 |
Request samples
- SHELL
- PHP
- Node.js
curl \ -H 'Authorization: Bearer <your-token>' \ 'https://sidetalk-api.p.uliza.jp/v1/rooms/d88c41e1-eefb-4251-85d6-5bfd85c755c4/polls/4a366ca5-37c3-4464-9cd7-fba2149a82f0'
Response samples
- 200
- 401
- 403
- 404
- 500
Content type
application/json
{- "id": "4a366ca5-37c3-4464-9cd7-fba2149a82f0",
- "room_id": "d88c41e1-eefb-4251-85d6-5bfd85c755c4",
- "query": "今日の天気は？",
- "time_to_answer": 30,
- "publish_result": true,
- "time_for_result": 15,
- "display_format": "percent",
- "show_correctness": false,
- "options": [
- {
- "id": 0,
- "text": "晴れ",
- "correct": true,
- "number_of_votes": 163
}, - {
- "id": 1,
- "text": "くもり",
- "correct": false,
- "number_of_votes": 37
}
], - "created_at": "2020-10-21 10:41:17",
- "updated_at": "2020-10-21 10:41:17",
- "opened_at": "2020-10-21 10:41:17",
- "closed_at": "2020-10-21 10:41:17"
}アンケート更新 API
指定したアンケートを更新します。リクエスト送信者が ルームの更新 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
| room-id required | string <UUID> ルーム ID |
| poll-id required | string <UUID> アンケート ID |
Request Body schema: application/json
| query | string <= 200 characters 質問文 |
| time_to_answer | integer >= 5 Nullable Default: null 自動締切時間（秒） |
| publish_result | boolean Default: false 集計結果をチャット画面に表示 |
| time_for_result | integer >= 5 Default: 30 集計結果表示時間（秒） |
| display_format | string Default: "percent" Enum: "percent" "number" "number_percent" 集計結果表示形式
|
| show_correctness | boolean Default: false 集計結果画面に正解/不正解を表示 |
Array of objects [ 2 .. 10 ] items 選択肢 |
Responses
Request samples
- Payload
- SHELL
- PHP
- Node.js
Content type
application/json
{- "query": "今日の天気は？",
- "time_to_answer": 30,
- "publish_result": true,
- "time_for_result": 15,
- "display_format": "percent",
- "show_correctness": false,
- "options": [
- {
- "text": "晴れ",
- "correct": true
}, - {
- "text": "くもり",
- "correct": false
}
]
}Response samples
- 400
- 401
- 403
- 404
- 500
Content type
application/json
{- "code": "INVALID_REQUEST",
- "message": null
}アンケート削除 API
指定したアンケートを削除します。リクエスト送信者が ルームの更新 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
| room-id required | string <UUID> ルーム ID |
| poll-id required | string <UUID> アンケート ID |
Responses
Request samples
- SHELL
- PHP
- Node.js
curl \ -X DELETE \ -H 'Authorization: Bearer <your-token>' \ 'https://sidetalk-api.p.uliza.jp/v1/rooms/d88c41e1-eefb-4251-85d6-5bfd85c755c4/polls/4a366ca5-37c3-4464-9cd7-fba2149a82f0'
Response samples
- 401
- 403
- 404
- 500
Content type
application/json
{- "code": "REQUEST_UNAUTHORIZED",
- "message": "Invalid credentials."
}アンケート回答開始 API
指定したアンケートの回答を開始しアンケートをチャット画面に表示します。リクエスト送信者が ルームの更新 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
| room-id required | string <UUID> ルーム ID |
| poll-id required | string <UUID> アンケート ID |
Responses
Request samples
- SHELL
- PHP
- Node.js
curl \ -X POST \ -H 'Authorization: Bearer <your-token>' \ 'https://sidetalk-api.p.uliza.jp/v1/rooms/d88c41e1-eefb-4251-85d6-5bfd85c755c4/polls:open/4a366ca5-37c3-4464-9cd7-fba2149a82f0'
Response samples
- 401
- 403
- 404
- 500
Content type
application/json
{- "code": "REQUEST_UNAUTHORIZED",
- "message": "Invalid credentials."
}アンケート回答締切 API
指定したアンケートの回答を締め切り集計結果をチャット画面に表示します。リクエスト送信者が ルームの更新 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
| room-id required | string <UUID> ルーム ID |
| poll-id required | string <UUID> アンケート ID |
Responses
Request samples
- SHELL
- PHP
- Node.js
curl \ -X POST \ -H 'Authorization: Bearer <your-token>' \ 'https://sidetalk-api.p.uliza.jp/v1/rooms/d88c41e1-eefb-4251-85d6-5bfd85c755c4/polls:close/4a366ca5-37c3-4464-9cd7-fba2149a82f0'
Response samples
- 401
- 403
- 404
- 500
Content type
application/json
{- "code": "REQUEST_UNAUTHORIZED",
- "message": "Invalid credentials."
}