Callin API ja webhookit kehittäjille: avaimet, oikeudet, tapahtumat
Käytännön kierros Callin REST-rajapintaan: API-avaimet ja oikeusalueet, nopeusrajoitukset, virheet, allekirjoitetut webhookit ja Kehittäjät-sivu päätepisteille.
Ennemmin tai myöhemmin puhelinjärjestelmän on keskusteltava jonkin muun kanssa: CRM:n, jonka pitäisi näyttää puhelu sen päättyessä, laskutustyökalun, joka haluaa tietää, kuka soitti, tai skriptin, joka soittaa puhelun lomakkeen lähettämisen jälkeen. Callissa on juuri tätä varten REST-rajapinta ja lähtevät webhookit. Tässä oppaassa kerrotaan, miten osat sopivat yhteen, mitä pyytää ennen koodin kirjoittamista ja mitkä virheet useimmin maksavat kehittäjältä iltapäivän.

Jos tavoitteesi on vain siirtää yhteystietoja massana, lue ensin Yhteystietojen tuominen puhelintiimin CRM:ään; tuonti on usein helpompi kuin integraatio.
Mistä aloittaa: viite ja Kehittäjät-sivu
On kaksi paikkaa, jotka kannattaa tuntea. API-viite löytyy kohdasta Asetukset sekä etusivun Resurssit-valikosta. Sitä voi lukea kirjautumatta, mikä on kätevää, kun arvioit työn laajuutta asiakkaalle. Myös kohdassa Asetukset on sivu Kehittäjät, joka on omaa työtilaasi varten: se näyttää organisaatiosi ja agenttiesi tunnisteet, webhook-päätepisteesi ja vain luku -luettelon avaimistasi.
Mitä kukin paikka antaa
- Aloita tästäPerus-URL ja käytännöt, todennus oikeusaluetaulukon kera sekä virheet tilakoodeineen.
- PäätepisteetJokainen päätepistekortti listaa oikeusalueensa, parametrit, pyynnön rungon, vastauksen ja virheet sekä valmiiksi kopioitavat pyynnöt curlilla, JavaScriptillä ja Pythonilla.
- HakuPaina / siirtyäksesi kohtaan Hae päätepisteitä ja suodata metodin, polun, oikeusalueen tai yhteenvedon mukaan.
- OpenAPI JSONLataa koko määrittelyn yhtenä tiedostona omia työkalujasi varten.
- Agentin tunnus / APIOrganisaatiosi tunnus ja lyhytnimi, API-tila (Sandbox tai Live) ja valitsemasi tekoälyagentin tunnus, kukin Kopioi-painikkeen kera.
- WebhookitPäätepisteesi, kunkin vastaanottamat tapahtumat, viimeisin HTTP-tila ja epäonnistuneet toimitukset.
Lue nopeusrajoituksia ja lähteviä webhookeja koskevat osiot ennen tuotantoon siirtymistä, ei sen jälkeen. Ne kuvaavat käyttäytymistä, joka jää nopeassa testissä helposti huomaamatta.
API-avaimet ja oikeusalueet
Jokainen pyyntö kantaa avainta Authorization-otsakkeessa bearer-tunnisteena. Avaimia ei luoda sovelluksessa: työtilasi alustan ylläpitäjä myöntää ne ja kertoo, mitä oikeusalueita niillä on. Koko avain näytetään kerran myöntämishetkellä, ja sen jälkeen näkyvät vain sen ensimmäiset merkit, joten tallenna se heti omaan salaisuuksien säilöösi.
| Oikeusalue | Mitä se sallii |
|---|---|
| read | Yhteystietojen, puhelujen, jonojen, tiimin jäsenten, raporttien ja kieltolistan lukeminen. |
| write | Yhteystietojen luominen ja päivittäminen, puhelujen lopputulosten kirjaaminen, numeroiden lisääminen kieltolistalle. |
| calls | Puhelujen soittaminen ja lopettaminen. |
| admin | Webhookien hallinta; voi myös kutsua kaikkia muita päätepisteitä. |
Pyydä pienin joukko, joka hoitaa tehtävän. Raportointiskripti tarvitsee read-oikeuden eikä mitään muuta; napsauta ja soita -painike tarvitsee calls-oikeuden. Jos pyyntö palauttaa 403-vastauksen koodilla insufficient_scope, avaimelta puuttuu päätepisteen kortissa näkyvä oikeusalue.
Sandbox ja live
Avaimia voidaan myöntää sandboxiin, joka käyttää simulaattoria eikä soita oikeita puheluja, tai tuotantokäyttöön. Pidä avaimen etuliitettä pelkkänä nimilappuna: testiksi merkitty avain toimii samoilla tiedoilla ja samalla puhelinyhteydellä kuin tuotantoavain, joten älä luota etuliitteeseen kokeilujen pitämisessä erossa oikeista asiakkaista. Käytä Kehittäjät-sivulla näkyvää API-tilaa tietääksesi, missä olet.
Puhelujen soittaminen API:n kautta
Julkiset päätepisteet kattavat perusasiat: terveystarkistuksen, puhelujen listaamisen, yksittäisen puhelun lukemisen, puhelun soittamisen, puhelun lopettamisen, webhookien hallinnan ja keskustelun tekoälyagentin kanssa. API:n kautta soitettu lähtevä puhelu käy läpi saman vaatimustenmukaisuustarkistuksen kuin työpisteeltä soitettu puhelu, joten kieltolistalla oleva tai sallittujen soittoaikojen ulkopuolella oleva numero torjutaan, aivan kuten agentin kohdalla. Rakenna koodisi käsittelemään torjuntaa normaalina lopputuloksena, ei virheenä.
Tällä on merkitystä suunnittelulle. Älä kirjoita silmukkaa, joka yrittää torjuttua puhelua uudelleen, kunnes se onnistuu. Lue syy, kirjaa se lokiin ja jatka eteenpäin. Torjuntojen taustalla olevista säännöistä kerrotaan oppaissa Soittoaikojen valvonta Callissa ja Kieltolista Callissa.
Nopeusrajoitukset ja virheet
Jokaisella avaimella on oma pyyntöä minuutissa -rajansa, joka asetetaan avainta myönnettäessä; oletus on 120. Kun avain käyttää minuutin kiintiönsä loppuun, API vastaa 429 koodilla rate_limited ja kertoo X-RateLimit-Reset-otsakkeessa, kuinka kauan odottaa. Odota se aika ja jatka sitten. Kohtelias asiakasohjelma hidastaa itseään ennen kuin törmää seinään.
- 429 rate_limited: pidä tauko nollausotsakkeen ilmoittaman ajan ja levitä massatyö pidemmälle ajalle.
- 403 insufficient_scope: avaimelta puuttuu päätepisteen kortissa mainittu oikeusalue; pyydä avain, jolla se on.
- Muut virheet: toimi virhekoodin, älä viestin perusteella. Koodit eivät muutu; sanamuoto voi muuttua.
Epäonnistuneen pyynnön käsittely
- Lue tilaOnko kyse asiakasvirheestä, jonka voit korjata, vai palvelinvirheestä, jota kannattaa yrittää uudelleen?
- Lue koodiHaaraudu koodin, älä koskaan viestitekstin perusteella.
- Pidä tauko429:n kohdalla odota nollausotsakkeen mukaan; palvelinvirheissä yritä muutaman kerran kasvavin viivein.
- Kirjaa yksityiskohdatSäilytä päätepiste, koodi ja aika, jotta tuki voi jäljittää tapahtuman.
- Pysähdy torjuntoihinVaatimustenmukaisuustorjunta on päätös, ei häiriö; älä toista sitä silmukassa.
Webhookit: tapahtumien vastaanottaminen
Sen sijaan, että kysyisit API:lta yhä uudelleen, onko jotain tapahtunut, anna Callin kertoa. Paina Kehittäjät-sivulla Lisää päätepiste, syötä julkinen https-osoite ja valitse haluamasi tapahtumat; jos et valitse yhtään, saat kaikki tapahtumat. Allekirjoitusavain näytetään kerran, kun päätepiste lisätään. Kopioi se silloin. Jos se katoaa, poista päätepiste ja lisää se uudelleen saadaksesi uuden.
Jokainen toimitus on allekirjoitettu. Allekirjoitusotsake sisältää HMAC-SHA256-tiivisteen aikaleimasta ja rungosta pisteellä yhdistettyinä, laskettuna allekirjoitusavaimellasi, ja erillinen otsake kantaa aikaleimaa. Laske se uudelleen omalla puolellasi ja vertaa ennen kuin luotat sisältöön. API-viite sisältää tätä varten esimerkkikoodia Node.js:llä ja Pythonilla, ja vanhojen aikaleimojen hylkääminen suojaa uudelleentoistetuilta pyynnöiltä.
Hyvä ja huono webhook-vastaanotin
| Hyvä | Huono | |
|---|---|---|
| Allekirjoitus | Tarkistetaan jokaisessa pyynnössä | Luotetaan tarkistamatta |
| Vastaus | 2xx sekunneissa, työ jonoon myöhemmäksi | Hidas käsittely ennen vastausta |
| Kaksoiskappaleet | Saman tapahtuman voi vastaanottaa turvallisesti kahdesti | Luo kaksi tietuetta |
| Epäonnistumiset | Hälyttää, kun toimitukset epäonnistuvat | Hiljaa, kunnes joku huomaa |
Päätepisteesi on vastattava 2xx-tilakoodilla 10 sekunnin kuluessa. Epäonnistunutta toimitusta yritetään uudelleen, enintään kuusi yritystä yhteensä, ja päätepiste, joka epäonnistuu 50 kertaa peräkkäin, kytketään pois päältä. Jokainen rivi Kehittäjät-sivulla näyttää viimeisimmän HTTP-tilan ja epäonnistuneiden toimitusten määrän, ja Lähetä testi lähettää yhden allekirjoitetun testitapahtuman, jotta näet, mitä palvelimesi vastaa.
Tarkistuslista tuotantoon siirtymiseen
Ennen kuin kytket integraation päälle
- Tiedät, mitä oikeusalueita avaimella on, eikä niitä ole enempää kuin tarvitaan
- Avain on tallennettu salaisuuksien säilöön, ei lähdekoodiin
- Webhookien allekirjoitukset tarkistetaan ja vanhat aikaleimat hylätään
- Vastaanotin vastaa nopeasti ja käsittelee kaksinkertaiset tapahtumat
- Nopeusrajoitus- ja torjuntavastaukset käsitellään ilman tiukkoja uudelleenyrityssilmukoita
- Testasit sandbox-tilassa ja painoit päätepisteen kohdalla Lähetä testi
- Joku on nimetty vastaanottamaan hälytys, jos toimitukset alkavat epäonnistua
Näin se tehdään Callissa
Avaa Callissa Asetukset ja sitten API-viite tutkiaksesi päätepisteitä, ja Asetukset ja sitten Kehittäjät kopioidaksesi organisaatiosi tunnuksen, tarkistaaksesi avaimesi ja lisätäksesi webhookin. Omistajat, ylläpitäjät ja esihenkilöt voivat lisätä, testata ja poistaa päätepisteitä; muut näkevät luettelon. Jos käytät myös tekoälyagentin ominaisuuksia, saman sivun agentin tunnus syötetään chat-päätepisteeseen. Tuotteen puhepuolesta kerrotaan oppaassa Tekoälyagentin käyttöönotto Callissa.
Usein kysytyt kysymykset
Miten saan API-avaimen?
Avaimet myöntää työtilasi alustan ylläpitäjä; niitä ei voi luoda sovelluksessa. Pyydä avain ja kerro, mitä oikeusalueita se tarvitsee. Koko avain näytetään kerran myöntämishetkellä.
Mitä 429-vastaus tarkoittaa?
Avain on käyttänyt kuluvan minuutin pyyntönsä. Odota X-RateLimit-Reset-otsakkeen ilmoittama määrä sekunteja, yritä sitten uudelleen ja levitä massatyö pidemmälle ajanjaksolle.
Miten tarkistan, että webhook todella tuli Callista?
Laske aikaleimasta ja rungosta HMAC-SHA256-tiiviste allekirjoitusavaimellasi ja vertaa sitä allekirjoitusotsakkeeseen. API-viite näyttää esimerkit Node.js:llä ja Pythonilla.
Voinko lähettää webhookeja paikalliselle kehityspalvelimelle?
Ei suoraan. Päätepisteiden on oltava julkisia https-osoitteita, joten käytä tunnelointityökalua, joka tuo paikallisen palvelimesi näkyviin sellaisen kautta.
Miksi API-kutsuni puhelun soittamiseksi torjuttiin?
API:n kautta soitetut puhelut käyvät läpi saman vaatimustenmukaisuustarkistuksen kuin työpisteeltä soitetut. Kieltolistalla oleva tai soittoaikojen ulkopuolella oleva numero torjutaan.
Kuka voi nähdä ja muuttaa webhookeja?
Kaikki voivat lukea luettelon, mutta vain omistajat, ylläpitäjät ja esihenkilöt voivat lisätä, testata tai poistaa päätepisteitä.