API-yleiskatsaus

Jokainen RolChatin REST-päätepiste noudattaa yhtä sopimusta: sama perus-URL, sama vastauksen kirjekuori, sama sivutus, sama virheen muoto. Opettele se kerran, niin jokainen päätepisteviitteen päätepisteperhe toimii samalla tavalla.

Perus-URL ja versiointi

https://api.rolchat.com/api/v1/

Versio on polussa. Valinnaisten kenttien, uusien päätepisteiden tai oletusarvoisten uusien kyselyparametrien lisääminen ei ole rikkova muutos eikä nosta versiota. Rikkovat muutokset julkaistaan versiona v2, ja käytöstä poistettavat v1-päätepisteet toimivat vähintään kuusi kuukautta ilmoituksen jälkeen (katso Käytöstä poistaminen).

Todennus

Menetelmä	Otsake	Käyttötarkoitus
JWT bearer	`Authorization: Bearer <access_token>`	Interaktiiviset istunnot (verkkosovellus, mobiilisovellukset)
API-avain	`Authorization: Bearer rcp_<secret>`	Koneelta koneelle -kutsut, laajennusten API-avaimet
HMAC-allekirjoitus	`X-RolChat-Signature: sha256=…`	Saapuvat webhookit järjestelmistäsi, katso Webhookit
Ei mitään	-	Julkiset widget-päätepisteet (`/widget/…`, `/forms/…`), rajattu sivuston ja alkuperän mukaan

Käytä integraatioissa API-avainta (henkilökohtainen käyttötunniste). Avaimet luodaan kohdassa Asetukset → Laajennukset → RolChat API -avaimet, ne näytetään kerran ja tallennetaan vain tiivisteenä. Avain ei voi koskaan tehdä enempää kuin sen luonut jäsen: sen oikeusalueet tarkistetaan jokaisessa kutsussa kyseisen jäsenen nykyisiä oikeuksia vasten. Katso Todennus JWT-tunnisteiden kestoista, X-Account-Id-otsakkeesta ja usean yrityksen istunnoista.

Vastauksen kirjekuori

Yksittäinen resurssi:

{
  "data": { "id": "cnt_01HK…", "email": "ada@example.com" },
  "meta": {
    "request_id": "req_01HK…"
  }
}

Luettelo:

{
  "data": [ { … }, { … } ],
  "meta": {
    "request_id": "req_01HK…",
    "count": 50,
    "next_cursor": "cur_01HK…",
    "prev_cursor": "cur_01HK…",
    "has_more": true
  }
}

Vastaukset ilman runkoa (204 No Content poiston jälkeen) sisältävät silti otsakkeen X-Request-Id.

Virhe:

{
  "errors": [
    {
      "code": "validation_failed",
      "message": "Email must be valid.",
      "field": "email",
      "details": { "received": "not-an-email" }
    }
  ],
  "meta": { "request_id": "req_01HK…" }
}

code on koneluettava snake_case-arvo, ja sen perusteella kannattaa haarautua; message on englanniksi ja tarkoitettu lokeihin. field ja details ovat mukana, kun niistä on apua, eivätkä ne koskaan sisällä henkilötietoja. API ei koskaan vastaa 200 ja errors-taulukko: jos virheitä on, tilakoodi on 400 tai suurempi. Koko koodiluettelo on sivulla Virheet.

Sivutus

Luettelopäätepisteet, jotka voivat kasvaa, käyttävät kursorisivutusta. Pyydä ensimmäinen sivu ilman kursoria ja välitä sitten saamasi next_cursor takaisin sellaisenaan:

GET /api/v1/contacts?limit=50
GET /api/v1/contacts?limit=50&cursor=eyJrIjoi…

limit on oletuksena 50 ja enintään 200; suuremmat arvot hylätään virheellä 400 validation_failed.
Kursorit ovat läpinäkymättömiä ja vanhenevat 24 tunnin jälkeen (400 validation_failed, jossa code: cursor_expired).
Tulokset ovat johdonmukaisia ensimmäisellä sivulla otettuun tilannekuvaan nähden: sivujen välillä poistetut tietueet katoavat, uudet tietueet näkyvät vasta, kun aloitat alusta ilman kursoria.
Lisäksi lähetetään Link-otsake arvoilla rel="next" ja rel="prev" asiakkaille, jotka suosivat sitä.

Idempotenssi

Lähetä Idempotency-Key-otsake (UUID tai ULID, enintään 255 merkkiä) minkä tahansa POST-, PATCH- tai DELETE-pyynnön mukana:

Ensimmäinen pyyntö avaimella suoritetaan, ja sen tilakoodi ja runko tallennetaan 24 tunniksi.
Toisto samalla avaimella ja samalla rungolla palauttaa tallennetun vastauksen suorittamatta sivuvaikutuksia uudelleen.
Toisto samalla avaimella mutta eri rungolla hylätään virheellä 409 idempotency_key_conflict.

Käytä sitä jokaisessa kutsussa, joka luo jotain sivuvaikutuksineen: viestin, sähköpostin tai tekstiviestin lähettäminen, puhelun soittaminen, kaikki laskutettava. GET-pyynnöt ovat aina idempotentteja ja ohittavat otsakkeen.

Nopeusrajat

Rajat lasketaan minuutin ajalta, ja ne kohdistuvat tiliin, API-avaimeen tai käyttäjään (IP-osoitteeseen reiteillä, jotka eivät vaadi kirjautumista). Oletusrajat:

Ämpäri	Oletusraja	Minuutissa
Pyynnöt ilman kirjautumista (IP:n mukaan)	60	IP:tä kohti
Kirjautunut käyttäjä (hallintapaneeli)	1 000	käyttäjää kohti
API-avain	1 000	avainta kohti
Julkiset widgetin päätepisteet	60 kävijää kohti ja 600 verkko-osoitetta kohti	minuutissa
Kirjautuminen (`/auth/login`)	5	IP:tä kohti
Saapuvat webhookit	300	minuutissa
MCP-palvelin	600	minuutissa
OAuth-päätepisteet	600	minuutissa

Rajat ovat alustan oletusarvoja, ja ylläpitäjä voi muuttaa niitä; pakettisi ei kerro niitä, ja Enterprise-rajoista sovitaan sopimuksessa. Nopeusrajoitetut päätepisteet palauttavat:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 543

Kun ylität rajan, vastaus on 429, jossa on code: rate_limited errors-taulukossa ja Retry-After-otsake sekunteina. Odota tämä aika ennen seuraavaa kutsua. Kymmenen epäonnistunutta kirjautumista lukitsee tilin 30 minuutiksi.

Koot ja aikakatkaisut

Kategoria	Pyynnön rungon enimmäiskoko	Palvelimen aikakatkaisu
Oletus	1 Mt	30 s
Viesti liitteineen	25 Mt	30 s
CSV-tuonti	50 Mt	palauttaa `202` ja suoritetaan taustalla
Tietopankin kuvat	10 Mt	30 s
Bulk-API	10 Mt	30 s
Haku	1 Mt	10 s
AI-pyynnöt	1 Mt	60 s
Widget-päätepisteet	100 kt	30 s

Liian suuret rungot saavat vastauksen 413 payload_too_large. Aikakatkaistu taustapalvelu vastaa 504 koodilla code: upstream_timeout ja retry_after-vihjeellä, kun uusintayrityksestä voi olla apua.

Sisältötyypit, päivämäärät ja tunnisteet

Pyynnöt ja vastaukset ovat application/json; charset=utf-8. Tiedostojen lataukset käyttävät multipart/form-data; CSV-viennit palauttavat text/csv. Virheellinen UTF-8 hylätään virheellä 400 validation_failed.
Aikaleimat ovat ISO-8601-muodossa UTC-ajassa millisekunnin tarkkuudella: 2026-04-20T14:23:45.123Z. Syötteessä hyväksytään mikä tahansa ISO-8601-poikkeama, ja se normalisoidaan UTC-aikaan.
Tunnisteet ovat läpinäkymättömiä ULID- tai UUID-arvoja. Numeerisia tunnisteita ei ole, eivätkä sähköpostiosoitteet tai puhelinnumerot koskaan näy URL-osoitteessa.

Vuokralaisten eristys ja oikeudet

Jokainen todennettu pyyntö suoritetaan yhden tilin sisällä. Resurssi, joka kuuluu toiselle tilille tai sivustolle, jota kutsujan rooli ei kata, vastaa 404 not_found eikä 403, jotta tietueiden olemassaolo ei koskaan paljastu. Kelvollinen tunniste ilman vaadittua oikeutta (esimerkiksi contacts.delete) vastaa 403 forbidden. Joillakin oikeuksilla on laajuusliite (conversations.read:own, :team, :all), joka rajaa sitä, mitä luettelo palauttaa.

PATCH hyväksyy vain kirjoitettavat kentät. id, account_id, created_at, updated_at ja tilakentät, kuten resolved_at, ovat vain luku -kenttiä; sellaisen lähettäminen palauttaa 400 validation_failed ja details.forbidden_fields. Tilamuutokset tehdään erillisillä toiminnoilla, kuten POST /tickets/:id/resolve.

Jokainen kirjoitus tallennetaan tilin tarkastuslokiin.

Havainnoitavuusotsakkeet

Jokainen vastaus sisältää:

X-Request-Id: req_01HK…

Kirjaa X-Request-Id lokiin. Tuki kysyy sitä ensimmäisenä.

CORS

Selaimen hallintapaneelin alkuperä on https://app.rolchat.com. Julkiset widget-päätepisteet sallivat minkä tahansa alkuperän tai vain sivustolle vahvistamasi alkuperät. API-avaimella tehdyt palvelimelta palvelimelle -kutsut eivät ole CORS-rajoitusten alaisia.

Käytöstä poistaminen

Muutoksesta ilmoitetaan muutoslokissa, ja asianomainen päätepiste alkaa lähettää otsakkeen Deprecation: true sekä Sunset-otsakkeen poistopäivämäärineen.
Julkiset päätepisteet toimivat vähintään kuusi kuukautta ilmoituksen jälkeen.
Poisto tapahtuu vain uudessa pääversiossa. v1:n sisällä muutokset ovat lisääviä.

Kunto

Jokainen palvelu tarjoaa päätepisteet /healthz (elossaolo) ja /readyz (valmius).