API en integraties

Elke ruimte heeft een HTTP-API. Start en stop timers, toon berichten, voeg tijd toe en lees de rundown uit vanuit een script, een showcontrolsysteem of alles wat een webverzoek kan doen. Een webhook laat je systeem weten wanneer een timer start of afloopt.

Aan de slag

De API bedient dezelfde ruimte als de regieruimte: een aanroep vanuit je tool verschijnt tegelijk op elk scherm.

Verzoeken

Elke aanroep gaat naar https://cliqer.io/api/timer/v1/<room>/<action>. GET, POST, PUT en PATCH werken allemaal. Parameters gaan in de querystring, of in een JSON-body bij POST, PUT en PATCH; de body wint als beide er een hebben. Streepjes in de actienaam werken ook, dus add-time is add_time. /api/timer/v0/ accepteert dezelfde aanroepen.

Stuur de sleutel mee op een van deze manieren, gecontroleerd in deze volgorde:

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

Sleutels en rechten

De API-sleutel van je account kan alles in ruimtes die van jou zijn. Een ruimte kan ook eigen sleutels hebben, elk met een of meer van drie rechten:

Een aanroep die een recht nodig heeft dat de sleutel mist, krijgt 401. Het geheim van een ruimtesleutel wordt één keer getoond, bij het aanmaken. Om de API überhaupt te gebruiken moet de API in je abonnement zitten, zie Abonnementen en limieten.

Acties

timer_id kiest een timer op zijn id; index kiest hem op positie, geteld vanaf 1. Als beide worden meegestuurd, wint timer_id. Laat beide weg om de huidige timer aan te sturen.

Hoeveelheden zijn 30s, 5m, 1h, 250ms of een kaal aantal seconden. seconds werkt in plaats van amount, en met een minteken ga je terug. Schakelaars zoals on, autostart en replace lezen 0, false, off en no als uit en al het andere als aan. Laat on weg bij blackout om hem om te schakelen.

Antwoorden

Elk antwoord is JSON: {"ok": true, "message": "<action>", "data": ...} bij succes, {"ok": false, "message": "...", "code": "..."} bij een fout.

Snelheidslimiet: 100 aanroepen per minuut per sleutel; aanroepen zonder sleutel tellen per adres. Elk antwoord bevat RateLimit-Limit, RateLimit-Remaining en RateLimit-Reset (het aantal seconden tot de minuut opnieuw begint).

Webhooks

De body is {"event", "roomId", "timestamp", "payload"}. De header x-cliqer-timestamp bevat de Unix-tijd in seconden, en x-cliqer-signature bevat sha256= gevolgd door de hexadecimale HMAC-SHA256 van <timestamp>.<body>, met je geheim als sleutel.

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

Bereken de handtekening over de ruwe body, precies zoals die binnenkwam en vóór enige JSON-parsing. Het venster van vijf minuten is je eigen keuze; het voorkomt dat een oud verzoek opnieuw wordt afgespeeld.

Bezorging gebeurt in één poging met een time-out van 5 seconden. Omleidingen worden niet gevolgd, en een adres dat naar een privénetwerk verwijst, wordt overgeslagen. Is een gemist event belangrijk, lees dan get_status uit om weer bij te zijn.

Korte links

GET https://cliqer.io/api/timer/link/<code> zet een korte-linkcode om in de bijbehorende ruimte: {"ok": true, "data": {"roomId", "link"}}, of 404 Link not found bij een onbekende, ingetrokken of verlopen code of een verkeerd wachtwoord. Stuur bij een link met wachtwoord het wachtwoord mee in de header x-link-password, nooit in het adres.

Companion en Stream Deck

Er is geen Companion-module of Stream Deck-plug-in voor Cliqer Timer-ruimtes. De Generic HTTP-module van Bitfocus Companion kan de acties hierboven aanroepen. De eigen timer van de Cliqer-desktopapp heeft een eigen REST API en ondersteuning voor Stream Deck, zie Timer (desktop) en Host-timer.

Veelgestelde vragen

Volgende stappen