API と連携

すべてのルームに HTTP API があります。スクリプト、ショーコントロールシステム、その他 Web リクエストを送れるものなら何からでも、タイマーの開始と停止、メッセージの表示、時間の追加、ランダウンの読み取りができます。タイマーが開始または終了すると、Webhook でシステムに通知します。

はじめに

API はコントロールルームと同じルームを操作します。ツールからの呼び出しは、すべての画面に同時に反映されます。

リクエスト

すべての呼び出しは https://cliqer.io/api/timer/v1/<room>/<action> の形式です。GET、POST、PUT、PATCH のいずれも使えます。パラメーターはクエリ文字列で渡すか、POST、PUT、PATCH では JSON ボディで渡します。両方に同じパラメーターがある場合はボディが優先されます。アクション名にはダッシュも使えるため、add-time は add_time と同じです。/api/timer/v0/ でも同じ呼び出しを受け付けます。

キーは次のいずれかで送信します。この順番で確認されます。

curl -X POST https://cliqer.io/api/timer/v1/<room>/add_time \
  -H "Authorization: Bearer $CLIQER_KEY" \
  -H "content-type: application/json" \
  -d '{"timer_id": "<timer>", "amount": "2m"}'

const res = await fetch('https://cliqer.io/api/timer/v1/<room>/add_time', {
  method: 'POST',
  headers: { 'authorization': `Bearer ${process.env.CLIQER_KEY}`, 'content-type': 'application/json' },
  body: JSON.stringify({ timer_id: '<timer>', amount: '2m' }),
})
const { ok, message, data } = await res.json()

import os, requests

r = requests.post(
    "https://cliqer.io/api/timer/v1/<room>/add_time",
    headers={"Authorization": f"Bearer {os.environ['CLIQER_KEY']}"},
    json={"timer_id": "<timer>", "amount": "2m"},
)
print(r.json())

キーと権限

アカウントの API キーは、自分が所有するルームですべての操作ができます。ルームに専用のキーを持たせることもでき、各キーには次の 3 つの権限から必要なものを付与します。

キーに付与されていない権限が必要な呼び出しには 401 が返されます。ルームキーのシークレットは、作成時に一度だけ表示されます。API を利用するには、プランに API が含まれている必要があります。プランと制限 をご覧ください。

アクション

timer_id は ID でタイマーを指定し、index は 1 から数えた位置で指定します。両方を送った場合は timer_id が優先されます。どちらも省略すると、現在のタイマーが対象になります。

時間量 は 30s、5m、1h、250ms、または秒数の数値だけで指定します。amount の代わりに seconds も使え、マイナス記号を付けると逆方向になります。on、autostart、replace などの スイッチ は、0、false、off、no をオフ、それ以外をオンとして扱います。blackout で on を省略すると切り替えになります。

レスポンス

すべての応答は JSON です。成功時は {"ok": true, "message": "<action>", "data": ...}、失敗時は {"ok": false, "message": "...", "code": "..."} が返されます。

レート制限： キーごとに 1 分あたり 100 回です。キーなしの呼び出しはアドレスごとにカウントされます。各応答には RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset（次の 1 分が始まるまでの秒数）が含まれます。

Webhook

ボディは {"event", "roomId", "timestamp", "payload"} です。x-cliqer-timestamp ヘッダーには Unix 時間（秒）が入り、x-cliqer-signature には sha256= に続けて、シークレットをキーとした <timestamp>.<body> の HMAC-SHA256 の 16 進値が入ります。

# Recompute the signature of a saved body.
printf '%s.%s' "$TIMESTAMP" "$(cat body.json)" \
  | openssl dgst -sha256 -hmac "$WHSEC" -hex

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verify(rawBody: string, timestamp: string, signature: string, secret: string) {
  const want = `sha256=${createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex')}`
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300
  return fresh && want.length === signature.length && timingSafeEqual(Buffer.from(want), Buffer.from(signature))
}

import hashlib, hmac, time

def verify(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    mac = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256)
    fresh = abs(time.time() - int(timestamp)) < 300
    return fresh and hmac.compare_digest("sha256=" + mac.hexdigest(), signature)

署名は、JSON を解析する前の、受信したままの生のボディで計算してください。5 分という時間枠は任意で決められます。古いリクエストが再送（リプレイ）されるのを防ぐためのものです。

配信は 1 回のみで、タイムアウトは 5 秒です。リダイレクトはたどらず、プライベートネットワークに解決されるアドレスへの配信は破棄されます。取りこぼしたイベントが重要な場合は、get_status を読み取って最新の状態を取得してください。

短縮リンク

GET https://cliqer.io/api/timer/link/<code> は、短縮リンクのコードを対応するルームに変換し、{"ok": true, "data": {"roomId", "link"}} を返します。不明、無効化済み、期限切れのコード、またはパスワードが間違っている場合は 404 Link not found が返されます。パスワード付きのリンクでは、パスワードをアドレスに含めず、必ず x-link-password ヘッダーで送信してください。

Companion と Stream Deck

Cliqer Timer のルーム用の Companion モジュールや Stream Deck プラグインはありません。Bitfocus Companion の Generic HTTP モジュールで上記のアクションを呼び出せます。Cliqer デスクトップアプリに内蔵されたタイマーには独自の REST API と Stream Deck 対応があります。Timer（デスクトップ） と ホストのタイマー をご覧ください。

よくある質問

次へ