वॉइस इवेंट

कॉल शुरू होने, उसका जवाब मिलने और उसके खत्म होने पर Bird वेबहुक इवेंट भेजता है। पोलिंग के बिना अपने सिस्टम अपडेट करने के लिए इनका इस्तेमाल करें। सब्सक्रिप्शन, सिग्नेचर, फिर से प्रयास और रीप्ले के लिए वेबहुक देखें।

इवेंट प्रकारों के ज़रिए किसी कॉल का क्रम:

1. voice_call.initiated: Bird ने कॉल सेटअप अनुरोध (एक SIP INVITE) स्वीकार किया और कॉल को रूट करना शुरू किया
2. voice_call.answered: जिस नंबर पर आपने कॉल किया, उसने कॉल उठा ली। यह इवेंट केवल जवाब दी गई कॉल के लिए आता है
3. voice_call.ended: कॉल खत्म हो गई है, और इवेंट में उसका परिणाम होता है

voice_call.initiated पुष्टि करता है कि कॉल मौजूद है, जबकि voice_call.ended उसका परिणाम बताता है। अस्वीकार की गई या विफल कॉल के लिए, रिपोर्ट की गई स्थिति और अंतिम SIP प्रतिक्रिया को कॉल रिकॉर्ड के साथ इस्तेमाल करें। केवल एक इवेंट मौजूद होने से पूरे जीवनकाल का अनुमान न लगाएँ।

इवेंट type एक ओपन enum है: Bird समय के साथ नए प्रकार जोड़ सकता है, इसलिए जिन प्रकारों को आप संभालते हैं उनका मिलान करें और बाकी को अनदेखा करें, किसी अपरिचित प्रकार को त्रुटि न मानें।

इवेंट एनवेलप

वॉइस इवेंट उसी नेस्टेड एनवेलप में आते हैं जिसमें हर दूसरा Bird इवेंट आता है, जिसका वर्णन वेबहुक गाइड में है: type, timestamp, और प्रकार के अनुसार एक data ऑब्जेक्ट। इवेंट की पहचान बॉडी में नहीं, बल्कि webhook-id HTTP हेडर में होती है।

हर वॉइस इवेंट के data में मिलान के लिए पहचान वाले वही फ़ील्ड होते हैं। फ़ोन नंबर E.164 फ़ॉर्मेट में होते हैं: शुरुआत में +, फिर देश कोड और राष्ट्रीय नंबर। किसी वर्कस्पेस उपयोगकर्ता या रिंग ग्रुप को ब्राउज़र से की गई कॉल में from कॉल करने वाले की usr_ ID हो सकता है। वर्कस्पेस उपयोगकर्ताओं, रिंग ग्रुप और सीक्वेंस को ब्राउज़र से की जाने वाली कॉल प्रीव्यू में हैं। दोनों पक्ष SIP एक्सटेंशन भी हो सकते हैं, और to किसी वर्कस्पेस उपयोगकर्ता, रिंग ग्रुप या सीक्वेंस की ID हो सकता है।

इवेंट फ़ील्ड के नाम लेग API से अलग हैं: इवेंट का call_id लेग की पहचान करता है और लेग प्रतिक्रिया के id से मेल खाता है; इवेंट का session_id लेग प्रतिक्रिया के call_id से मेल खाता है। वेबहुक अपडेट को API रिकॉर्ड से जोड़ते समय इसी मैपिंग का उपयोग करें।

ये लाइफ़साइकल इवेंट साझा वेबहुक डिलीवरी और सिग्नेचर अनुबंध का उपयोग करते हैं। किसी सीक्वेंस का सिंक्रोनस वेबहुक चरण एक अलग रिसीवर प्रोटोकॉल का उपयोग करता है, जिस पर इवेंट सब्सक्रिप्शन के सीक्रेट से नहीं, बल्कि वर्कस्पेस के कॉलबैक सीक्रेट से सिग्नेचर किया जाता है।

voice_call.initiated

Bird को INVITE मिला और उसने कॉल को रूट करना शुरू किया।

{
  "type": "voice_call.initiated",
  "timestamp": "2026-06-10T14:30:00Z",
  "data": {
    "call_id": "vcl_01krdgeqcxet5s7t44vh8rt9mg",
    "session_id": "vcs_01krdgeqcxet5s7t44vh8rt9mh",
    "workspace_id": "wsp_01krdgeqcxet5s7t44vh8rt9mj",
    "direction": "outbound",
    "from": "+14155551234",
    "to": "+16505559876"
  }
}

voice_call.answered

प्राप्तकर्ता ने कॉल का जवाब दिया और बिल योग्य समय शुरू हो गया। जिस कॉल का जवाब नहीं दिया जाता, वह यह इवेंट नहीं भेजती।

पेलोड में वही कॉल पहचान फ़ील्ड होते हैं जो हर वॉइस इवेंट में होते हैं, और timestamp जवाब दिए जाने के क्षण पर सेट होता है।

voice_call.ended

कॉल समाप्त हो गई है। यह इवेंट परिणाम भी जोड़ता है:

{
  "type": "voice_call.ended",
  "timestamp": "2026-06-10T14:31:05Z",
  "data": {
    "call_id": "vcl_01krdgeqcxet5s7t44vh8rt9mg",
    "session_id": "vcs_01krdgeqcxet5s7t44vh8rt9mh",
    "workspace_id": "wsp_01krdgeqcxet5s7t44vh8rt9mj",
    "direction": "outbound",
    "from": "+14155551234",
    "to": "+16505559876",
    "status": "answered",
    "sip_response_code": 200,
    "duration_ms": 65000,
    "billable_ms": 60000
  }
}

यह इवेंट नहीं बताता कि कॉल क्यों समाप्त हुई। जो कॉल प्लेटफ़ॉर्म की कॉल अवधि सीमा तक पहुँच गई, वह एक सामान्य answered समाप्ति के रूप में आती है, जिसका duration_ms लगभग 4 घंटे होता है।

कॉल रिकॉर्ड में दो ऐसी जानकारियाँ होती हैं जो यह इवेंट नहीं देता: अस्वीकृति का कारण और लागत। Bird द्वारा अस्वीकृति और कैरियर की विफलता में अंतर करने के लिए कॉल लॉग में कॉल खोलें। रेटिंग पूरी होने के बाद लागत दिखाई देती है।

इन्हें सुरक्षित रूप से उपयोग करना

• webhook-id के आधार पर डुप्लिकेट हटाएँ। सिग्नलिंग या डिलीवरी का फिर से प्रयास किसी अपडेट को दोहरा सकता है। एक ही कॉल चरण दोबारा प्रकाशित होने पर उसकी डिलीवरी पहचान वही रहती है, इसलिए उसे कुंजी बनाने से डुप्लिकेट हट जाता है।
• क्रम पर निर्भर न रहें। डिलीवरी क्रम में नहीं होतीं, इसलिए answered आपको ended के बाद मिल सकता है। timestamp के अनुसार क्रमबद्ध करें, और बाद में पहुँचे किंतु पहले के टाइमस्टैम्प वाले इवेंट को अनदेखा करें।
• रिपोर्ट किए गए परिणाम के लिए ended का उपयोग करें। इसमें स्थिति और अवधियाँ होती हैं। डिलीवरी कतार में लगने से पहले ही इवेंट का प्रकाशन विफल हो सकता है, इसलिए किसी इवेंट के न मिलने से यह सिद्ध नहीं होता कि कॉल अभी भी सक्रिय है।
• कॉल रिकॉर्ड से मिलान करें। इवेंट समय पर अपडेट देते हैं, जबकि कॉल रिकॉर्ड कॉल लॉग में रहता है। मिलान के लिए कॉल को CSV के रूप में एक्सपोर्ट करें।

अगले कदम