Voice इवेंट

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

इवेंट टाइप के ज़रिए एक कॉल का पथ:

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

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

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

इवेंट एनवेलप

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

फ़ील्ड	विवरण
`type`	इस पेज पर तीन टाइप में से एक, उदाहरण के लिए `voice_call.ended`
`timestamp`	इवेंट कब हुआ (RFC 3339)। इसी से सॉर्ट करें, आगमन क्रम से कभी नहीं
`data`	इवेंट-विशिष्ट पेलोड, जिसमें हमेशा वही कॉल पहचान फ़ील्ड होती हैं

हर voice इवेंट के data में सहसंबंध के लिए वही पहचान फ़ील्ड होती हैं। दोनों नंबर E.164 फ़ॉर्मैट में होते हैं: शुरू में +, कंट्री कोड, और राष्ट्रीय नंबर।

फ़ील्ड	विवरण
`call_id`	कॉल रिकॉर्ड की id (`vcl_…`), वही जो Call log में दिखाई देती है
`session_id`	ट्रांसफ़र या मल्टी-पार्टी कॉल के हर लेग में साझा (`vcs_…`)। जब कोई सेशन सहसंबंध लागू नहीं होता तो null
`workspace_id`	वह वर्कस्पेस जिससे कॉल संबंधित है
`direction`	प्राप्त कॉल के लिए `inbound`; की गई कॉल के लिए `outbound`
`from`	कॉल करने वाला नंबर
`to`	जिस नंबर पर कॉल किया गया

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

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

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

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

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

voice_call.ended

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

फ़ील्ड	विवरण
`status`	कैसे समाप्त हुई: `answered`, `no_answer`, `failed`, `rejected`, या `unknown` (देखें Statuses)
`sip_response_code`	कॉल का अंतिम SIP कोड, उदाहरण के लिए `200` या `486`। Bird द्वारा अस्वीकार की गई कॉल `503` लेकर आती है; जब कोई अंतिम कोड रिकॉर्ड नहीं हुआ तो null
`duration_ms`	मिलीसेकंड में कुल कॉल अवधि, Bird द्वारा कॉल प्राप्त करने के क्षण से हैंगअप तक
`billable_ms`	मिलीसेकंड में उत्तर दिए जाने के बाद की अवधि; जिस कॉल का किसी ने उत्तर नहीं दिया उसके लिए शून्य रिपोर्ट होता है

कोड उदाहरण

{
  "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 लगभग 3 घंटे होती है।

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

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

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

अगले कदम

पेज	किसे कवर करता है
Webhooks और इवेंट	एंडपॉइंट सेटअप, सिग्नेचर सत्यापन, फिर से प्रयास, और रीप्ले
Call log	कॉल रिकॉर्ड की हर फ़ील्ड, और CSV एक्सपोर्ट

इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।

इम्प्लीमेंटेशन ब्रीफ़ पाएँ