Voice इवेंट

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

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

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

voice_call.initiated पुष्टि करता है कि कॉल मौजूद है, जबकि voice_call.ended उसका परिणाम रिपोर्ट करता है। INVITE स्वीकार करने के बाद Bird अस्वीकार हुई कॉल भी status: "failed" और sip_response_code: 503 के साथ voice_call.ended भेजती है।

इवेंट 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	आपके उपकरण द्वारा की गई कॉल के लिए outbound
from	कॉल करने वाला नंबर
to	जिस नंबर पर कॉल किया गया

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

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

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

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

अगले कदम

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