Opret en afgrænset læsenøgle
En organisationsadministrator åbner Indstillinger → API og automatisering. Adgang kræver et egnet abonnement, eksempelvis Team. Opret kun de ressourcescopes, applikationen behøver. Kopiér hemmeligheden én gang, og opbevar den uden for versionsstyring. Nøgler udløber efter 30 dage og arver ejerens aktuelle rettigheder. Tilbagekald ubrugte nøgler.
Den offentlige REST-kontrakt tilbyder GET-ressourcer under /api/v1: calls, statistics, employees, teams, dashboards, integrations og organization. Hver ressource kræver sit læsescope, eksempelvis calls:read. Identiteten fastlægger organisationen; en forespørgsel kan ikke vælge en anden tenant. Telefonnumre maskeres. Se præcise filtre og svar i OpenAPI-referencen.
Send en forespørgsel
Sæt CALLMETRA_ORIGIN til din faktiske HTTPS-oprindelse og CALLMETRA_API_KEY til din nøgle i miljøet. Indsæt ikke en rigtig nøgle i eksemplet.
curl --fail --silent --show-error \
-H "Authorization: Bearer $CALLMETRA_API_KEY" \
"$CALLMETRA_ORIGIN/api/v1/calls?page=1&pageSize=20"
Modtag og send hændelser
Egne indgående opkaldswebhooks konfigureres under Integrationer. Den genererede bearer-token er forskellig fra en læse-API-nøgle. Brug schemaVersion 1, unik hændelses-ID, opkalds-ID, occurredAt med eksplicit tidszone, retning og medarbejderens lokalnummer. HTTP 202 betyder varig modtagelse, ikke færdig behandling. Hold indgangs-URL’er og tokens private.
Udgående webhooks sender valgte livscyklushændelser til din offentlige HTTPS-URL. Private/lokale destinationer og omdirigeringer blokeres. Kontrollér Callmetra-Timestamp og Callmetra-Signature mod den præcise rå request-body. Signaturen er HMAC-SHA256 af Unix-tidsstempel, punktum og body; værdien har præfikset v1=. Afvis tidsstempler uden for fem minutter, sammenlign i konstant tid, og deduplikér hændelses-ID. Levering sker mindst én gang med op til otte forsøg. Opbevar signeringshemmeligheden privat, og kontrollér ikke en reserialiseret JSON-body.
Se fejlfinding ved opsætnings- eller leveringsfejl.
Sideinddeling og fejl
Lister bruger sidenumre fra 1 og pageSize mellem 1 og 100. Svar indeholder data og pagination med page, pageSize, total og totalPages. Se opkaldsfiltre for periode, team, medarbejder, retning, status og søgning i OpenAPI. Hver nøgle tillader 120 autoriserede forespørgsler pr. minut. Respektér Retry-After ved HTTP 429. HTTP 401 betyder manglende eller tilbagekaldt autentifikation; 403 betyder utilstrækkeligt scope, rolle eller abonnement. Fejlobjektet indeholder status, code, message og requestId. Gem forespørgsels-ID til support uden at dele nøglen.
Eksempel på egne indgående hændelser
Denne fiktive payload starter et indgående opkald. Send derefter call.answered og call.ended med samme callId og nye hændelses-ID’er. Brug faktiske hændelsestider med eksplicit offset; afspil ikke eksemplet i en produktionsintegration.
{
"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"
}
Kontrollér en udgående signatur
Denne modtagerfunktion kontrollerer den rå UTF-8-body før parsing. Hent signeringshemmeligheden fra sikker serverkonfiguration. Deduplikér derefter Callmetra-Event-Id varigt, før du udfører handlinger.
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);
}