Pangkalahatang-ideya ng API

Iisang kontrata ang sinusunod ng bawat REST endpoint ng RolChat: parehong base URL, parehong response envelope, parehong pagination, parehong hugis ng error. Aralin ito nang isang beses at pareho ang pagbasa sa bawat pamilya ng endpoint sa reference ng endpoint.

Base URL at versioning

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

Nasa path ang bersyon. Ang pagdaragdag ng mga opsyonal na field, bagong endpoint o bagong query parameter na may default ay hindi breaking change at hindi nagpapataas ng bersyon. Inilalabas ang mga breaking change bilang v2, at patuloy na gumagana ang mga deprecated na endpoint ng v1 nang hindi bababa sa anim na buwan matapos silang ianunsyo (tingnan ang Pag-deprecate).

Authentication

Paraan	Header	Ginagamit para sa
JWT bearer	Authorization: Bearer <access_token>	Mga interactive na session (ang web app, mga mobile app)
API key	Authorization: Bearer rcp_<secret>	Mga tawag na machine-to-machine, mga plugin API key
HMAC signature	X-RolChat-Signature: sha256=…	Mga papasok na webhook mula sa mga system mo, tingnan ang Mga webhook
Wala	-	Mga pampublikong endpoint ng widget (/widget/…, /forms/…), naka-scope sa site at origin

Para sa mga integrasyon, gumamit ng API key (personal access token). Ginagawa ang mga key sa Mga Setting → Mga Plugin → Mga API key ng RolChat, isang beses lang ipinapakita at iniimbak bilang hash lang. Hindi kailanman makakagawa ang key nang higit sa miyembrong gumawa nito: sinusuri ang mga scope nito laban sa kasalukuyang mga pahintulot ng miyembrong iyon sa bawat tawag. Tingnan ang Authentication para sa tagal ng bisa ng JWT, ang header na X-Account-Id at mga session na may maraming kumpanya.

Envelope ng sagot

Iisang resource:

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

Isang listahan:

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

Dala pa rin ng mga sagot na walang body (204 No Content pagkatapos ng delete) ang header na X-Request-Id.

Isang error:

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

Ang code ay machine-readable na snake_case at ito ang value na pagbabatayan ng branch; English ang message at para sa mga log ito. Naroroon ang field at details kapag nakakatulong ang mga ito at hindi kailanman naglalaman ng personal na data. Hindi kailanman sumasagot ang API ng 200 na may array na errors: kung may mga error, 400 o mas mataas ang status. Nasa pahinang Mga error ang buong listahan ng code.

Pagination

Gumagamit ng cursor pagination ang mga list endpoint na puwedeng lumaki. Hingin ang unang pahina nang walang cursor, tapos ibalik nang eksakto ang next_cursor na natanggap mo:

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

• 50 ang default ng limit at 200 ang maximum; tinatanggihan ang mas malalaking value nang may 400 validation_failed.
• Opaque ang mga cursor at nag-e-expire pagkatapos ng 24 oras (400 validation_failed na may code: cursor_expired).
• Consistent ang mga resulta laban sa snapshot na kinuha sa unang pahina: nawawala ang mga record na nabura sa pagitan ng mga pahina, at lumalabas lang ang mga bagong record kapag nagsimula ka ulit nang walang cursor.
• Ipinapadala rin ang header na Link na may rel="next" at rel="prev" para sa mga client na mas gusto ito.

Idempotency

Magpadala ng header na Idempotency-Key (UUID o ULID, hanggang 255 character) kasama ng anumang POST, PATCH o DELETE:

• Tumatakbo ang unang request na may key at iniimbak ang status at body nito nang 24 oras.
• Ang pag-ulit na may parehong key at parehong body ay nagbabalik ng naka-imbak na sagot nang hindi muling pinapatakbo ang mga side effect.
• Ang pag-ulit na may parehong key pero ibang body ay tinatanggihan nang may 409 idempotency_key_conflict.

Gamitin ito sa bawat tawag na lumilikha ng isang bagay na may side effect: pagpapadala ng mensahe, e-mail o SMS, pagtawag, anumang may singil. Laging idempotent ang mga request na GET at binabalewala ng mga ito ang header.

Mga rate limit

Binibilang ang mga limitasyon kada minuto at nakabatay sa account, sa API key o sa user (sa IP address sa mga ruta na hindi nangangailangan ng sign-in). Ang mga default na limitasyon:

Bucket	Default na limitasyon	Kada minuto
Mga request nang walang sign-in (ayon sa IP)	60	kada IP
Naka-sign in na user (dashboard)	1 000	kada user
API key	1 000	kada key
Mga pampublikong endpoint ng widget	60 kada bisita, at 600 kada network address	kada minuto
Pag-sign in (/auth/login)	5	kada IP
Mga papasok na webhook	300	kada minuto
MCP server	600	kada minuto
Mga OAuth endpoint	600	kada minuto

Mga default ng platform ang mga limitasyong ito at puwedeng baguhin ng operator; hindi ito pinararami ng plan mo, at napagkakasunduan sa kontrata mo ang mga limitasyon ng Enterprise. Nagbabalik ang mga endpoint na may rate limit ng:

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

Kapag lumampas ka sa limitasyon, 429 ang sagot na may code: rate_limited sa errors array at header na Retry-After sa segundo. Maghintay nang ganoon katagal bago ang susunod na tawag. Sampung bigong pag-sign in ang nagla-lock sa account nang 30 minuto.

Mga laki at timeout

Kategorya	Max na laki ng request body	Timeout ng server
Default	1 MB	30 s
Mensaheng may mga attachment	25 MB	30 s
CSV import	50 MB	nagbabalik ng 202 at tumatakbo sa background
Mga larawan sa base ng kaalaman	10 MB	30 s
Bulk API	10 MB	30 s
Paghahanap	1 MB	10 s
Mga AI request	1 MB	60 s
Mga endpoint ng widget	100 KB	30 s

Nakakakuha ng 413 payload_too_large ang sobrang laking body. Ang upstream na nag-time out ay sumasagot ng 504 na may code: upstream_timeout at pahiwatig na retry_after kapag makakatulong ang retry.

Mga content type, petsa at ID

• application/json; charset=utf-8 ang mga request at sagot. Gumagamit ng multipart/form-data ang pag-upload ng file; nagbabalik ng text/csv ang mga CSV export. Tinatanggihan ang hindi valid na UTF-8 nang may 400 validation_failed.
• ISO-8601 sa UTC ang mga timestamp na may katumpakang millisecond: 2026-04-20T14:23:45.123Z. Tinatanggap sa input ang anumang ISO-8601 offset at ginagawang UTC.
• Mga opaque na ULID o UUID ang mga identifier. Walang numeric na ID, at hindi kailanman lumalabas sa URL ang mga e-mail address o numero ng telepono.

Paghihiwalay ng tenant at mga pahintulot

Tumatakbo ang bawat authenticated na request sa loob ng iisang account. Ang resource na kabilang sa ibang account, o sa site na hindi saklaw ng role ng tumatawag, ay sumasagot ng 404 not_found sa halip na 403, para hindi kailanman maibunyag ang pag-iral ng mga record. Ang valid na token na walang kinakailangang pahintulot (halimbawa contacts.delete) ay sumasagot ng 403 forbidden. May scope suffix ang ilang pahintulot (conversations.read:own, :team, :all) na nagpapaliit sa ibinabalik ng isang listahan.

Tumatanggap lang ang PATCH ng mga field na puwedeng isulat. Read-only ang id, account_id, created_at, updated_at at mga state field gaya ng resolved_at; ang pagpapadala ng isa sa mga ito ay nagbabalik ng 400 validation_failed na may details.forbidden_fields. Dumadaan ang mga pagbabago sa state sa mga nakalaang aksyon gaya ng POST /tickets/:id/resolve.

Nire-record sa audit log ng account ang bawat write.

Mga header para sa observability

Dala ng bawat sagot ang:

X-Request-Id: req_01HK…

I-log ang X-Request-Id. Ito ang unang hinihingi ng suporta.

CORS

https://app.rolchat.com ang origin ng dashboard sa browser. Pinapayagan ng mga pampublikong endpoint ng widget ang anumang origin, o ang mga origin lang na na-verify mo para sa isang site. Hindi saklaw ng CORS ang mga tawag na server-to-server gamit ang API key.

Pag-deprecate

1. Ina-anunsyo ang pagbabago sa talaan ng mga pagbabago at nagsisimulang magpadala ang apektadong endpoint ng Deprecation: true at header na Sunset na may petsa ng pag-alis.
2. Patuloy na gumagana ang mga pampublikong endpoint nang hindi bababa sa anim na buwan matapos ang anunsyo.
3. Sa bagong major version lang nangyayari ang pag-alis. Sa loob ng v1, additive ang mga pagbabago.

Kalusugan

Inilalantad ng bawat serbisyo ang /healthz (liveness) at /readyz (readiness).