API कुंजियां और स्कोप

Ringhum REST API आपके अपने सिस्टम को आपके वर्कस्पेस के साथ काम करने देता है: कॉल और ट्रांसक्रिप्ट की सूची बनाना, असिस्टेंट बनाना, अपॉइंटमेंट बुक करना, कॉन्टैक्ट मैनेज करना, आउटबाउंड कॉल करना और भी बहुत कुछ। हर रिक्वेस्ट एक API कुंजी से ऑथेंटिकेट होती है जो एक वर्कस्पेस से जुड़ी होती है। यह लेख कुंजियां बनाने और हर एंडपॉइंट में साझा नियमों को कवर करता है। पूरा एंडपॉइंट रेफरेंस /docs पर है।

कुंजियां कौन मैनेज कर सकता है

API हर प्लान पर उपलब्ध है। एक कुंजी क्या कर सकती है, यह फिर भी आपके प्लान से सीमित होता है: उदाहरण के लिए, आपके प्लान की सीमा से ज़्यादा असिस्टेंट बनाने पर एरर आती है।

एक API कुंजी बनाएं

1. साइडबार में डेवलपर्स खोलें।
2. API कुंजियां कार्ड में, कुंजी बनाएं पर क्लिक करें।
3. एक कुंजी का नाम डालें जो बताए कि कुंजी कहां इस्तेमाल होती है, उदाहरण के लिए "प्रोडक्शन सर्वर"।
4. स्कोप के तहत, read, write या दोनों पर टिक करें।
5. कुंजी बनाएं पर क्लिक करें।
6. हरे बॉक्स से कुंजी कॉपी करें और उसे किसी सुरक्षित जगह पर रखें, जैसे आपके सर्वर के सीक्रेट स्टोर में। Done पर क्लिक करें।

ज़रूरी: कुंजी सिर्फ़ एक बार दिखाई जाती है। Ringhum इसका केवल एक फिंगरप्रिंट सेव करता है, इसलिए इसे दोबारा नहीं दिखाया जा सकता। अगर आप इसे खो देते हैं, तो एक नई कुंजी बनाएं और पुरानी को रद्द करें।

कुंजियां ck_live_ से शुरू होती हैं। API कुंजियां टेबल हर कुंजी का नाम, उसके शुरुआती अक्षर, उसके स्कोप, आख़िरी बार इस्तेमाल होने का समय और क्या वह सक्रिय है या रद्द किया गया है, दिखाती है।

स्कोप

हर कुंजी उन एंडपॉइंट को कॉल कर सकती है जो सिर्फ़ पढ़ते हैं। जो एंडपॉइंट कुछ बनाते, बदलते या मिटाते हैं, उन्हें write स्कोप चाहिए। उदाहरण हैं कॉल करना, मैसेज भेजना, अपॉइंटमेंट बुक करना, या असिस्टेंट अपडेट करना। /docs पर मौजूद रेफरेंस इन एंडपॉइंट को चिह्नित करता है। write के बिना कुंजी को इन पर 403 एरर मिलती है।

हर सिस्टम को उतनी ही एक्सेस दें जितनी उसे ज़रूरत है। एक रिपोर्टिंग डैशबोर्ड को सिर्फ़ read चाहिए।

एक कुंजी रद्द करें

1. डेवलपर्स पर, API कुंजियां टेबल में कुंजी ढूंढें।
2. रद्द करें पर क्लिक करें और पुष्टि करें।

उस कुंजी का इस्तेमाल करने वाली रिक्वेस्ट तुरंत 401 के साथ फेल होती हैं। रद्द की गई कुंजियां सूची में रद्द किया गया के रूप में चिह्नित रहती हैं, ताकि आप उनका इतिहास देख सकें। किसी कुंजी को संपादित नहीं किया जा सकता: उसके स्कोप बदलने के लिए, एक नई कुंजी बनाएं और पुरानी को रद्द करें।

रिक्वेस्ट बनाना

• बेस URL: https://ringhum.com/api/v1
• ऑथेंटिकेशन: कुंजी को बियरर टोकन के रूप में भेजें: Authorization: Bearer ck_live_…
• फ़ॉर्मेट: आने-जाने वाला डेटा JSON में। बॉडी के साथ Content-Type: application/json भेजें।
• समय UTC में ISO 8601 फ़ॉर्मेट में होते हैं। फ़ोन नंबर E.164 फ़ॉर्मेट में होते हैं, उदाहरण के लिए +14155550132। Id पूर्णांक होते हैं।
• अपडेट के लिए सिर्फ़ बदलने वाले फ़ील्ड के साथ PATCH इस्तेमाल करें।
• हर रिस्पॉन्स में एक X-Request-Id हेडर होता है। सपोर्ट से संपर्क करते समय इसे शामिल करें।

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

कोई कुंजी किस वर्कस्पेस से जुड़ी है, यह जांचने के लिए GET /me कॉल करें।

रिस्पॉन्स और पेजिनेशन

एक सिंगल ऑब्जेक्ट {"data": {…}} के रूप में वापस आता है। पेजिनेटेड सूचियां एक meta ऑब्जेक्ट के साथ वापस आती हैं:

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

नतीजों में आगे-पीछे जाने के लिए page और per_page इस्तेमाल करें। per_page डिफ़ॉल्ट रूप से 25 होता है और ज़्यादा से ज़्यादा 100 हो सकता है।

एरर

हर विफलता एक जैसी दिखती है, एक स्थिर type के साथ जिसे आप अपने कोड में जांच सकते हैं:

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

रेट लिमिट

आप प्रति मिनट 120 रिक्वेस्ट कर सकते हैं। रिस्पॉन्स में X-RateLimit-Limit और X-RateLimit-Remaining हेडर शामिल होते हैं। जब आप सीमा पार कर जाते हैं तो आपको 429 के साथ एक Retry-After हेडर मिलता है जो बताता है कि कितने सेकंड इंतज़ार करना है।

टिप: कॉल के नतीजों के लिए पोल न करें। call.ended के लिए एक वेबहुक जोड़ें और Ringhum कॉल पूरी होने पर आपको सारांश और ट्रांसक्रिप्ट भेज देता है। देखें वेबहुक।

सामान्य सवाल

क्या कोई मशीन-रीडेबल स्पेक है? हां। OpenAPI 3.1 डिस्क्रिप्शन /api/v1/openapi.json पर है और इसके लिए किसी कुंजी की ज़रूरत नहीं है। आप इससे एक क्लाइंट जनरेट कर सकते हैं।

अगर कुंजी बनाने वाला व्यक्ति चला जाए, तो क्या कुंजी काम करना बंद कर देती है? नहीं। कुंजियां वर्कस्पेस से जुड़ी होती हैं और रद्द होने तक काम करती रहती हैं। जिन कुंजियों पर अब आपको भरोसा नहीं है, उन्हें रद्द करें, ख़ासकर जब एक्सेस रखने वाला कोई व्यक्ति चला जाए।

क्या मैं API को किसी वेब पेज से इस्तेमाल कर सकता हूं? नहीं। पेज खोलने वाला कोई भी व्यक्ति कुंजी पढ़ सकता है। API को अपने सर्वर से कॉल करें। </content>