API-avaimet ja käyttöoikeudet

Ringhumin REST-rajapinnan avulla omat järjestelmäsi voivat toimia yhdessä työtilasi kanssa: listata puheluita ja transkriptioita, luoda assistentteja, varata aikoja, hallita yhteystietoja, soittaa lähteviä puheluita ja paljon muuta. Jokainen pyyntö tunnistetaan API-avaimella, joka kuuluu yhteen työtilaan. Tässä artikkelissa käsitellään avainten luomista ja sääntöjä, jotka koskevat jokaista rajapinnan päätepistettä. Täydellinen päätepisteiden viiteopas löytyy osoitteesta /docs.

Kuka voi hallita avaimia

Rajapinta on käytettävissä jokaisella paketilla. Se, mitä avaimella voi tehdä, riippuu silti paketistasi: esimerkiksi assistentin luominen paketin rajan yli palauttaa virheen.

Luo API-avain

1. Avaa sivupalkista Kehittäjät.
2. Napsauta API-avaimet-kortissa Luo avain.
3. Anna Avaimen nimi, joka kertoo missä avainta käytetään, esimerkiksi "Tuotantopalvelin".
4. Valitse Käyttöoikeudet-kohdassa read, write tai molemmat.
5. Napsauta Luo avain.
6. Kopioi avain vihreästä laatikosta ja säilytä se turvallisessa paikassa, kuten palvelimesi salaisuuksien hallinnassa. Napsauta Valmis.

Tärkeää: Avain näytetään vain kerran. Ringhum tallentaa siitä vain sormenjäljen, joten sitä ei voida näyttää uudelleen. Jos menetät sen, luo uusi avain ja mitätöi vanha.

Avaimet alkavat merkinnällä ck_live_. API-avaimet-taulukko näyttää kunkin avaimen nimen, avaimen ensimmäiset merkit, sen käyttöoikeudet, milloin sitä on viimeksi käytetty ja onko se Aktiivinen vai Mitätöity.

Käyttöoikeudet

Jokainen avain voi kutsua päätepisteitä, jotka vain lukevat. Päätepisteet, jotka luovat, muuttavat tai poistavat jotain, tarvitsevat write-käyttöoikeuden. Esimerkkejä ovat puhelun soittaminen, viestin lähettäminen, ajan varaaminen tai assistentin päivittäminen. Viiteopas osoitteessa /docs merkitsee nämä päätepisteet. Avain ilman write-oikeutta saa niistä 403-virheen.

Anna jokaiselle järjestelmälle pienin tarvittava käyttöoikeus. Raportointinäkymä tarvitsee vain read-oikeuden.

Mitätöi avain

1. Etsi avain Kehittäjät-sivun API-avaimet-taulukosta.
2. Napsauta Mitätöi ja vahvista.

Avainta käyttävät pyynnöt epäonnistuvat välittömästi virheellä 401. Mitätöidyt avaimet pysyvät listassa merkittynä Mitätöity, jotta näet niiden historian. Avainta ei voi muokata: jos haluat muuttaa sen käyttöoikeuksia, luo uusi avain ja mitätöi vanha.

Pyyntöjen tekeminen

• Perusosoite: https://ringhum.com/api/v1
• Tunnistautuminen: lähetä avain Bearer-tunnuksena: Authorization: Bearer ck_live_…
• Muoto: JSON sekä sisään että ulos. Lähetä Content-Type: application/json, kun pyynnössä on sisältö.
• Ajat ovat ISO 8601 -muodossa UTC-ajassa. Puhelinnumerot ovat E.164-muodossa, esimerkiksi +14155550132. Tunnisteet ovat kokonaislukuja.
• Päivitykset käyttävät PATCH-metodia ja sisältävät vain kentät, joita haluat muuttaa.
• Jokainen vastaus sisältää X-Request-Id-otsikon. Liitä se mukaan, kun otat yhteyttä tukeen.

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

Voit tarkistaa, mihin työtilaan avain kuuluu, kutsumalla GET /me.

Vastaukset ja sivutus

Yksittäinen objekti palautuu muodossa {"data": {…}}. Sivutetut listat palautuvat meta-objektin kanssa:

{
  "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
  }
}

Käytä page- ja per_page-parametreja tulosten selaamiseen. per_page on oletuksena 25 ja voi olla enintään 100.

Virheet

Jokaisella virheellä on sama muoto, jossa on vakaa type-kenttä, jota voit tarkistaa koodissasi:

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

Pyyntörajat

Voit tehdä 120 pyyntöä minuutissa. Vastaukset sisältävät X-RateLimit-Limit- ja X-RateLimit-Remaining-otsikot. Kun rajan ylittää, saat 429-virheen ja Retry-After-otsikon, joka kertoo odotettavat sekunnit.

Vinkki: Älä kysele puhelutuloksia toistuvasti. Lisää webhook tapahtumalle call.ended, niin Ringhum lähettää sinulle yhteenvedon ja transkription heti, kun puhelu on päättynyt. Katso Webhookit.

Yleisiä kysymyksiä

Onko olemassa koneluettavaa määrittelyä? Kyllä. OpenAPI 3.1 -kuvaus löytyy osoitteesta /api/v1/openapi.json, eikä se vaadi avainta. Voit luoda sen pohjalta asiakasohjelman.

Lakkaako avain toimimasta, jos sen luonut henkilö lähtee? Ei. Avaimet kuuluvat työtilalle ja toimivat, kunnes ne mitätöidään. Mitätöi avaimet, joihin et enää luota, erityisesti kun joku pääsyn omannut henkilö lähtee.

Voinko käyttää rajapintaa verkkosivulta? Et. Kuka tahansa sivun avaava voisi lukea avaimen. Kutsu rajapintaa palvelimeltasi.