API-nøkler og tilganger

Ringhums REST-API lar dine egne systemer jobbe med arbeidsområdet ditt: liste opp samtaler og transkripsjoner, opprette assistenter, bestille avtaler, administrere kontakter, ringe utgående samtaler og mer. Hver forespørsel autentiseres med en API-nøkkel som tilhører ett arbeidsområde. Denne artikkelen dekker hvordan du oppretter nøkler, og konvensjonene som gjelder for alle endepunkter. Den fullstendige endepunktreferansen finner du på /docs.

Hvem kan administrere nøkler

API-et er tilgjengelig på alle planer. Hva en nøkkel kan gjøre, er likevel begrenset av planen din: for eksempel returnerer det en feil å opprette en assistent utover planens grense.

Opprett en API-nøkkel

1. Åpne Utviklere i sidemenyen.
2. I kortet API-nøkler klikker du på Opprett nøkkel.
3. Skriv inn et Nøkkelnavn som viser hvor nøkkelen brukes, for eksempel «Produksjonsserver».
4. Under Tilganger krysser du av for read, write eller begge.
5. Klikk på Opprett nøkkel.
6. Kopier nøkkelen fra den grønne boksen og lagre den et trygt sted, for eksempel serverens hemmelighetslager. Klikk på Ferdig.

Viktig: Nøkkelen vises bare én gang. Ringhum lagrer bare et fingeravtrykk av den, så den kan ikke vises på nytt. Hvis du mister den, oppretter du en ny nøkkel og tilbakekaller den gamle.

Nøkler starter med ck_live_. Tabellen API-nøkler viser navnet på hver nøkkel, de første tegnene i nøkkelen, tilgangene, når den sist ble brukt, og om den er Aktiv eller Tilbakekalt.

Tilganger

Alle nøkler kan kalle endepunktene som bare leser. Endepunkter som oppretter, endrer eller sletter noe, krever tilgangen write. Eksempler er å ringe en samtale, sende en melding, bestille en avtale eller oppdatere en assistent. Referansen på /docs merker disse endepunktene. En nøkkel uten write får en 403-feil på dem.

Gi hvert system den minste tilgangen det trenger. Et rapporteringsdashbord trenger bare read.

Tilbakekall en nøkkel

1. På Utviklere finner du nøkkelen i tabellen API-nøkler.
2. Klikk på Tilbakekall og bekreft.

Forespørsler som bruker nøkkelen, feiler umiddelbart med 401. Tilbakekalte nøkler blir stående i listen, merket Tilbakekalt, slik at du kan se historikken. En nøkkel kan ikke redigeres: for å endre tilgangene oppretter du en ny nøkkel og tilbakekaller den gamle.

Sende forespørsler

• Base-URL: https://ringhum.com/api/v1
• Autentisering: send nøkkelen som et Bearer-token: Authorization: Bearer ck_live_…
• Format: JSON inn og ut. Send Content-Type: application/json med en body.
• Tidspunkter er ISO 8601 i UTC. Telefonnumre er E.164, for eksempel +14155550132. ID-er er heltall.
• Oppdateringer bruker PATCH med bare feltene du vil endre.
• Hvert svar har en X-Request-Id-header. Ta den med når du kontakter support.

curl "https://ringhum.com/api/v1/calls?per_page=10" \
  -H "Authorization: Bearer ck_live_…"

For å sjekke hvilket arbeidsområde en nøkkel tilhører, kaller du GET /me.

Svar og paginering

Et enkelt objekt kommer tilbake som {"data": {…}}. Lister som er paginerte, kommer tilbake med et meta-objekt:

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 87,
    "next_page_url": "https://ringhum.com/api/v1/calls?page=2",
    "prev_page_url": null
  }
}

Bruk page og per_page til å bla gjennom resultatene. per_page er som standard 25 og kan være maks 100.

Feil

Hver feil har samme form, med en stabil type du kan sjekke i koden din:

{
  "error": {
    "type": "validation_error",
    "message": "The to field format is invalid.",
    "errors": { "to": ["Use E.164 format, e.g. +15551234567."] }
  }
}

Hastighetsgrenser

Du kan gjøre 120 forespørsler per minutt. Svarene inneholder headerne X-RateLimit-Limit og X-RateLimit-Remaining. Når du går over grensen, får du 429 med en Retry-After-header som angir hvor mange sekunder du må vente.

Tips: Ikke poll etter samtaleresultater. Legg til en webhook for call.ended, så sender Ringhum sammendraget og transkripsjonen til deg når samtalen er ferdig. Se Webhooker.

Vanlige spørsmål

Finnes det en maskinlesbar spesifikasjon? Ja. OpenAPI 3.1-beskrivelsen finner du på /api/v1/openapi.json, og den krever ingen nøkkel. Du kan generere en klient ut fra den.

Slutter en nøkkel å fungere hvis personen som opprettet den, slutter? Nei. Nøkler tilhører arbeidsområdet og fortsetter å fungere til de tilbakekalles. Tilbakekall nøkler du ikke lenger stoler på, spesielt når noen med tilgang slutter.

Kan jeg bruke API-et fra en nettside? Nei. Alle som åpner siden, kan lese nøkkelen. Kall API-et fra serveren din.