På denne side
callmetra.Dokumentation
Arbejdsområde ↗
Dokumentationsnavigation
callmetra./Dokumentation/API-nøgler og webhooks

Udviklere

API-nøgler og webhooks

Læseadgang til API, egne opkaldshændelser og signerede leveringer.

Opdateret

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.

API-indstillinger i den offentlige demo uden oprettelse eller eksponering af en nøgle.
API-indstillinger i den offentlige demo uden oprettelse eller eksponering af en nøgle.

API-indstillinger i den offentlige demo uden oprettelse eller eksponering af en nøgle.

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);
}
callmetra. · Every call. Measurable insights.Kontakt ↗