API Specifications for ULIZA Sidetalk (v1.6.0)

本書は ULIZA Sidetalk が提供する API 仕様について記述しています。ULIZA Sidetalk の機能や管理画面の操作方法については ULIZA Sidetalk ユーザーガイド を参照してください。

なお、本書に掲載しているコードサンプル(Request samples)は、具体的な実装例を示すことで開発者を支援することを目的としていますが、掲載しているコードがすべての環境において正常に動作することを保証するものではありません。また、コードサンプル内で使用している関数やライブラリの安全性に関して、弊社は何ら責任を負うものではありません。

CHANGELOG

バージョン 改版日 改版内容
v1.0.0 2020/10/21 初版
v1.1.0 2021/04/05
  1. アンケート管理系 API を追加
v1.2.0 2021/08/10
  1. ルームの属性に profanities_method (NG ワードや URL の処理方法)を追加
  2. アンケートの属性に display_format (集計結果表示形式)を追加
  3. アンケート取得系 API のレスポンスに opened_at (回答受付開始日時)を追加
v1.3.0 2021/08/31
  1. NG ワードや URL の処理方法に sender_only (NG ワードや URL を含むメッセージを送信者のみに表示)を追加
v1.4.0 2022/03/22
  1. ルームの属性に disable_username (ユーザー名を収集および表示しない)を追加
  2. アンケート更新 APIを追加
v1.6.0 2022/08/08
  1. メッセージ履歴取得 API のレスポンスに userid (ユーザーID)を追加

Authentication

特に断りのない限り、本書に記載されている全ての API に対するリクエストの Authorization ヘッダに下記の形式で有効な API 認証キーを含める必要があります。API 認証キーの取得方法については ULIZA プロダクトアカウントユーザーガイド を参照してください。リクエストに有効な API 認証キーが含まれていない場合は、401 Unauthorized が返却されます。

Authorization: Bearer <api-credential>

Rooms

ルーム管理系 API について以下に記述します。

ルーム全取得 API

すべてのルームを取得します。リクエスト送信者が ルームの取得 権限を持っていない場合は、403 Forbidden が返却されます。

query Parameters
statistics
string^\d+:\d+$

統計情報の粒度(1, 5, 10, 30 または 60 の倍数。秒単位)および現在から起算した取得範囲(データの個数)を : で連結した文字列。省略した場合は統計情報 statistics は返却されません。

Responses

Response Schema: application/json
Array of objects (Room)

ルーム情報

Request samples

curl \
  -H 'Authorization: Bearer <your-token>' \
  'https://sidetalk-api.p.uliza.jp/v1/rooms'

Response samples

Content type
application/json
{
  • "data": [
    ]
}

ルーム登録 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 の処理方法

  • replace : NG ワードや URL を「***」に置換して送信
  • reject : NG ワードや URL を含むメッセージの送信を禁止
  • 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

Content type
application/json
{
  • "name": "sample-room",
  • "max_clients": 1000,
  • "disable_username": false,
  • "embeddable_domains": [
    ],
  • "show_clients_count": true,
  • "custom_styles": ".message.moderator { color: red; }",
  • "profanities": [
    ],
  • "profanities_method": "reject",
  • "blacklist_ipv4": [
    ],
  • "cooldown_seconds": 3,
  • "allow_client_deletes": true,
  • "allow_repeated_posts": true,
  • "allow_post_links": true
}

Response samples

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 の倍数。秒単位)および現在から起算した取得範囲(データの個数)を : で連結した文字列。省略した場合は統計情報 statistics は返却されません。

Responses

Response Schema: application/json
id
string <UUID>

ルーム ID

name
string <= 200 characters

ルームの名前

status
string

以下のいずれかの状態

  • open : オープン(誰でもメッセージを送信可能)
  • close : クローズ(モデレータのみメッセージを送信可能)
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 の処理方法

  • replace : NG ワードや URL を「***」に置換して送信
  • reject : NG ワードや URL を含むメッセージの送信を禁止
  • 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

curl \
  -H