Lesenden Schlüssel erstellen
Als Organisationsadmin öffnest du Einstellungen → API & Automationen. Der Zugriff benötigt einen passenden Tarif, etwa Team. Erstelle einen Schlüssel nur mit den benötigten Ressourcen-Rechten. Kopiere das Geheimnis einmalig und speichere es außerhalb der Versionsverwaltung. Schlüssel laufen nach 30 Tagen ab und erben die aktuellen Rechte des Besitzers. Widerrufe ungenutzte Schlüssel.
Der öffentliche REST-Vertrag bietet GET-Ressourcen unter /api/v1: calls, statistics, employees, teams, dashboards, integrations und organization. Jede Ressource verlangt ihren passenden Lese-Scope, etwa calls:read. Die Identität legt die Organisation fest; Anfragen können keinen anderen Mandanten auswählen. Rufnummern sind maskiert. Exakte Filter und Antworten stehen in der OpenAPI-Referenz.
Anfrage senden
Setze CALLMETRA_ORIGIN in deiner Umgebung auf deinen tatsächlichen HTTPS-Ursprung und CALLMETRA_API_KEY auf deinen Schlüssel. Füge keinen echten Schlüssel in dieses Beispiel ein.
curl --fail --silent --show-error \
-H "Authorization: Bearer $CALLMETRA_API_KEY" \
"$CALLMETRA_ORIGIN/api/v1/calls?page=1&pageSize=20"
Ereignisse empfangen und senden
Eigene eingehende Anruf-Webhooks konfigurierst du unter Integrationen. Der generierte Bearer-Token ist kein lesender API-Schlüssel. Nutze schemaVersion 1, eine eindeutige Ereignis-ID, Anruf-ID, occurredAt mit explizitem Zeitzonenversatz, Richtung und Mitarbeiter-Nebenstelle. HTTP 202 bestätigt dauerhafte Annahme, nicht abgeschlossene Verarbeitung. Halte Eingangs-URLs und Tokens geheim.
Ausgehende Webhooks senden gewählte Lebenszyklus-Ereignisse an deine öffentliche HTTPS-URL. Private/lokale Ziele und Weiterleitungen sind gesperrt. Prüfe Callmetra-Timestamp und Callmetra-Signature gegen den unveränderten Request-Body. Die Signatur ist HMAC-SHA256 aus Unix-Zeitstempel, Punkt und Body; der Wert trägt das Präfix v1=. Lehne Zeitstempel außerhalb von fünf Minuten ab, vergleiche in konstanter Zeit und dedupliziere die Ereignis-ID. Die Zustellung erfolgt mindestens einmal mit bis zu acht Versuchen. Halte das Signiergeheimnis privat und prüfe keinen neu serialisierten JSON-Body.
Bei Einrichtungs- und Zustellfehlern hilft die Fehlerdiagnose.
Seitennavigation und Fehler
Listen verwenden Seitennummern ab 1 und pageSize zwischen 1 und 100. Antworten enthalten data und pagination mit page, pageSize, total und totalPages. Anruf-Filter für Zeitraum, Team, Mitarbeiter, Richtung, Status und Suche stehen in OpenAPI. Pro Schlüssel sind 120 autorisierte Anfragen pro Minute erlaubt. Beachte Retry-After bei HTTP 429. HTTP 401 bedeutet fehlende oder widerrufene Anmeldung; 403 steht für unzureichende Scopes, Rollen oder Tarifrechte. Das Fehlerobjekt enthält status, code, message und requestId. Notiere die Anfrage-ID für Support, ohne den Schlüssel weiterzugeben.
Beispiel für eigene Eingangsereignisse
Dieses fiktive Beispiel beginnt einen eingehenden Anruf. Sende call.answered und call.ended anschließend mit derselben callId und jeweils neuer Ereignis-ID. Nutze tatsächliche Ereigniszeiten mit explizitem Versatz. Spiele dieses Beispiel nicht in eine produktive Verbindung ein.
{
"schemaVersion": 1,
"id": "example-start-1",
"event": "call.started",
"callId": "example-call-1",
"occurredAt": "2026-11-21T10:00:00+01:00",
"direction": "inbound",
"employeeExtension": "101",
"number": "+12025550101"
}
Ausgehende Signatur prüfen
Diese Empfangsfunktion prüft den rohen UTF-8-Body vor dem Parsen. Übergib das Signiergeheimnis aus sicherer Server-Konfiguration. Dedupliziere nach der Prüfung Callmetra-Event-Id dauerhaft, bevor du Folgeaktionen ausführst.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, timestamp, signature, secret) {
if (!/^\d+$/.test(timestamp || '') ||
Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = 'v1=' + createHmac('sha256', secret)
.update(timestamp + '.' + rawBody).digest('hex');
const left = Buffer.from(expected);
const right = Buffer.from(signature || '');
return left.length === right.length && timingSafeEqual(left, right);
}