Callin käyttö

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.

Call-toimitus · Julkaistu · Lukuaika 4 min

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.

Kehittäjä käy läpi integraatiota kannettavalla tietokoneella pöytäpuhelimen vieressä
Havainnekuva

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.

OikeusalueMitä se sallii
readYhteystietojen, puhelujen, jonojen, tiimin jäsenten, raporttien ja kieltolistan lukeminen.
writeYhteystietojen luominen ja päivittäminen, puhelujen lopputulosten kirjaaminen, numeroiden lisääminen kieltolistalle.
callsPuhelujen soittaminen ja lopettaminen.
adminWebhookien 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.

Epäonnistuneen pyynnön käsittely

  1. Lue tilaOnko kyse asiakasvirheestä, jonka voit korjata, vai palvelinvirheestä, jota kannattaa yrittää uudelleen?
  2. Lue koodiHaaraudu koodin, älä koskaan viestitekstin perusteella.
  3. Pidä tauko429:n kohdalla odota nollausotsakkeen mukaan; palvelinvirheissä yritä muutaman kerran kasvavin viivein.
  4. Kirjaa yksityiskohdatSäilytä päätepiste, koodi ja aika, jotta tuki voi jäljittää tapahtuman.
  5. 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
AllekirjoitusTarkistetaan jokaisessa pyynnössäLuotetaan tarkistamatta
Vastaus2xx sekunneissa, työ jonoon myöhemmäksiHidas käsittely ennen vastausta
KaksoiskappaleetSaman tapahtuman voi vastaanottaa turvallisesti kahdestiLuo kaksi tietuetta
EpäonnistumisetHälyttää, kun toimitukset epäonnistuvatHiljaa, 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ä.

Avaa Callin API-viite ja lisää webhook-päätepiste

Demokonsolissa voit kokeilla saapuvia puheluita simulaatiossa.

Aiheeseen liittyvät oppaat