API-oorsig

Elke RolChat REST-eindpunt volg een kontrak: dieselfde basis-URL, dieselfde antwoordomslag, dieselfde paginering, dieselfde foutvorm. Leer dit een keer en elke eindpuntfamilie in die eindpuntverwysing lees op dieselfde manier.

Basis-URL en weergawes

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

Die weergawe is in die pad. Die byvoeging van opsionele velde, nuwe eindpunte of nuwe navraagparameters met verstekwaardes is nie ’n brekende verandering nie en verhoog nie die weergawe nie. Brekende veranderinge word as v2 vrygestel, en uitgefaseerde v1-eindpunte bly vir ten minste ses maande ná die aankondiging werk (sien Uitfasering).

Verifikasie

Metode	Opskrif	Gebruik vir
JWT-draer	Authorization: Bearer <access_token>	Interaktiewe sessies (die webprogram, mobiele programme)
API-sleutel	Authorization: Bearer rcp_<secret>	Masjien-tot-masjien-oproepe, inprop-API-sleutels
HMAC-handtekening	X-RolChat-Signature: sha256=…	Inkomende webhooks van jou stelsels, sien Webhooks
Geen	-	Publieke widget-eindpunte (/widget/…, /forms/…), afgebaken volgens webwerf en oorsprong

Gebruik vir integrasies ’n API-sleutel (’n persoonlike toegangstoken). Sleutels word geskep in Instellings → Inproppe → RolChat API-sleutels, een keer gewys en slegs as ’n hash gestoor. ’n Sleutel kan nooit meer doen as die lid wat dit geskep het nie: sy omvange word by elke oproep teen daardie lid se huidige toestemmings nagegaan. Sien Verifikasie vir JWT-leeftye, die X-Account-Id-opskrif en sessies oor verskeie maatskappye.

Antwoordomslag

’n Enkele hulpbron:

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

’n Lys:

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

Antwoorde sonder ’n liggaam (204 No Content ná ’n skrapping) dra steeds die X-Request-Id-opskrif.

’n Fout:

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

code is masjienleesbare snake_case en is die waarde om op te vertak; message is in Engels en bedoel vir logs. field en details is teenwoordig wanneer hulle help en bevat nooit persoonlike data nie. Die API antwoord nooit 200 met ’n errors-skikking nie: as daar foute is, is die status 400 of hoër. Die volledige kodelys is op die bladsy Foute.

Paginering

Lys-eindpunte wat kan groei, gebruik wyserpaginering. Vra vir die eerste bladsy sonder ’n wyser, en gee dan die next_cursor wat jy ontvang het, woordeliks terug:

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

• limit is by verstek 50 en word by 200 beperk; groter waardes word met 400 validation_failed verwerp.
• Wysers is ondeursigtig en verval ná 24 uur (400 validation_failed met code: cursor_expired).
• Resultate is konsekwent teen die momentopname wat by die eerste bladsy geneem is: rekords wat tussen bladsye geskrap word, verdwyn, en nuwe rekords verskyn eers wanneer jy weer sonder ’n wyser begin.
• ’n Link-opskrif met rel="next" en rel="prev" word ook gestuur vir kliënte wat dit verkies.

Idempotensie

Stuur ’n Idempotency-Key-opskrif (’n UUID of ULID, tot 255 karakters) saam met enige POST, PATCH of DELETE:

• Die eerste versoek met ’n sleutel loop, en sy status en liggaam word vir 24 uur gestoor.
• ’n Herhaling met dieselfde sleutel en dieselfde liggaam gee die gestoorde antwoord terug sonder om newe-effekte weer uit te voer.
• ’n Herhaling met dieselfde sleutel maar ’n ander liggaam word met 409 idempotency_key_conflict verwerp.

Gebruik dit vir elke oproep wat iets met newe-effekte skep: die stuur van ’n boodskap, ’n e-pos of ’n SMS, die maak van ’n oproep, enigiets wat gefaktureer word. GET-versoeke is altyd idempotent en ignoreer die opskrif.

Tempolimiete

Limiete word per minuut getel en volgens die rekening, die API-sleutel of die gebruiker bepaal (volgens IP-adres op roetes wat nie aanmelding vereis nie). Die verstekplafonne:

Emmer	Verstek-limiet	Per minuut
Versoeke sonder aanmelding (volgens IP)	60	per IP
Aangemelde gebruiker (kontroleskerm)	1 000	per gebruiker
API-sleutel	1 000	per sleutel
Publieke widget-eindpunte	60 per besoeker, en 600 per netwerkadres	per minuut
Aanmelding (/auth/login)	5	per IP
Inkomende webhooks	300	per minuut
MCP-bediener	600	per minuut
OAuth-eindpunte	600	per minuut

Die plafonne is die platformverstekke en kan deur die operateur verander word; jou plan vermenigvuldig hulle nie, en ondernemingslimiete word in jou kontrak ooreengekom. Eindpunte met tempolimiete gee terug:

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

Wanneer jy ’n limiet oorskry, is die antwoord 429 met code: rate_limited in die errors-skikking en ’n Retry-After-opskrif in sekondes. Wag soveel tyd voor die volgende oproep. Tien mislukte aanmeldings sluit die rekening vir 30 minute.

Groottes en uittellings

Kategorie	Maks. versoekliggaam	Bediener-uittelling
Verstek	1 MB	30 s
Boodskap met aanhegsels	25 MB	30 s
CSV-invoer	50 MB	gee 202 terug en loop in die agtergrond
Kennisbasis-beelde	10 MB	30 s
Grootmaat-API	10 MB	30 s
Soektog	1 MB	10 s
KI-versoeke	1 MB	60 s
Widget-eindpunte	100 KB	30 s

Te groot liggame kry 413 payload_too_large. ’n Stroomop-diens wat uittel, antwoord 504 met code: upstream_timeout en ’n retry_after-wenk wanneer ’n herprobeer kan help.

Inhoudtipes, datums en ID’s

• Versoeke en antwoorde is application/json; charset=utf-8. Lêeroplaaie gebruik multipart/form-data; CSV-uitvoere gee text/csv terug. Ongeldige UTF-8 word met 400 validation_failed verwerp.
• Tydstempels is ISO-8601 in UTC met millisekonde-presisie: 2026-04-20T14:23:45.123Z. Enige ISO-8601-afwyking word by invoer aanvaar en na UTC genormaliseer.
• Identifiseerders is ondeursigtige ULID’s of UUID’s. Daar is geen numeriese ID’s nie, en e-posadresse of foonnommers verskyn nooit in ’n URL nie.

Huurderisolasie en toestemmings

Elke geverifieerde versoek loop binne een rekening. ’n Hulpbron wat aan ’n ander rekening behoort, of aan ’n webwerf wat die roeper se rol nie dek nie, antwoord 404 not_found eerder as 403, sodat die bestaan van rekords nooit uitlek nie. ’n Geldige token sonder die vereiste toestemming (byvoorbeeld contacts.delete) antwoord 403 forbidden. Sommige toestemmings dra ’n omvangagtervoegsel (conversations.read:own, :team, :all) wat beperk wat ’n lys teruggee.

PATCH aanvaar slegs skryfbare velde. id, account_id, created_at, updated_at en toestandvelde soos resolved_at is slegs-lees; as jy een stuur, kry jy 400 validation_failed met details.forbidden_fields. Toestandveranderinge gaan deur toegewyde aksies soos POST /tickets/:id/resolve.

Elke skryfbewerking word in die rekening se ouditlog aangeteken.

Waarneembaarheidsopskrifte

Elke antwoord dra:

X-Request-Id: req_01HK…

Teken X-Request-Id aan. Dit is die eerste ding waarvoor ondersteuning vra.

CORS

Die blaaier-kontroleskerm se oorsprong is https://app.rolchat.com. Publieke widget-eindpunte laat enige oorsprong toe, of slegs die oorspronge wat jy vir ’n webwerf verifieer. Bediener-tot-bediener-oproepe met ’n API-sleutel is nie aan CORS onderhewig nie.

Uitfasering

1. Die verandering word in die veranderingslog aangekondig, en die betrokke eindpunt begin Deprecation: true en ’n Sunset-opskrif met die verwyderingsdatum stuur.
2. Publieke eindpunte bly vir ten minste ses maande ná die aankondiging werk.
3. Verwydering gebeur slegs in ’n nuwe hoofweergawe. Binne v1 is veranderinge slegs toevoegings.

Gesondheid

Elke diens stel /healthz (lewendigheid) en /readyz (gereedheid) beskikbaar.