Brug af Call

Call-API og webhooks for udviklere: nøgler, scopes og events

En praktisk gennemgang af Calls REST API: API-nøgler og scopes, rate limits, fejlhåndtering, signerede webhooks og siden Udviklere, hvor du styrer endpoints.

Calls redaktion · Udgivet · 6 min. læsetid

Før eller siden skal et telefonsystem tale med noget andet: et CRM, der skal vise et opkald, når det slutter, et faktureringsværktøj, der vil vide, hvem der ringede, et script, der foretager et opkald, når en formular sendes. Call har et REST API og udgående webhooks til netop det. Denne guide forklarer, hvordan delene passer sammen, hvad du skal bede om, før du skriver kode, og de fejl, der oftest koster en udvikler en eftermiddag.

En udvikler gennemgår en integration på en bærbar ved siden af en bordtelefon
Illustrativt billede

Hvis dit mål blot er at flytte kontakter i stor mængde, så læs først Import af kontakter til telefonteamets CRM; en import er ofte lettere end en integration.

Hvor du starter: referencen og siden Udviklere

Der er to steder, du skal kende. API-referencen findes under Indstillinger og også i menuen Ressourcer på forsiden. Den kan læses uden login, hvilket er praktisk, når du afgrænser en opgave for en kunde. Siden Udviklere, også under Indstillinger, er til dit eget arbejdsområde: Den viser din organisations og agents id'er, dine webhook-endpoints og en skrivebeskyttet liste over dine nøgler.

Hvad hvert sted giver dig

  • Start herBase-URL og konventioner, godkendelse med en tabel over scopes samt fejl med statuskoder.
  • EndpointsHvert endpointkort viser scope, parametre, request body, svar og fejl med færdige anmodninger til kopiering i curl, JavaScript og Python.
  • SøgningTryk på / for at springe til Søg i endpoints og filtrere efter metode, sti, scope eller resumé.
  • OpenAPI JSONDownloader hele specifikationen som én fil til dine egne værktøjer.
  • Agent-id / APIDit organisations-id og din slug, API-tilstanden (Sandbox eller Live) og id'et for den AI-agent, du vælger, hver med en Kopiér-knap.
  • WebhooksDine endpoints, de events hver af dem modtager, den seneste HTTP-status og eventuelle mislykkede leveringer.

Læs afsnittene om rate limits og udgående webhooks, før du går live, ikke bagefter. De beskriver adfærd, der er let at overse i en hurtig test.

API-nøgler og scopes

Hver anmodning har en nøgle i en Authorization-header som bearer-token. Nøgler oprettes ikke i appen: Operatøren af dit arbejdsområde udsteder dem og fortæller dig, hvilke scopes de har. Den fulde nøgle vises én gang i det øjeblik, den udstedes, og derefter vises kun de første tegn, så gem den i dit eget hemmelighedslager med det samme.

ScopeHvad det tillader
readLæse kontakter, opkald, køer, teammedlemmer, rapporter og listen over frabedte opkald.
writeOprette og opdatere kontakter, registrere opkaldsresultater, tilføje numre til listen over frabedte opkald.
callsForetage og afslutte opkald.
adminAdministrere webhooks; kan også kalde alle andre endpoints.

Bed om det mindste sæt, der løser opgaven. Et rapporteringsscript har brug for read og intet andet; en klik-for-at-ringe-knap har brug for calls. Hvis en anmodning returnerer 403 med koden insufficient_scope, mangler nøglen det scope, der står på det pågældende endpoints kort.

Sandbox og live

Nøgler kan udstedes til en sandbox, der bruger en simulator og ikke foretager rigtige opkald, eller til live brug. Betragt en nøgles præfiks som en etiket og intet andet: En nøgle mærket som test virker på de samme data og den samme telefonforbindelse som en live nøgle, så stol ikke på præfikset til at holde eksperimenter væk fra rigtige kunder. Brug API-tilstanden, der vises på siden Udviklere, for at vide, hvor du står.

Foretag opkald via API'et

De offentlige endpoints dækker det grundlæggende: et sundhedstjek, en liste over opkald, læsning af ét opkald, at foretage et opkald, at lægge på, administration af webhooks og chat med en AI-agent. Et udgående opkald via API'et gennemgår det samme compliancetjek som et opkald foretaget fra skrivebordet, så et nummer på listen over frabedte opkald eller uden for de tilladte tidspunkter for opkald afvises, præcis som det ville blive for en medarbejder. Byg din kode, så den håndterer den afvisning som et normalt udfald, ikke en fejl.

Det har betydning for designet. Skriv ikke en løkke, der prøver et afvist opkald igen, indtil det lykkes. Læs årsagen, log den, og gå videre. For reglerne bag de afvisninger, se Værn om opkaldstidspunkter i Call og Listen over frabedte opkald i Call.

Rate limits og fejl

Hver nøgle har sin egen grænse for anmodninger pr. minut, som fastsættes, når nøglen udstedes; standarden er 120. Når en nøgle har opbrugt minuttet, svarer API'et 429 med koden rate_limited og fortæller i headeren X-RateLimit-Reset, hvor længe du skal vente. Vent så længe, og fortsæt derefter. En høflig klient sætter selv farten ned, før den rammer muren.

Håndter en mislykket anmodning

  1. Læs statusEr det en klientfejl, du kan rette, eller en serverfejl, der er værd at prøve igen?
  2. Læs kodenForgren på koden, aldrig på beskedteksten.
  3. VentVed 429 venter du på reset-headeren; ved serverfejl prøver du igen nogle gange med stigende pauser.
  4. Log detaljerneGem endpointet, koden og tidspunktet, så support kan spore det.
  5. Stop ved afvisningerEn complianceafvisning er en beslutning, ikke en fejl; kør ikke i løkke på den.

Webhooks: modtag events

I stedet for at spørge API'et igen og igen, om noget er sket, så lad Call fortælle dig det. På siden Udviklere trykker du på Tilføj endpoint, indtaster en offentlig https-adresse og sætter flueben ved de events, du vil have; ingen flueben betyder alle events. Signeringshemmeligheden vises én gang, når endpointet tilføjes. Kopiér den da. Hvis den går tabt, så slet endpointet, og tilføj det igen for at få en ny.

Hver levering er signeret. Signaturheaderen indeholder en HMAC-SHA256 af tidsstemplet og body sat sammen med et punktum, beregnet med din signeringshemmelighed, og en separat header indeholder tidsstemplet. Beregn den igen på din side, og sammenlign, før du stoler på indholdet. API-referencen indeholder eksempelkode til det i Node.js og Python, og afvisning af gamle tidsstempler beskytter dig mod genafspillede anmodninger.

En god og en dårlig webhook-modtager

GodDårlig
SignaturVerificeret ved hver anmodningStolet på uden tjek
Svar2xx inden for sekunder, arbejdet sat i kø til senereLangsom behandling før svar
DubletterTåler at modtage samme event to gangeOpretter to poster
FejlAdvarer, når leveringer fejlerTavs, indtil nogen opdager det

Dit endpoint skal svare med en 2xx-status inden for 10 sekunder. En mislykket levering forsøges igen, op til seks forsøg i alt, og et endpoint, der fejler 50 gange i træk, slås fra. Hver række på siden Udviklere viser den seneste HTTP-status, og hvor mange leveringer der er fejlet, og Send test sender én signeret testevent, så du kan se, hvad din server svarer.

En tjekliste før go-live

Før du slår en integration til

  • Du ved, hvilke scopes nøglen har, og den har ikke flere end nødvendigt
  • Nøglen er gemt i et hemmelighedslager, ikke i kildekoden
  • Webhook-signaturer verificeres, og gamle tidsstempler afvises
  • Modtageren svarer hurtigt og håndterer dublerede events
  • Svar om rate limits og afvisninger håndteres uden tætte genforsøgsløkker
  • Du har testet i sandbox-tilstand og trykket på Send test på endpointet
  • En navngiven person modtager en advarsel, hvis leveringer begynder at fejle

Sådan gør du i Call

I Call åbner du Indstillinger og derefter API-reference for at studere endpoints, og Indstillinger og derefter Udviklere for at kopiere dit organisations-id, tjekke dine nøgler og tilføje en webhook. Ejere, administratorer og ledere kan tilføje, teste og slette endpoints; alle andre ser listen. Hvis du også bruger AI-agentfunktionerne, bruges agent-id'et på samme side til chat-endpointet. For stemmesiden af produktet, se Opsætning af en AI-agent i Call.

Ofte stillede spørgsmål

Hvordan får jeg en API-nøgle?

Nøgler udstedes af operatøren af dit arbejdsområde; de kan ikke oprettes i appen. Bed om en, og sig, hvilke scopes den skal have. Den fulde nøgle vises én gang, når den udstedes.

Hvad betyder et 429-svar?

Nøglen har opbrugt sine anmodninger for det aktuelle minut. Vent det antal sekunder, der står i headeren X-RateLimit-Reset, prøv derefter igen, og fordel store opgaver over en længere periode.

Hvordan tjekker jeg, at en webhook virkelig kom fra Call?

Beregn en HMAC-SHA256 af tidsstemplet og body med din signeringshemmelighed, og sammenlign den med signaturheaderen. API-referencen viser eksempler i Node.js og Python.

Kan jeg sende webhooks til en lokal udviklingsserver?

Ikke direkte. Endpoints skal være offentlige https-adresser, så brug et tunnelværktøj, der eksponerer din lokale server på en sådan.

Hvorfor blev mit API-kald om at foretage et opkald afvist?

Opkald foretaget via API'et gennemgår det samme compliancetjek som opkald fra skrivebordet. Et nummer på listen over frabedte opkald eller uden for tidspunkterne for opkald afvises.

Hvem kan se og ændre webhooks?

Alle kan læse listen, men kun ejere, administratorer og ledere kan tilføje, teste eller slette endpoints.

Åbn API-referencen for Call, og tilføj et webhook-endpoint

I demokonsollen kan du afprøve indgående opkald i en simulering.

Relaterede guides