Använda Call

Calls API och webhooks för utvecklare: nycklar, scopes, händelser

En praktisk genomgång av Calls REST API: API-nycklar och scopes, anropsgränser, felhantering, signerade webhooks och sidan Utvecklare där du hanterar endpoints.

Redaktionen för Call · Publicerad · 6 min läsning

Förr eller senare måste ett telefonsystem prata med något annat: ett CRM som ska visa ett samtal när det avslutas, ett faktureringsverktyg som vill veta vem som ringde, ett skript som ringer upp när ett formulär skickas in. Call har ett REST API och utgående webhooks för just detta. Den här guiden förklarar hur delarna hänger ihop, vad du ska be om innan du skriver kod och de misstag som oftast kostar en utvecklare en eftermiddag.

En utvecklare granskar en integration på en bärbar dator bredvid en bordstelefon
Illustrationsbild

Om ditt mål bara är att flytta kontakter i stora mängder, läs först Importera kontakter till ett CRM för telefonteam; en import är ofta enklare än en integration.

Var du börjar: referensen och sidan Utvecklare

Det finns två ställen att känna till. API-referensen finns under Inställningar, och även i menyn Resurser på startsidan. Den kan läsas utan inloggning, vilket är praktiskt när du avgränsar ett uppdrag åt en kund. Sidan Utvecklare, också under Inställningar, gäller din egen arbetsyta: den visar identifierarna för din organisation och dina agenter, dina webhook-endpoints och en skrivskyddad lista över dina nycklar.

Vad varje ställe ger dig

  • Börja härBas-URL och konventioner, autentisering med en tabell över scopes samt fel med statuskoder.
  • EndpointsVarje endpoint-kort listar scope, parametrar, anropskropp, svar och fel, med färdiga anrop att kopiera i curl, JavaScript och Python.
  • SökTryck på / för att hoppa till Sök endpoints och filtrera på metod, sökväg, scope eller sammanfattning.
  • OpenAPI JSONLaddar ned hela specifikationen som en enda fil för dina egna verktyg.
  • Agent-ID / APIOrganisationens ID och slug, API-läget (Sandbox eller Live) och ID:t för den AI-agent du väljer, var och en med en Kopiera-knapp.
  • WebhooksDina endpoints, vilka händelser var och en tar emot, senaste HTTP-status och eventuella misslyckade leveranser.

Läs avsnitten om anropsgränser och utgående webhooks innan du går live, inte efteråt. De beskriver beteenden som är lätta att missa i ett snabbt test.

API-nycklar och scopes

Varje anrop har en nyckel i en Authorization-header som bearer-token. Nycklar skapas inte i appen: operatören för din arbetsyta utfärdar dem och talar om vilka scopes de har. Hela nyckeln visas en gång, när den utfärdas, och därefter syns bara de första tecknen, så spara den direkt i ditt eget hemlighetsvalv.

ScopeVad den tillåter
readLäsa kontakter, samtal, köer, teammedlemmar, rapporter och spärrlistan.
writeSkapa och uppdatera kontakter, registrera samtalsutfall, lägga till nummer i spärrlistan.
callsRinga och avsluta samtal.
adminHantera webhooks; får även anropa alla andra endpoints.

Be om den minsta uppsättning som klarar jobbet. Ett rapportskript behöver read och inget annat; en klicka-för-att-ringa-knapp behöver calls. Om ett anrop returnerar 403 med koden insufficient_scope saknar nyckeln det scope som anges på endpointens kort.

Sandbox och live

Nycklar kan utfärdas för en sandbox, som använder en simulator och inte ringer några riktiga samtal, eller för skarp användning. Se en nyckels prefix enbart som en etikett: en nyckel märkt som test fungerar mot samma data och samma telefonanslutning som en skarp, så förlita dig inte på prefixet för att hålla experiment borta från riktiga kunder. Använd API-läget som visas på sidan Utvecklare för att veta var du står.

Ringa samtal via API:t

De publika endpoints täcker grunderna: en hälsokontroll, lista samtal, läsa ett samtal, ringa ett samtal, lägga på, hantera webhooks och chatta med en AI-agent. Ett utgående samtal som rings via API:t går igenom samma regelkontroll som ett samtal från kundtjänsten, så ett nummer på spärrlistan eller utanför tillåtna ringtider nekas, precis som för en handläggare. Bygg din kod så att den hanterar nekandet som ett normalt utfall, inte som en bugg.

Det här spelar roll för designen. Skriv inte en loop som försöker ringa ett nekat samtal igen tills det fungerar. Läs orsaken, logga den och gå vidare. För reglerna bakom nekandena, se Spärr för ringtider i Call och Spärrlistan i Call.

Anropsgränser och fel

Varje nyckel har en egen gräns för anrop per minut, som sätts när nyckeln utfärdas; standardvärdet är 120. När en nyckel har förbrukat minuten svarar API:t 429 med koden rate_limited och talar om hur länge du ska vänta i headern X-RateLimit-Reset. Vänta så länge och fortsätt sedan. En hänsynsfull klient saktar ned själv innan den slår i väggen.

Hantera ett misslyckat anrop

  1. Läs statusenÄr det ett klientfel du kan rätta, eller ett serverfel som är värt att försöka igen?
  2. Läs kodenFörgrena på koden, aldrig på meddelandetexten.
  3. BackaVid 429, vänta enligt reset-headern; vid serverfel, försök igen några gånger med ökande fördröjning.
  4. Logga detaljernaSpara endpoint, kod och tidpunkt så att supporten kan spåra det.
  5. Stanna vid nekandenEtt nekande på grund av regelkontrollen är ett beslut, inte ett fel; loopa inte på det.

Webhooks: ta emot händelser

I stället för att fråga API:t om och om igen om något har hänt kan du låta Call tala om det. På sidan Utvecklare trycker du på Lägg till endpoint, anger en publik https-adress och kryssar i de händelser du vill ha; inga ikryssade betyder alla händelser. Signeringshemligheten visas en gång, när endpointen läggs till. Kopiera den då. Om den försvinner, ta bort endpointen och lägg till den igen för att få en ny.

Varje leverans är signerad. Signaturheadern innehåller en HMAC-SHA256 av tidsstämpeln och kroppen sammanfogade med en punkt, beräknad med din signeringshemlighet, och en separat header innehåller tidsstämpeln. Beräkna den på din sida och jämför innan du litar på innehållet. API-referensen innehåller exempelkod för detta i Node.js och Python, och att avvisa gamla tidsstämplar skyddar dig mot uppspelade anrop.

En bra och en dålig webhook-mottagare

BraDålig
SignaturVerifieras vid varje anropBetrodd utan kontroll
Svar2xx inom några sekunder, arbetet köas till senareLångsam bearbetning innan svaret
DubbletterTål att ta emot samma händelse två gångerSkapar två poster
FelLarmar när leveranser misslyckasTyst tills någon märker det

Din endpoint måste svara med en 2xx-status inom 10 sekunder. En misslyckad leverans görs om, upp till sex försök totalt, och en endpoint som misslyckas 50 gånger i rad stängs av. Varje rad på sidan Utvecklare visar senaste HTTP-status och hur många leveranser som misslyckades, och Skicka test skickar en signerad testhändelse så att du kan se vad din server svarar.

En checklista inför driftstart

Innan du slår på en integration

  • Du vet vilka scopes nyckeln har, och den har inte fler än nödvändigt
  • Nyckeln är sparad i ett hemlighetsvalv, inte i källkoden
  • Webhook-signaturer verifieras och gamla tidsstämplar avvisas
  • Mottagaren svarar snabbt och hanterar dubbla händelser
  • Svar om anropsgränser och nekanden hanteras utan täta loopar för nya försök
  • Du har testat i sandbox-läge och tryckt på Skicka test för endpointen
  • Någon är utsedd att ta emot ett larm om leveranser börjar misslyckas

Så gör du i Call

I Call öppnar du Inställningar och sedan API-referens för att studera endpoints, och Inställningar och sedan Utvecklare för att kopiera organisationens ID, kontrollera dina nycklar och lägga till en webhook. Ägare, administratörer och chefer kan lägga till, testa och ta bort endpoints; alla andra ser listan. Om du även använder AI-agentfunktionerna används agent-ID:t på samma sida i chatt-endpointen. För röstdelen av produkten, se Konfigurera en AI-agent i Call.

Vanliga frågor

Hur får jag en API-nyckel?

Nycklar utfärdas av operatören för din arbetsyta; de kan inte skapas i appen. Be om en och ange vilka scopes den behöver. Hela nyckeln visas en gång när den utfärdas.

Vad betyder ett 429-svar?

Nyckeln har förbrukat sina anrop för den aktuella minuten. Vänta det antal sekunder som anges i headern X-RateLimit-Reset, försök sedan igen, och sprid ut massarbete över en längre period.

Hur kontrollerar jag att en webhook verkligen kom från Call?

Beräkna en HMAC-SHA256 av tidsstämpeln och kroppen med din signeringshemlighet och jämför den med signaturheadern. API-referensen visar exempel i Node.js och Python.

Kan jag skicka webhooks till en lokal utvecklingsserver?

Inte direkt. Endpoints måste vara publika https-adresser, så använd ett tunnelverktyg som exponerar din lokala server på en sådan.

Varför nekades mitt API-anrop för att ringa ett samtal?

Samtal som rings via API:t går igenom samma regelkontroll som samtal från kundtjänsten. Ett nummer på spärrlistan eller utanför ringtiderna nekas.

Vem kan se och ändra webhooks?

Alla kan läsa listan, men bara ägare, administratörer och chefer kan lägga till, testa eller ta bort endpoints.

Öppna API-referensen för Call och lägg till en webhook-endpoint

I demokonsolen kan du prova inkommande samtal i en simulering.

Relaterade guider