API und Integrationen

Jeder Raum hat eine HTTP-API. Starten und stoppen Sie Timer, zeigen Sie Nachrichten an, fügen Sie Zeit hinzu und lesen Sie den Ablaufplan aus, und zwar aus einem Skript, einem Showsteuerungssystem oder allem, was eine Webanfrage senden kann. Ein Webhook informiert Ihr System, wenn ein Timer startet oder endet.

Erste Schritte

Die API steuert denselben Raum wie der Kontrollraum: Ein Aufruf aus Ihrem Tool erscheint gleichzeitig auf allen Bildschirmen.

Anfragen

Jeder Aufruf lautet https://cliqer.io/api/timer/v1/<room>/<action>. GET, POST, PUT und PATCH funktionieren alle. Parameter stehen im Query-String oder bei POST, PUT und PATCH in einem JSON-Body; enthalten beide einen Wert, gilt der Body. Bindestriche im Aktionsnamen funktionieren ebenfalls, add-time entspricht also add_time. /api/timer/v0/ akzeptiert dieselben Aufrufe.

Senden Sie den Schlüssel auf eine dieser Arten, geprüft in dieser Reihenfolge:

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())

Schlüssel und Berechtigungen

Mit dem API-Schlüssel Ihres Kontos können Sie in allen Räumen, die Ihnen gehören, alles tun. Ein Raum kann außerdem eigene Schlüssel haben, jeweils mit einer Auswahl aus drei Berechtigungen:

Ein Aufruf, der eine Berechtigung benötigt, die dem Schlüssel fehlt, erhält 401. Das Secret eines Raumschlüssels wird nur einmal angezeigt, bei seiner Erstellung. Damit Sie die API überhaupt nutzen können, muss sie in Ihrem Plan enthalten sein, siehe Pläne und Limits.

Aktionen

timer_id wählt einen Timer über seine ID aus; index wählt ihn über seine Position aus, gezählt ab 1. Werden beide gesendet, gilt timer_id. Lassen Sie beide weg, um den aktuellen Timer anzusprechen.

Beträge sind 30s, 5m, 1h, 250ms oder eine einfache Zahl in Sekunden. seconds funktioniert anstelle von amount, und ein Minuszeichen geht rückwärts. Schalter wie on, autostart und replace werten 0, false, off und no als aus und alles andere als ein. Lassen Sie on bei blackout weg, um den Blackout umzuschalten.

Antworten

Jede Antwort ist JSON: {"ok": true, "message": "<action>", "data": ...} bei Erfolg, {"ok": false, "message": "...", "code": "..."} bei einem Fehler.

Ratenlimit: 100 Aufrufe pro Minute und Schlüssel; Aufrufe ohne Schlüssel werden pro Adresse gezählt. Jede Antwort enthält RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset (Sekunden, bis die Minute neu beginnt).

Webhooks

Der Body ist {"event", "roomId", "timestamp", "payload"}. Der Header x-cliqer-timestamp enthält die Unix-Zeit in Sekunden, und x-cliqer-signature enthält sha256= gefolgt vom hexadezimalen HMAC-SHA256 von <timestamp>.<body>, mit Ihrem Secret als Schlüssel.

# 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)

Signieren Sie den Rohbody genau so, wie er angekommen ist, vor jedem JSON-Parsing. Das Fünf-Minuten-Fenster legen Sie selbst fest; es verhindert, dass eine alte Anfrage erneut eingespielt wird.

Die Zustellung erfolgt mit einem einzigen Versuch und 5 Sekunden Timeout. Weiterleitungen werden nicht verfolgt, und eine Adresse, die in ein privates Netzwerk auflöst, wird verworfen. Wenn ein verpasstes Ereignis wichtig ist, lesen Sie get_status, um den aktuellen Stand abzurufen.

Kurzlinks

GET https://cliqer.io/api/timer/link/<code> löst einen Kurzlink-Code in seinen Raum auf: {"ok": true, "data": {"roomId", "link"}}, oder 404 Link not found bei einem unbekannten, widerrufenen oder abgelaufenen Code oder einem falschen Passwort. Bei einem Link mit Passwort senden Sie dieses im Header x-link-password, niemals in der Adresse.

Companion und Stream Deck

Es gibt kein Companion-Modul und kein Stream Deck Plugin für Räume in Cliqer Timer. Das Generic HTTP Modul von Bitfocus Companion kann die oben genannten Aktionen aufrufen. Der eigene Timer der Cliqer Desktop-App hat eine eigene REST-API und Unterstützung für Stream Deck, siehe Timer (Desktop) und Host-Timer.

Häufige Fragen

Weiter