API Block - अपने चैटबॉट फ़्लो से बाहरी API कॉल करें

अपने ChatMaxima चैटबॉट फ़्लो से किसी भी REST API को कॉल करें। URL, मेथड, हेडर, प्रमाणीकरण, बॉडी कॉन्फ़िगर करें और JSON प्रतिक्रिया फ़ील्ड को वेरिएबल से मैप करें।

अवलोकन

API Block आपके चैटबॉट को कन्वर्सेशन के बीच किसी भी बाहरी REST API को कॉल करने, प्रतिक्रिया कैप्चर करने, और सफलता या विफलता के आधार पर फ़्लो को रूट करने देता है। इसका उपयोग अपने डेटाबेस में ऑर्डर देखने, OTP सत्यापित करने, शिपमेंट स्थिति लाने, खाता बैलेंस जांचने, या किसी भी ऐसे सिस्टम को एकीकृत करने के लिए करें जो एक HTTP एंडपॉइंट उजागर करता है।

जब बॉट किसी API ब्लॉक तक पहुंचता है, तो यह कॉन्फ़िगर किया गया HTTP अनुरोध भेजता है, प्रतिक्रिया की प्रतीक्षा करता है, JSON या XML बॉडी से फ़ील्ड को वेरिएबल में निकालता है, और फिर सफलता शाखा (HTTP 2xx/3xx) या विफलता शाखा (HTTP 4xx/5xx) का पालन करता है। फ़्लो में अगले ब्लॉक निकाले गए वेरिएबल को संदेशों, शर्तों, या बाद की API कॉल में उपयोग कर सकते हैं।

इसे कहां खोजें

Studio में अपना चैटबॉट खोलें
बाएं साइडबार से API ब्लॉक को कैनवास पर ड्रैग करें
इसे किसी भी पिछले ब्लॉक से कनेक्ट करें
इसे कॉन्फ़िगर करने के लिए ब्लॉक पर डबल-क्लिक करें

API ब्लॉक में दो आउटपुट कनेक्शन हैं: 2xx और 3xx प्रतिक्रियाओं के लिए Success (शीर्ष/डिफ़ॉल्ट), और 4xx और 5xx प्रतिक्रियाओं के लिए Failure (द्वितीयक)।

कॉन्फ़िगरेशन

चरण 1: अनुरोध URL और मेथड सेट करें

फ़ील्ड	विवरण
URL	पूर्ण एंडपॉइंट, उदाहरण के लिए `https://api.example.com/orders/{order_id}`
Method	HTTP क्रिया: `GET`, `POST`, `PUT`, `PATCH`, या `DELETE`

आप {variable_name} सिंटैक्स (एकल कर्ली ब्रेसेस) का उपयोग करके फ़्लो में पहले कैप्चर किए गए किसी भी वेरिएबल को सम्मिलित कर सकते हैं। अनुरोध भेजे जाने से पहले वेरिएबल रनटाइम पर हल किए जाते हैं।

चरण 2: क्वेरी पैरामीटर जोड़ें (वैकल्पिक)

GET अनुरोधों के लिए, URL में की-वैल्यू जोड़े जोड़ने के लिए Query Parameters का उपयोग करें। प्रत्येक पंक्ति एक Key और एक Value लेती है। वेरिएबल प्रतिस्थापन दोनों फ़ील्ड में काम करता है।

Key: customer_email       Value: {email}
Key: include_archived     Value: false

चरण 3: हेडर कॉन्फ़िगर करें

Headers अनुभाग के तहत कस्टम HTTP हेडर जोड़ें। प्रत्येक पंक्ति एक Key और एक Value लेती है।

Key: Content-Type         Value: application/json
Key: Accept               Value: application/json
Key: X-Custom-Header      Value: {tenant_id}

जब आप कोई बॉडी प्रारूप चुनते हैं तो Content-Type स्वतः-पहचाना जाता है, लेकिन आप इसे ओवरराइड कर सकते हैं।

चरण 4: प्रमाणीकरण जोड़ें

API ब्लॉक तीन प्रमाणीकरण मोड का समर्थन करता है। वह चुनें जो आपके लक्ष्य API से मेल खाता हो।

Auth प्रकार	फ़ील्ड	इसे कैसे भेजा जाता है
Basic Auth	Username, Password	`Authorization: Basic <base64>` के रूप में भेजा गया
Bearer Token	Bearer Token	`Authorization: Bearer <token>` के रूप में भेजा गया
Custom Header	Header Name, Header Value	`<Name>: <Value>` के रूप में भेजा गया (API keys, कस्टम स्कीम के लिए)

ध्यान दें: उन API के लिए जो x-api-key या समान का उपयोग करती हैं, Custom Header चुनें और Name को x-api-key और Value को अपनी की पर सेट करें। आप की को एक वेरिएबल में भी संग्रहीत कर सकते हैं और इसे {api_key} के रूप में संदर्भित कर सकते हैं।

चरण 5: अनुरोध बॉडी बनाएं

POST, PUT, और PATCH अनुरोधों के लिए, Body अनुभाग में बॉडी कॉन्फ़िगर करें। प्रारूप चुनें:

प्रारूप	इसका उपयोग कब करें
JSON	अधिकांश आधुनिक REST API
XML	लीगेसी SOAP या XML एंडपॉइंट
None	किसी बॉडी की आवश्यकता नहीं (`GET` और `DELETE` के लिए विशिष्ट)

बॉडी संपादक में कच्चा JSON या XML लिखें। वेरिएबल को इनलाइन सम्मिलित किया जा सकता है:

{
  "order_id": "{order_id}",
  "customer": {
    "name": "{name}",
    "email": "{email}"
  },
  "total": {amount}
}

चरण 6: प्रतिक्रिया को वेरिएबल से मैप करें

Save Response to Variables के तहत, परिभाषित करें कि JSON प्रतिक्रिया से फ़ील्ड को फ़्लो वेरिएबल में कैसे निकालना है।

JSON Path	Variable Name
`result.user.name`	`user_name`
`data.orders[0].status`	`order_status`
`items[*].id`	`item_ids`

समर्थित पथ सिंटैक्स:

नेस्टेड ऑब्जेक्ट के लिए डॉट नोटेशन: result.user.email
ऐरे इंडेक्स: items[0].name
वाइल्डकार्ड ऐरे एक्सट्रैक्शन: items[*].id सभी ID को एक ऐरे के रूप में लौटाता है
रूट फ़ील्ड: status या message

निकाले गए मान सभी बाद के ब्लॉक में {variable_name} के रूप में उपलब्ध हैं।

चरण 7: सबमिट करें और सहेजें

ब्लॉक मोडल में Submit पर क्लिक करें, फिर शीर्ष बार में Save Changes का उपयोग करके फ़्लो सहेजें।

प्रतिक्रिया को कैसे संभाला जाता है

सफलता पथ (HTTP 2xx / 3xx)

Save Response to Variables से वेरिएबल भरे जाते हैं
फ़्लो Success आउटपुट कनेक्शन का पालन करता है

विफलता पथ (HTTP 4xx / 5xx)

त्रुटि बॉडी के आधार पर प्रतिक्रिया वेरिएबल भर भी सकते हैं या नहीं भी
फ़्लो Failure आउटपुट कनेक्शन का पालन करता है
एक अनुकूल त्रुटि संदेश भेजने या पुनः प्रयास करने के लिए इस शाखा का उपयोग करें

टाइमआउट

अनुरोध 30 सेकंड के बाद टाइम आउट हो जाते हैं। यदि आपकी API धीमी है, तो काम को दो चरणों में विभाजित करने या एक वेबहुक-संचालित async पैटर्न का उपयोग करने पर विचार करें।

API Playground में परीक्षण

हर API ब्लॉक कॉल लॉग की जाती है और Studio के भीतर API Playground में उपलब्ध होती है। प्रत्येक टेस्ट रन के लिए आप देख सकते हैं:

पूरी तरह हल किया गया URL, मेथड, और हेडर
भेजी गई अनुरोध बॉडी
प्राप्त HTTP स्थिति कोड
पूर्ण प्रतिक्रिया बॉडी
निकाले गए वेरिएबल

फ़्लो शिप करने से पहले टेम्पलेट वेरिएबल, प्रमाणीकरण, और JSON पथ मैपिंग को डीबग करने के लिए प्लेग्राउंड का उपयोग करें।

सर्वोत्तम अभ्यास

रहस्य वेरिएबल में संग्रहीत करें, ब्लॉक कॉन्फ़िग में नहीं। पर्यावरण-विशिष्ट सेटिंग्स से API keys कैप्चर करें और उन्हें वेरिएबल के माध्यम से पास करें ताकि वही फ़्लो स्टेजिंग और प्रोडक्शन में काम करे
हमेशा Failure शाखा कॉन्फ़िगर करें। कभी यह न मानें कि API कॉल सफल होती है। "We could not retrieve your order right now. Please try again later." जैसा एक फ़ॉलबैक संदेश भेजें।
अनुरोध बॉडी को छोटा रखें। पूरे चैट इतिहास या बड़े पेलोड न भेजें जब तक कि API को उनकी आवश्यकता न हो
उपयोग से पहले प्रतिक्रिया फ़ील्ड को सत्यापित करें। यदि order_status गायब हो सकता है, तो किसी संदेश में उपयोग करने से पहले {order_status} जांचने के लिए API कॉल के बाद एक Condition ब्लॉक जोड़ें
वर्णनात्मक वेरिएबल नामों का उपयोग करें। user_email, val1 से बेहतर है क्योंकि Playground और कन्वर्सेशन लॉग में इसे डीबग करना आसान है
JSON भेजते समय Content-Type को स्पष्ट रूप से सेट करें, ताकि सख्त API अनुरोध स्वीकार करें

सामान्य उपयोग के मामले

ऑर्डर लुकअप

ग्राहक एक ऑर्डर ID प्रदान करता है, बॉट आपके ई-कॉमर्स बैकएंड से स्थिति लाता है।

Method: GET
URL: https://api.myshop.com/orders/{order_id}
Auth: Bearer Token
Response Map: data.status को order_status से, data.tracking_url को tracking_url से

OTP सत्यापन

बॉट एक 6-अंकीय कोड एकत्र करता है, आपके सत्यापन एंडपॉइंट को कॉल करता है, और परिणाम के आधार पर शाखा बनाता है।

Method: POST
URL: https://api.myapp.com/verify-otp/
Body: {"phone": "{phone}", "code": "{otp_code}"}
Response Map: verified को otp_verified से
आगे एक Condition ब्लॉक का उपयोग करें: यदि {otp_verified} == true तो जारी रखें, अन्यथा फिर से पूछें

CRM संपर्क सिंक

जब उपयोगकर्ता योग्यता पूरी करता है तो एकत्रित संपर्क विवरण को अपने CRM में पुश करें।

Method: POST
URL: https://api.crm.com/v1/contacts/
Auth: Custom Header (x-api-key: {crm_key})
Body: {"name": "{name}", "email": "{email}", "source": "chatbot"}

समस्या निवारण

अनुरोध 401 Unauthorized के साथ विफल होता है

जांचें कि auth प्रकार उससे मेल खाता है जो API अपेक्षा करती है
Bearer टोकन के लिए, टोकन फ़ील्ड में Bearer शब्द शामिल न करें। ब्लॉक इसे स्वचालित रूप से जोड़ता है
Custom Header auth के लिए, सत्यापित करें कि हेडर नाम API डॉक्स से बिल्कुल मेल खाता है (कुछ API के लिए केस-संवेदनशील)
यह पुष्टि करने के लिए API Playground में अनुरोध का निरीक्षण करें कि हेडर भेजा जा रहा है

प्रतिक्रिया से वेरिएबल नहीं भर रहे

API Playground खोलें और वास्तविक प्रतिक्रिया बॉडी का निरीक्षण करें
पुष्टि करें कि JSON पथ प्रतिक्रिया संरचना से मेल खाता है। पथ केस-संवेदनशील होते हैं
ऐरे के लिए, एकल मान के लिए items[0].field या सभी मानों के लिए items[*].field का उपयोग करें
यदि प्रतिक्रिया XML है, तो सुनिश्चित करें कि आपने बॉडी प्रारूप सही ढंग से सेट किया है। JSON पथ पार्स किए गए XML पर भी काम करते हैं

API काम करने पर भी फ़्लो विफलता शाखा का पालन करता है

API Playground में HTTP स्थिति कोड जांचें। कुछ API POST पर 201 (Created) लौटाती हैं जो अभी भी सफलता है
यदि API 200 लौटाती है लेकिन बॉडी में एक त्रुटि के साथ, तो प्रतिक्रिया फ़ील्ड का निरीक्षण करने के लिए सफलता शाखा के बाद एक Condition ब्लॉक का उपयोग करें

अनुरोध टाइम आउट हो जाता है

टाइमआउट 30 सेकंड पर निश्चित है। यदि आपकी API नियमित रूप से अधिक समय लेती है, तो API रीयल-टाइम चैट के लिए उपयुक्त नहीं हो सकती
धीमे काम को एक पृष्ठभूमि जॉब में ले जाने और परिणाम के लिए पोलिंग करने पर विचार करें, या तैयार होने पर सूचित होने के लिए एक वेबहुक का उपयोग करें

टेम्पलेट वेरिएबल अनुरोध में कच्चे `{variable}` के रूप में दिखाई देते हैं

पुष्टि करें कि वेरिएबल फ़्लो में एक पहले के ब्लॉक द्वारा सेट किया गया था
वेरिएबल नाम की वर्तनी जांचें (केस-संवेदनशील)
यह निरीक्षण करने के लिए Conversation Log का उपयोग करें कि उस बिंदु पर कौन से वेरिएबल वास्तव में भरे गए हैं

अगले चरण

Webhook Block - किसी फ़्लो को ट्रिगर या फिर से शुरू करने के लिए इनबाउंड HTTP कॉल प्राप्त करें
Conversation End Block - एक रीस्टार्ट बटन के साथ कन्वर्सेशन समाप्त करें
Studio अवलोकन - सभी ब्लॉक प्रकार और फ़्लो बिल्डर सुविधाओं का अन्वेषण करें