इसे छोड़कर कंटेंट पर जाएं

API अवलोकन

हर RolChat REST एंडपॉइंट एक ही अनुबंध का पालन करता है: वही बेस URL, वही रिस्पॉन्स एनवेलप, वही पेजिनेशन, वही त्रुटि संरचना। इसे एक बार सीख लें, और एंडपॉइंट संदर्भ की हर एंडपॉइंट फ़ैमिली उसी तरह पढ़ी जाती है।

बेस URL और संस्करण

Section titled “बेस URL और संस्करण”
https://api.rolchat.com/api/v1/

संस्करण पथ में है। वैकल्पिक फ़ील्ड, नए एंडपॉइंट या डिफ़ॉल्ट मान वाले नए क्वेरी पैरामीटर जोड़ना तोड़ने वाला बदलाव नहीं है और इससे संस्करण नहीं बढ़ता। तोड़ने वाले बदलाव v2 के रूप में आते हैं, और डेप्रिकेट किए गए v1 एंडपॉइंट घोषणा के बाद कम से कम छह महीने तक काम करते रहते हैं (डेप्रिकेशन देखें)।

प्रमाणीकरण

Section titled “प्रमाणीकरण”
तरीका हेडर किसके लिए
JWT bearer Authorization: Bearer <access_token> इंटरैक्टिव सेशन (वेब ऐप, मोबाइल ऐप)
API कुंजी Authorization: Bearer rcp_<secret> मशीन-से-मशीन कॉल, प्लगइन API कुंजियाँ
HMAC हस्ताक्षर X-RolChat-Signature: sha256=… आपके सिस्टम से आने वाले वेबहुक, वेबहुक देखें
कोई नहीं - सार्वजनिक विजेट एंडपॉइंट (/widget/…, /forms/…), साइट और ओरिजिन के दायरे में

इंटीग्रेशन के लिए API कुंजी (व्यक्तिगत एक्सेस टोकन) इस्तेमाल करें। कुंजियाँ सेटिंग्स → प्लगइन → RolChat API कुंजियाँ में बनती हैं, एक बार दिखाई जाती हैं और केवल हैश के रूप में संग्रहीत होती हैं। कुंजी कभी उसे बनाने वाले सदस्य से ज़्यादा नहीं कर सकती: हर कॉल पर उसके स्कोप उस सदस्य की मौजूदा अनुमतियों से जाँचे जाते हैं। JWT की अवधि, X-Account-Id हेडर और कई कंपनियों वाले सेशन के लिए प्रमाणीकरण देखें।

रिस्पॉन्स एनवेलप

Section titled “रिस्पॉन्स एनवेलप”

एक संसाधन:

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

एक सूची:

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

बिना बॉडी वाले जवाब (हटाने के बाद 204 No Content) में भी X-Request-Id हेडर होता है।

एक त्रुटि:

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

code मशीन-पठनीय snake_case है और यही वह मान है जिस पर ब्रांच करना है; message अंग्रेज़ी में है और लॉग के लिए है। field और details तब होते हैं जब वे मददगार हों और उनमें कभी व्यक्तिगत डेटा नहीं होता। API कभी errors ऐरे के साथ 200 नहीं लौटाता: त्रुटियाँ होने पर स्टेटस 400 या उससे ऊपर होता है। पूरी कोड सूची त्रुटियाँ पेज पर है।

पेजिनेशन

Section titled “पेजिनेशन”

जो सूची एंडपॉइंट बढ़ सकते हैं वे कर्सर पेजिनेशन इस्तेमाल करते हैं। पहला पेज बिना कर्सर के माँगें, फिर मिला हुआ next_cursor ज्यों का त्यों वापस भेजें:

GET /api/v1/contacts?limit=50
GET /api/v1/contacts?limit=50&cursor=eyJrIjoi…
  • limit डिफ़ॉल्ट रूप से 50 है और अधिकतम 200; बड़े मान 400 validation_failed के साथ अस्वीकार होते हैं।
  • कर्सर अपारदर्शी हैं और 24 घंटे बाद समाप्त होते हैं (code: cursor_expired के साथ 400 validation_failed)।
  • परिणाम पहले पेज पर लिए गए स्नैपशॉट के अनुरूप रहते हैं: पेजों के बीच हटाए गए रिकॉर्ड गायब हो जाते हैं, नए रिकॉर्ड तभी दिखते हैं जब आप बिना कर्सर के फिर शुरू करते हैं।
  • जो क्लाइंट पसंद करते हैं उनके लिए rel="next" और rel="prev" वाला Link हेडर भी भेजा जाता है।

आइडेम्पोटेंसी

Section titled “आइडेम्पोटेंसी”

किसी भी POST, PATCH या DELETE के साथ Idempotency-Key हेडर (UUID या ULID, 255 अक्षरों तक) भेजें:

  • किसी कुंजी वाला पहला अनुरोध चलता है और उसका स्टेटस और बॉडी 24 घंटे के लिए संग्रहीत होते हैं।
  • उसी कुंजी और उसी बॉडी के साथ दोहराव साइड इफ़ेक्ट दोबारा चलाए बिना संग्रहीत जवाब लौटाता है।
  • उसी कुंजी लेकिन अलग बॉडी के साथ दोहराव 409 idempotency_key_conflict के साथ अस्वीकार होता है।

इसे हर उस कॉल के लिए इस्तेमाल करें जो साइड इफ़ेक्ट वाली कोई चीज़ बनाती है: संदेश, ईमेल या SMS भेजना, कॉल करना, कुछ भी जिस पर बिल बनता है। GET अनुरोध हमेशा आइडेम्पोटेंट होते हैं और हेडर को अनदेखा करते हैं।

दर सीमाएँ

Section titled “दर सीमाएँ”

सीमाएँ प्रति मिनट गिनी जाती हैं और खाते, API कुंजी या उपयोगकर्ता से जुड़ी होती हैं (जिन रूट पर साइन-इन नहीं चाहिए वहाँ IP पते से)। डिफ़ॉल्ट सीमाएँ:

बकेट डिफ़ॉल्ट सीमा प्रति मिनट
साइन-इन के बिना अनुरोध (IP से) 60 प्रति IP
साइन-इन उपयोगकर्ता (डैशबोर्ड) 1 000 प्रति उपयोगकर्ता
API कुंजी 1 000 प्रति कुंजी
सार्वजनिक विजेट एंडपॉइंट प्रति विज़िटर 60, और प्रति नेटवर्क पता 600 प्रति मिनट
साइन-इन (/auth/login) 5 प्रति IP
इनबाउंड वेबहुक 300 प्रति मिनट
MCP सर्वर 600 प्रति मिनट
OAuth एंडपॉइंट 600 प्रति मिनट

ये सीमाएँ प्लेटफ़ॉर्म की डिफ़ॉल्ट हैं और ऑपरेटर इन्हें बदल सकता है; आपका प्लान इन्हें गुणा नहीं करता, और Enterprise सीमाएँ आपके अनुबंध में तय होती हैं। दर-सीमित एंडपॉइंट लौटाते हैं:

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

सीमा पार होने पर जवाब 429 होता है, errors ऐरे में code: rate_limited और सेकंड में Retry-After हेडर के साथ। अगली कॉल से पहले उतनी देर प्रतीक्षा करें। दस असफल साइन-इन खाते को 30 मिनट के लिए लॉक कर देते हैं।

आकार और टाइमआउट

Section titled “आकार और टाइमआउट”
श्रेणी अधिकतम अनुरोध बॉडी सर्वर टाइमआउट
डिफ़ॉल्ट 1 MB 30 से
अटैचमेंट वाला संदेश 25 MB 30 से
CSV इंपोर्ट 50 MB 202 लौटाता है और बैकग्राउंड में चलता है
ज्ञान आधार इमेज 10 MB 30 से
Bulk API 10 MB 30 से
खोज 1 MB 10 से
AI अनुरोध 1 MB 60 से
विजेट एंडपॉइंट 100 KB 30 से

बहुत बड़ी बॉडी को 413 payload_too_large मिलता है। टाइमआउट होने वाली अपस्ट्रीम सेवा 504 के साथ code: upstream_timeout और, जब दोबारा कोशिश मदद कर सकती हो, retry_after संकेत लौटाती है।

कंटेंट टाइप, तारीखें और ID

Section titled “कंटेंट टाइप, तारीखें और ID”
  • अनुरोध और जवाब application/json; charset=utf-8 हैं। फ़ाइल अपलोड multipart/form-data इस्तेमाल करते हैं; CSV एक्सपोर्ट text/csv लौटाते हैं। अमान्य UTF-8 400 validation_failed के साथ अस्वीकार होता है।
  • टाइमस्टैम्प मिलीसेकंड सटीकता के साथ UTC में ISO-8601 हैं: 2026-04-20T14:23:45.123Z। इनपुट में कोई भी ISO-8601 ऑफ़सेट स्वीकार होता है और UTC में सामान्यीकृत होता है।
  • पहचानकर्ता अपारदर्शी ULID या UUID हैं। कोई संख्यात्मक ID नहीं है, और ईमेल पते या फ़ोन नंबर कभी URL में नहीं आते।

टेनेंट अलगाव और अनुमतियाँ

Section titled “टेनेंट अलगाव और अनुमतियाँ”

हर प्रमाणित अनुरोध एक खाते के भीतर चलता है। किसी दूसरे खाते का, या ऐसी साइट का संसाधन जो कॉल करने वाले की भूमिका में नहीं आती, 403 के बजाय 404 not_found लौटाता है, ताकि रिकॉर्ड का अस्तित्व कभी उजागर न हो। ज़रूरी अनुमति (उदाहरण के लिए contacts.delete) के बिना मान्य टोकन 403 forbidden लौटाता है। कुछ अनुमतियों में दायरे का प्रत्यय (conversations.read:own, :team, :all) होता है जो सूची के परिणाम को सीमित करता है।

PATCH केवल लिखने योग्य फ़ील्ड स्वीकार करता है। id, account_id, created_at, updated_at और resolved_at जैसे स्थिति फ़ील्ड केवल पढ़ने योग्य हैं; इनमें से कोई भेजने पर details.forbidden_fields के साथ 400 validation_failed मिलता है। स्थिति में बदलाव POST /tickets/:id/resolve जैसी समर्पित कार्रवाइयों से होते हैं।

हर लेखन खाते के ऑडिट लॉग में दर्ज होता है।

ऑब्ज़र्वेबिलिटी हेडर

Section titled “ऑब्ज़र्वेबिलिटी हेडर”

हर जवाब में होते हैं:

X-Request-Id: req_01HK…

X-Request-Id लॉग करें। सपोर्ट सबसे पहले यही माँगता है।

CORS

Section titled “CORS”

ब्राउज़र डैशबोर्ड का ओरिजिन https://app.rolchat.com है। सार्वजनिक विजेट एंडपॉइंट किसी भी ओरिजिन की अनुमति देते हैं, या केवल उन ओरिजिन की जिन्हें आप किसी साइट के लिए सत्यापित करते हैं। API कुंजी वाली सर्वर-से-सर्वर कॉल CORS के अधीन नहीं हैं।

डेप्रिकेशन

Section titled “डेप्रिकेशन”
  1. बदलाव की घोषणा बदलावों के लॉग में होती है और प्रभावित एंडपॉइंट Deprecation: true और हटाने की तारीख वाला Sunset हेडर भेजना शुरू करता है।
  2. सार्वजनिक एंडपॉइंट घोषणा के बाद कम से कम छह महीने तक काम करते रहते हैं।
  3. हटाना केवल नए मुख्य संस्करण में होता है। v1 के भीतर बदलाव केवल जोड़ने वाले होते हैं।

हेल्थ

Section titled “हेल्थ”

हर सेवा /healthz (लाइवनेस) और /readyz (रेडीनेस) उपलब्ध कराती है।