डेवलपर्स के लिए Call API और वेबहुक: कीज़, स्कोप, इवेंट
Call REST API का व्यावहारिक परिचय: API कीज़ और स्कोप, रेट लिमिट, एरर हैंडलिंग, साइन किए गए वेबहुक और Developers पेज जहाँ आप एंडपॉइंट मैनेज करते हैं।
देर-सबेर फ़ोन सिस्टम को किसी और चीज़ से बात करनी पड़ती है: ऐसा CRM जो कॉल ख़त्म होते ही उसे दिखाए, ऐसा बिलिंग टूल जो जानना चाहे कि किसने कॉल किया, ऐसी स्क्रिप्ट जो फ़ॉर्म सबमिट होने पर कॉल करे। Call में ठीक इसी के लिए REST API और आउटबाउंड वेबहुक हैं। यह गाइड बताती है कि ये हिस्से कैसे जुड़ते हैं, कोड लिखने से पहले क्या माँगें, और वे गलतियाँ जिनमें अक्सर डेवलपर की पूरी दोपहर चली जाती है।

अगर आपका लक्ष्य बस कॉन्टैक्ट को बड़ी संख्या में ले जाना है, तो पहले फ़ोन टीम के CRM में कॉन्टैक्ट इम्पोर्ट करना पढ़ें; इम्पोर्ट अक्सर इंटीग्रेशन से आसान होता है।
कहाँ से शुरू करें: रेफ़रेंस और Developers पेज
दो जगहें जाननी ज़रूरी हैं। API reference Settings के अंतर्गत है, और होम पेज के Resources मेन्यू में भी। इसे बिना साइन इन किए पढ़ा जा सकता है, जो किसी क्लाइंट के लिए काम का दायरा तय करते समय काम आता है। Developers पेज, जो Settings के अंतर्गत ही है, आपके अपने वर्कस्पेस के लिए है: यह आपके संगठन और एजेंट के आइडेंटिफ़ायर, आपके वेबहुक एंडपॉइंट और आपकी कीज़ की सिर्फ़ पढ़ने लायक सूची दिखाता है।
हर जगह आपको क्या देती है
- Start hereबेस URL और नियम, स्कोप तालिका के साथ ऑथेंटिकेशन, और स्टेटस कोड के साथ एरर।
- Endpointsहर एंडपॉइंट कार्ड उसका स्कोप, पैरामीटर, रिक्वेस्ट बॉडी, रिस्पॉन्स और एरर बताता है, साथ में curl, JavaScript और Python में कॉपी करने के लिए तैयार रिक्वेस्ट।
- SearchSearch endpoints पर जाने के लिए / दबाएँ और मेथड, पाथ, स्कोप या सारांश से फ़िल्टर करें।
- OpenAPI JSONआपके अपने टूल के लिए पूरी स्पेसिफ़िकेशन एक फ़ाइल में डाउनलोड करता है।
- Agent ID / APIआपके संगठन की ID और स्लग, API मोड (Sandbox या Live) और आपके चुने AI एजेंट की ID, हर एक के साथ Copy बटन।
- Webhooksआपके एंडपॉइंट, हर एक को मिलने वाले इवेंट, आख़िरी HTTP स्टेटस और कोई भी विफल डिलीवरी।
रेट लिमिट और आउटबाउंड वेबहुक वाले सेक्शन लाइव होने से पहले पढ़ें, बाद में नहीं। वे ऐसे व्यवहार बताते हैं जो जल्दी के टेस्ट में आसानी से छूट जाते हैं।
API कीज़ और स्कोप
हर रिक्वेस्ट Authorization हेडर में बेयरर टोकन के रूप में एक की लेकर जाती है। कीज़ ऐप में नहीं बनाई जातीं: आपके वर्कस्पेस का ऑपरेटर उन्हें जारी करता है और बताता है कि उनमें कौन-से स्कोप हैं। पूरी की सिर्फ़ जारी होने के समय एक बार दिखती है, और बाद में सिर्फ़ उसके शुरुआती अक्षर दिखते हैं, इसलिए उसे तुरंत अपने सीक्रेट स्टोर में रखें।
| स्कोप | यह क्या करने देता है |
|---|---|
| read | कॉन्टैक्ट, कॉल, क्यू, टीम सदस्य, रिपोर्ट और डू-नॉट-कॉल सूची पढ़ना। |
| write | कॉन्टैक्ट बनाना और अपडेट करना, कॉल के नतीजे दर्ज करना, डू-नॉट-कॉल सूची में नंबर जोड़ना। |
| calls | कॉल करना और ख़त्म करना। |
| admin | वेबहुक मैनेज करना; बाक़ी सभी एंडपॉइंट भी कॉल कर सकता है। |
काम के लिए ज़रूरी सबसे छोटा सेट माँगें। रिपोर्टिंग स्क्रिप्ट को सिर्फ़ read चाहिए; क्लिक-टू-कॉल बटन को calls चाहिए। अगर कोई रिक्वेस्ट insufficient_scope कोड के साथ 403 लौटाए, तो की में वह स्कोप नहीं है जो उस एंडपॉइंट के कार्ड पर दिखाया गया है।
सैंडबॉक्स और लाइव
कीज़ सैंडबॉक्स के लिए जारी हो सकती हैं, जो सिम्युलेटर इस्तेमाल करता है और कोई असली कॉल नहीं करता, या लाइव इस्तेमाल के लिए। की के प्रीफ़िक्स को सिर्फ़ एक लेबल मानें: टेस्ट लेबल वाली की उसी डेटा और उसी फ़ोन कनेक्शन पर काम करती है जिस पर लाइव की, इसलिए प्रयोगों को असली ग्राहकों से दूर रखने के लिए प्रीफ़िक्स पर भरोसा न करें। आप कहाँ हैं, यह जानने के लिए Developers पेज पर दिखाया गया API मोड देखें।
API से कॉल करना
सार्वजनिक एंडपॉइंट बुनियादी चीज़ें कवर करते हैं: हेल्थ चेक, कॉल की सूची, एक कॉल पढ़ना, कॉल करना, कॉल काटना, वेबहुक मैनेज करना और AI एजेंट से चैट। API से की गई आउटबाउंड कॉल उसी अनुपालन जाँच से गुज़रती है जिससे डेस्क से की गई कॉल, इसलिए डू-नॉट-कॉल सूची वाला या अनुमत कॉलिंग घंटों के बाहर का नंबर ठीक वैसे ही अस्वीकार होता है जैसे किसी एजेंट के लिए होता। अपना कोड ऐसा बनाएँ कि वह इस अस्वीकृति को बग नहीं, सामान्य नतीजे के रूप में संभाले।
डिज़ाइन के लिए यह अहम है। ऐसा लूप न लिखें जो अस्वीकार हुई कॉल को तब तक दोहराए जब तक वह न हो जाए। कारण पढ़ें, लॉग करें, और आगे बढ़ें। इन अस्वीकृतियों के पीछे के नियमों के लिए Call में कॉलिंग-आवर्स गार्ड और Call में डू-नॉट-कॉल सूची देखें।
रेट लिमिट और एरर
हर की की प्रति मिनट अनुरोधों की अपनी सीमा होती है, जो की जारी होते समय तय होती है; डिफ़ॉल्ट 120 है। जब कोई की मिनट का कोटा ख़त्म कर देती है, तो API rate_limited कोड के साथ 429 लौटाता है और X-RateLimit-Reset हेडर में बताता है कि कितना इंतज़ार करना है। उतना इंतज़ार करें, फिर आगे बढ़ें। शिष्ट क्लाइंट दीवार से टकराने से पहले ख़ुद धीमा हो जाता है।
- 429 rate_limited: रीसेट हेडर में दी गई अवधि तक रुकें, और बड़े काम को समय में फैलाएँ।
- 403 insufficient_scope: की में उस एंडपॉइंट के कार्ड वाला स्कोप नहीं है; उस स्कोप वाली की माँगें।
- दूसरे एरर: संदेश नहीं, एरर कोड के आधार पर कार्रवाई करें। कोड नहीं बदलते; शब्द बदल सकते हैं।
विफल रिक्वेस्ट संभालना
- स्टेटस पढ़ेंक्या यह क्लाइंट एरर है जिसे आप ठीक कर सकते हैं, या सर्वर एरर जिसे दोबारा आज़माना ठीक है?
- कोड पढ़ेंकोड के आधार पर ब्रांच करें, संदेश के टेक्स्ट पर कभी नहीं।
- रुकें429 के लिए रीसेट हेडर तक इंतज़ार करें; सर्वर एरर के लिए बढ़ते अंतराल के साथ कुछ बार दोबारा आज़माएँ।
- विवरण लॉग करेंएंडपॉइंट, कोड और समय रखें ताकि सपोर्ट उसे ट्रेस कर सके।
- अस्वीकृति पर रुकेंअनुपालन अस्वीकृति एक फ़ैसला है, गड़बड़ी नहीं; उस पर लूप न चलाएँ।
वेबहुक: इवेंट प्राप्त करना
API से बार-बार पूछने के बजाय कि कुछ हुआ या नहीं, Call को आपको बताने दें। Developers पेज पर Add endpoint दबाएँ, एक सार्वजनिक https पता डालें, और जो इवेंट चाहिए उन पर टिक करें; किसी पर टिक न करने का मतलब है सभी इवेंट। साइनिंग सीक्रेट सिर्फ़ एक बार, एंडपॉइंट जोड़ते समय दिखता है। उसे तभी कॉपी करें। अगर वह खो जाए, तो नया पाने के लिए एंडपॉइंट डिलीट करके फिर से जोड़ें।
हर डिलीवरी साइन की होती है। सिग्नेचर हेडर में टाइमस्टैम्प और बॉडी को पूर्णविराम (.) से जोड़कर, आपके साइनिंग सीक्रेट से निकाला गया HMAC-SHA256 होता है, और एक अलग हेडर में टाइमस्टैम्प होता है। पेलोड पर भरोसा करने से पहले अपनी ओर इसे फिर से निकालें और तुलना करें। API रेफ़रेंस में इसके लिए Node.js और Python में सैंपल कोड है, और पुराने टाइमस्टैम्प अस्वीकार करना आपको दोहराए गए अनुरोधों से बचाता है।
अच्छा और कमज़ोर वेबहुक रिसीवर
| अच्छा | कमज़ोर | |
|---|---|---|
| सिग्नेचर | हर रिक्वेस्ट पर सत्यापित | बिना जाँचे भरोसा |
| जवाब | कुछ सेकंड में 2xx, काम बाद के लिए क्यू में | जवाब देने से पहले धीमी प्रोसेसिंग |
| डुप्लिकेट | एक ही इवेंट दो बार मिलना सुरक्षित | दो रिकॉर्ड बना देता है |
| विफलताएँ | डिलीवरी विफल होने पर अलर्ट | किसी के ध्यान देने तक चुप |
आपके एंडपॉइंट को 10 सेकंड के भीतर 2xx स्टेटस के साथ जवाब देना होगा। विफल डिलीवरी फिर से आज़माई जाती है, कुल छह कोशिशों तक, और जो एंडपॉइंट लगातार 50 बार विफल हो उसे बंद कर दिया जाता है। Developers पेज की हर पंक्ति आख़िरी HTTP स्टेटस और कितनी डिलीवरी विफल हुईं यह दिखाती है, और Send test एक साइन किया हुआ टेस्ट इवेंट भेजता है ताकि आप देख सकें कि आपका सर्वर क्या जवाब देता है।
लाइव होने की चेकलिस्ट
इंटीग्रेशन चालू करने से पहले
- आपको पता है कि की में कौन-से स्कोप हैं, और ज़रूरत से ज़्यादा नहीं हैं
- की सीक्रेट स्टोर में रखी है, सोर्स कोड में नहीं
- वेबहुक सिग्नेचर सत्यापित होते हैं और पुराने टाइमस्टैम्प अस्वीकार होते हैं
- रिसीवर जल्दी जवाब देता है और डुप्लिकेट इवेंट संभालता है
- रेट-लिमिट और अस्वीकृति वाले रिस्पॉन्स बिना तंग रीट्राई लूप के संभाले जाते हैं
- आपने सैंडबॉक्स मोड में टेस्ट किया और एंडपॉइंट पर Send test दबाया
- डिलीवरी विफल होने लगें तो अलर्ट पाने के लिए किसी व्यक्ति का नाम तय है
Call में ऐसा करना
Call में एंडपॉइंट समझने के लिए Settings, फिर API reference खोलें, और अपने संगठन की ID कॉपी करने, अपनी कीज़ देखने और वेबहुक जोड़ने के लिए Settings, फिर Developers खोलें। ओनर, एडमिन और मैनेजर एंडपॉइंट जोड़, टेस्ट और डिलीट कर सकते हैं; बाक़ी सबको सूची दिखती है। अगर आप AI एजेंट फ़ीचर भी इस्तेमाल करते हैं, तो उसी पेज पर एजेंट ID चैट एंडपॉइंट में जाती है। प्रोडक्ट के वॉइस पक्ष के लिए Call में AI एजेंट सेट करना देखें।
अक्सर पूछे जाने वाले प्रश्न
मुझे API की कैसे मिलेगी?
कीज़ आपके वर्कस्पेस का ऑपरेटर जारी करता है; इन्हें ऐप में नहीं बनाया जा सकता। एक माँगें और बताएँ कि उसे कौन-से स्कोप चाहिए। पूरी की जारी होते समय एक बार दिखती है।
429 रिस्पॉन्स का क्या मतलब है?
की ने मौजूदा मिनट के अपने अनुरोध ख़त्म कर दिए हैं। X-RateLimit-Reset हेडर में दिए सेकंड तक इंतज़ार करें, फिर दोबारा आज़माएँ, और बड़े काम को लंबी अवधि में फैलाएँ।
मैं कैसे जाँचूँ कि वेबहुक सच में Call से आया है?
अपने साइनिंग सीक्रेट से टाइमस्टैम्प और बॉडी का HMAC-SHA256 निकालें और उसे सिग्नेचर हेडर से मिलाएँ। API रेफ़रेंस Node.js और Python में उदाहरण दिखाता है।
क्या मैं लोकल डेवलपमेंट सर्वर पर वेबहुक भेज सकता/सकती हूँ?
सीधे नहीं। एंडपॉइंट सार्वजनिक https पते होने चाहिए, इसलिए ऐसा टनलिंग टूल इस्तेमाल करें जो आपके लोकल सर्वर को ऐसे पते पर उपलब्ध कराए।
कॉल करने का मेरा API अनुरोध अस्वीकार क्यों हुआ?
API से की गई कॉल उसी अनुपालन जाँच से गुज़रती हैं जिससे डेस्क से की गई कॉल। डू-नॉट-कॉल सूची वाला या कॉलिंग घंटों के बाहर का नंबर अस्वीकार होता है।
वेबहुक कौन देख और बदल सकता है?
सूची हर कोई पढ़ सकता है, लेकिन एंडपॉइंट सिर्फ़ ओनर, एडमिन और मैनेजर जोड़, टेस्ट या डिलीट कर सकते हैं।