वॉइस कॉल बनाएँ

Warning: Voice sequences are in preview. Steps, entry data, and the sequence definition format can change in ways that break existing sequences and API requests.

किसी फ़ोन नंबर पर कॉल करने और प्राप्तकर्ता के उत्तर देने पर एक प्रकाशित sequence, या अनुरोध के साथ भेजी गई sequence डेफ़िनिशन, शुरू करने के लिए POST /v1/voice/calls का उपयोग करें। यह अनुरोध एक वास्तविक कॉल करता है; सामान्य कॉलिंग शुल्क लागू होते हैं।

CLI और MCP प्रीव्यू: इन इंटरफ़ेस के लिए संगत क्लाइंट चाहिए। जाँचें कि आपका MCP सर्वर voice_calls_create उपलब्ध कराता है, या अपने CLI के कमांड देखने के लिए bird voice --help चलाएँ। नए रिलीज़ की जाँच के लिए bird update --check चलाएँ और CLI इंस्टॉलेशन देखें। अगर टूल या कमांड उपलब्ध नहीं है, तो HTTP API या SDK का उपयोग करें।

प्रीव्यू में, CLI और MCP एक ही कॉल को किसी व्यक्ति की समीक्षा और ब्राउज़र में चलाने के लिए तैयार करते हैं। व्यक्ति द्वारा अनुरोध चलाने के बाद एजेंट को रिकॉर्ड किया गया स्वीकृति परिणाम प्राप्त होता है।

शुरू करने से पहले

एक ही वर्कस्पेस में ये संसाधन तैयार करें:

• चलाने के लिए एक sequence: डैशबोर्ड में बनाया गया एक सक्षम, अनआर्काइव्ड सक्रिय प्रकाशन वाला sequence, या अनुरोध के साथ भेजी गई एक पूर्ण डेफ़िनिशन।
• HTTP अनुरोधों के लिए एक API key, या CLI और MCP के लिए एक OAuth लॉगिन, जिसमें voice_management:write और voice:write दोनों अनुमतियाँ हों।
• एक कॉलिंग नंबर जो वर्कस्पेस प्रस्तुत कर सके, जैसे कोई स्वामित्व वाला या सत्यापित caller ID, और एक सक्षम गंतव्य देश। प्राप्तकर्ता के देश का नंबर प्राथमिकता दें: कुछ मोबाइल नेटवर्क विदेशी caller ID प्रस्तुत करने वाली कॉल को अस्वीकार कर देते हैं।
• पहली कॉल के लिए एक ऐसा प्राप्तकर्ता जिसे आप नियंत्रित करते हैं।

sequence ऑब्जेक्ट sequence.id या sequence.definition में से ठीक एक लेता है। दोनों को entry_node_id भी चाहिए, वह Start call स्टेप जहाँ से कॉल शुरू होता है, और trigger_data, उस एंट्री के डेटा स्कीमा से मेल खाने वाला ऑब्जेक्ट। जब एंट्री खाली डेटा स्वीकार करती हो तो {} का उपयोग करें। Create Call संदर्भ में अनुरोध सीमाएँ और वैकल्पिक रिंगिंग टाइमआउट प्रलेखित हैं।

डैशबोर्ड में बना sequence कॉल करें

डैशबोर्ड में आपके द्वारा बनाए और प्रकाशित किए गए sequence को चलाने के लिए sequence.id का उपयोग करें। Create Call हमेशा इसके सक्रिय प्रकाशन को चलाता है।

1. Sequences में sequence खोलें।
2. How to run this sequence के अंतर्गत, Create a call के बगल में More details चुनें।
3. यदि sequence में कई entries हैं, तो शुरू करने के लिए Call trigger चुनें।
4. अनुरोध कॉपी करें। इसमें sequence ID और entry ID होती है।

उदाहरण नंबरों को अपने नंबरों से बदलते हुए अनुरोध बॉडी को call.json के रूप में सेव करें:

{
  "from": "+12025550100",
  "to": "+12025550101",
  "sequence": {
    "id": "YOUR_SEQUENCE_ID",
    "entry_node_id": "YOUR_ENTRY_NODE_ID",
    "trigger_data": {}
  }
}

trigger_data में entry द्वारा घोषित फ़ील्ड भरें, जिनमें नेस्टेड ऑब्जेक्ट और ऐरे शामिल हैं। Create Call ऐतिहासिक संस्करण, ड्राफ़्ट, या टेस्ट मोड स्वीकार नहीं करता। सेव किए गए ड्राफ़्ट का परीक्षण करने के लिए डैशबोर्ड के Place a call नियंत्रणों का उपयोग करें।

इनलाइन sequence चलाएँ

कॉल के साथ एक पूर्ण sequence भेजने के लिए sequence.definition का उपयोग करें। Bird इसे एक बार चलाता है और सेव नहीं करता, इसलिए कॉल का कोई sequence ID नहीं होता। इनलाइन डेफ़िनिशन उन फ़्लो के लिए उपयुक्त है जो आपका एप्लिकेशन प्रति कॉल जनरेट करता है।

इनलाइन डेफ़िनिशन को वही जाँचें पास करनी होती हैं जो सीक्वेंस प्रकाशित करते समय होती हैं। इसका रन अधिकतम 16 कमांड चला सकता है, जिसमें gather प्रॉम्प्ट शामिल हैं; जिस कॉल को 17वें की ज़रूरत हो वह call_limit trace error के साथ समाप्त होती है। नोड संदर्भ हर उपलब्ध स्टेप को उसके फ़ील्ड और आउटकम सहित सूचीबद्ध करता है। किसी कार्यशील फ़्लो से शुरू करने के लिए, इसे डैशबोर्ड में बनाएँ और प्रकाशित करें, सीक्वेंस खोलें, और Published version के अंतर्गत Definition JSON पर Copy JSON चुनें।

यह call.json प्राप्तकर्ता से खुलने के समय के लिए 1 या दिशा-निर्देशों के लिए 2 दबाने को कहता है। मौन और कोई भी अन्य key अपने स्वयं के exit कारणों के साथ रन समाप्त करते हैं:

{
  "from": "+12025550100",
  "to": "+12025550101",
  "sequence": {
    "entry_node_id": "start",
    "trigger_data": {},
    "definition": {
      "schema_version": 1,
      "expression_environment": "bird.cel.v1",
      "nodes": [
        {
          "id": "start",
          "type": "trigger.start_call",
          "type_version": 1,
          "config": {},
          "input": {},
          "connections": { "event": { "node_id": "menu", "port": "input" } }
        },
        {
          "id": "menu",
          "type": "voice.gather",
          "type_version": 1,
          "config": {},
          "input": {
            "prompts": [
              {
                "type": "say",
                "text": "Press 1 for opening hours, or 2 for directions.",
                "language": "en"
              }
            ],
            "max_digits": 1,
            "timeout_seconds": 5,
            "inter_digit_timeout_seconds": 2,
            "finish_on_key": "#",
            "private": false,
            "matches": { "hours": "1", "directions": "2" }
          },
          "connections": {
            "hours": { "node_id": "hours", "port": "input" },
            "directions": { "node_id": "directions", "port": "input" },
            "timeout": { "node_id": "no_input", "port": "input" },
            "fallback": { "node_id": "other_input", "port": "input" }
          }
        },
        {
          "id": "hours",
          "type": "voice.say",
          "type_version": 1,
          "config": {},
          "input": { "text": "We are open Monday through Friday, nine to five.", "language": "en" },
          "connections": { "next": { "node_id": "done", "port": "input" } }
        },
        {
          "id": "directions",
          "type": "voice.say",
          "type_version": 1,
          "config": {},
          "input": {
            "text": "Find directions on your appointment confirmation.",
            "language": "en"
          },
          "connections": { "next": { "node_id": "done", "port": "input" } }
        },
        {
          "id": "done",
          "type": "logic.exit",
          "type_version": 1,
          "config": { "status": "succeeded", "reason": "information_played" },
          "input": { "output": {} }
        },
        {
          "id": "no_input",
          "type": "logic.exit",
          "type_version": 1,
          "config": { "status": "succeeded", "reason": "no_input" },
          "input": { "output": {} }
        },
        {
          "id": "other_input",
          "type": "logic.exit",
          "type_version": 1,
          "config": { "status": "succeeded", "reason": "unrecognized_input" },
          "input": { "output": {} }
        }
      ]
    }
  }
}

प्रत्येक नोड का connections एक परिणाम को अगले नोड से मैप करता है। मेनू का matches उसके विकल्पों के नाम बताता है, और connections बिल्ट-इन timeout और fallback परिणामों के साथ उन्हीं नामों का उपयोग करता है।

इनलाइन sequence को वैयक्तिकृत करें

entry के data_schema में भेजे जाने वाले फ़ील्ड घोषित करें, फिर उन्हें $expr वैल्यू में trigger.data.<field> के रूप में पढ़ें। यह कॉल प्राप्तकर्ता को नाम से संबोधित करती है और उनकी अपॉइंटमेंट की पुष्टि या चिह्नित करती है:

{
  "from": "+12025550100",
  "to": "+12025550101",
  "sequence": {
    "entry_node_id": "start",
    "trigger_data": {
      "appointment_id": "apt_2048",
      "customer_name": "Sam",
      "appointment_time": "Tuesday at 10 AM"
    },
    "definition": {
      "schema_version": 1,
      "expression_environment": "bird.cel.v1",
      "nodes": [
        {
          "id": "start",
          "type": "trigger.start_call",
          "type_version": 1,
          "config": {
            "data_schema": {
              "type": "object",
              "additionalProperties": false,
              "required": ["appointment_id", "customer_name", "appointment_time"],
              "properties": {
                "appointment_id": { "type": "string", "minLength": 1 },
                "customer_name": { "type": "string", "minLength": 1 },
                "appointment_time": { "type": "string", "minLength": 1 }
              }
            }
          },
          "input": {},
          "connections": { "event": { "node_id": "confirm_menu", "port": "input" } }
        },
        {
          "id": "confirm_menu",
          "type": "voice.gather",
          "type_version": 1,
          "config": {},
          "input": {
            "prompts": [
              {
                "type": "say",
                "text": {
                  "$template": [
                    "Hello ",
                    { "$expr": "trigger.data.customer_name" },
                    ". Press 1 to confirm your appointment on ",
                    { "$expr": "trigger.data.appointment_time" },
                    ", or 2 if you need help."
                  ]
                },
                "language": "en"
              }
            ],
            "max_digits": 1,
            "timeout_seconds": 7,
            "inter_digit_timeout_seconds": 2,
            "finish_on_key": null,
            "private": false,
            "matches": { "confirm": "1", "help": "2" }
          },
          "connections": {
            "confirm": { "node_id": "confirmed", "port": "input" },
            "help": { "node_id": "help_requested", "port": "input" },
            "timeout": { "node_id": "no_response", "port": "input" },
            "fallback": { "node_id": "no_response", "port": "input" }
          }
        },
        {
          "id": "confirmed",
          "type": "logic.exit",
          "type_version": 1,
          "config": { "status": "succeeded", "reason": "appointment_confirmed" },
          "input": {
            "output": { "appointment_id": { "$expr": "trigger.data.appointment_id" } }
          }
        },
        {
          "id": "help_requested",
          "type": "logic.exit",
          "type_version": 1,
          "config": { "status": "succeeded", "reason": "appointment_help_requested" },
          "input": {
            "output": { "appointment_id": { "$expr": "trigger.data.appointment_id" } }
          }
        },
        {
          "id": "no_response",
          "type": "logic.exit",
          "type_version": 1,
          "config": { "status": "failed", "reason": "appointment_no_response" },
          "input": {
            "output": { "appointment_id": { "$expr": "trigger.data.appointment_id" } }
          }
        }
      ]
    }
  }
}

प्रत्येक exit के status और reason एक पुष्टि, सहायता अनुरोध, और कोई प्रतिक्रिया नहीं को अलग करते हैं। data_schema से मेल न खाने वाला trigger_data ऑब्जेक्ट सत्यापन में विफल होता है, जिसका स्थान /sequence/trigger_data के अंतर्गत होता है, और कोई कॉल नहीं लगाई जाती।

अनुरोध भेजें

आपने जो call.json सेव किया है, उसके लिए नीचे से एक अनुरोध विधि चुनें।

इस इच्छित कॉल के लिए एक बार एक नया, अद्वितीय idempotency key चुनें। फिर से प्रयास करने या कन्फ़र्मेशन रिकवरी के लिए उस key और मूल इनपुट को रखें। जब आप एक अलग नई कॉल करना चाहें, तो मूल कॉल के किसी भी अज्ञात परिणाम को हल करने के बाद दूसरी key चुनें।

शेल उदाहरणों के लिए, भेजने से पहले IDEMPOTENCY_KEY को अपने चुने हुए मान पर सेट करें। यदि यह सेट नहीं है या खाली है तो उदाहरण रुक जाते हैं; दोहराने पर वे दूसरी key नहीं बनाते।

HTTP के लिए, BIRD_API_KEY को अपनी key पर और BIRD_API_URL को इसके क्षेत्रीय बेस URL पर सेट करें, जैसे eu1 key के लिए https://eu1.platform.bird.com, फिर अनुरोध भेजें:

curl --request POST "$BIRD_API_URL/v1/voice/calls" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY:?Set IDEMPOTENCY_KEY to the saved key for this intended call}" \
  --data-binary @call.json

CLI प्रीव्यू के लिए, दोनों write अनुमतियों के साथ साइन इन करें और उसी फ़ाइल का उपयोग करके कॉल तैयार करें:

bird auth login --scope voice_management:write --scope voice:write
bird voice calls create --body-file call.json \
  --idempotency-key "${IDEMPOTENCY_KEY:?Set IDEMPOTENCY_KEY to the saved key for this intended call}"

कमांड एक ब्राउज़र समीक्षा लिंक प्रिंट करता है और पूर्ण होने की प्रतीक्षा करता है। लिंक खोलें, कॉलर, प्राप्तकर्ता, sequence, और entry डेटा जाँचें, और अनुरोध स्वयं चलाएँ। अनुरोध तैयार करने से कॉल नहीं लगती। कन्फ़र्मेशन बनाए बिना CLI अनुरोध का निरीक्षण करने के लिए --dry-run जोड़ें। यदि कन्फ़र्मेशन समाप्त, रद्द, या बिना रिकॉर्ड किए परिणाम के समाप्त हो जाता है, तो कमांड 5 से बाहर निकलता है; दूसरा अनुरोध करने से पहले फिर से प्रयास करने का मार्गदर्शन देखें।

MCP प्रीव्यू के लिए, call.json के फ़ील्ड और एक आवश्यक idempotency_key के साथ voice_calls_create को कॉल करें। <unique-key-for-this-request-reuse-for-retries> को अपनी चुनी हुई key से बदलें:

{
  "from": "+12025550100",
  "to": "+12025550101",
  "sequence": {
    "id": "YOUR_SEQUENCE_ID",
    "entry_node_id": "YOUR_ENTRY_NODE_ID",
    "trigger_data": {}
  },
  "idempotency_key": "<unique-key-for-this-request-reuse-for-retries>"
}

अनुरोध चलाने के लिए लौटाए गए ब्राउज़र समीक्षा लिंक का अनुसरण करें। डायनामिक MCP endpoint पर, execute के माध्यम से voice_calls_create चुनें। OAuth सहमति वर्कस्पेस अनुमतियाँ प्रदान करती है; ब्राउज़र समीक्षा इस विशिष्ट कॉल को चलाती है।

एक 202 Accepted प्रतिक्रिया स्वीकृति की पुष्टि करती है। प्राप्तकर्ता के उत्तर देने के बाद sequence शुरू होता है। स्वीकृति के बाद नया संस्करण प्रकाशित करने से इस कॉल की चयनित डेफ़िनिशन या entry डेटा नहीं बदलता।

स्वीकृति परिणाम पढ़ें

सहसंबंध के लिए प्रतिक्रिया के id, initial_leg_id, और sequence.run_id को बनाए रखें। शीर्ष-स्तरीय id कॉल को उसके सभी लेग्स में पहचानता है; initial_leg_id इसके पहले लेग को पहचानता है।

प्रतिक्रिया एक अपरिवर्तनीय स्वीकृति स्नैपशॉट है। इसके started_at और ended_at null हैं, अवलोकन बूलियन false हैं, और parties खाली है। ये फ़ील्ड स्वीकृति का वर्णन करते हैं, इसलिए जब आप अनुरोध दोहराते हैं तो ये लाइव स्थिति रिपोर्ट नहीं बनते।

प्रगति देखने के लिए सीक्वेंस का Runs खोलें। इनलाइन कॉल किसी सीक्वेंस से संबंधित नहीं होती, इसलिए उसकी leg को फ़ॉलो करें; अगर leg रजिस्टर होने से पहले विफल हो जाती है, तो अभी उसे निरीक्षण करने का कोई तरीका नहीं है। एक बार leg रिकॉर्ड बन जाने पर, initial_leg_id के साथ GET /v1/voice/legs/{leg_id} का उपयोग करें, या कॉल लॉग देखें। Legs पढ़ने के लिए voice:read अनुमति चाहिए, जो voice:write में शामिल है।

status rejected वाली leg कनेक्ट होने से पहले अस्वीकार कर दी गई थी, इसलिए इसका सीक्वेंस नहीं चला। बिना अस्वीकृति कारण के, दूसरे छोर ने कॉल अस्वीकार की; देखें अस्वीकृत कॉल।

CLI के साथ, bird voice calls get YOUR_CALL_ID कॉल और उसकी पार्टियाँ दिखाता है। bird voice legs trace YOUR_LEG_ID दिखाता है कि कौन-से स्टेप चले, gather प्राइवेट न होने पर एकत्र किए गए अंक, और exit की स्थिति व कारण। कॉल समाप्त होने के कुछ समय बाद ट्रेस तैयार हो जाता है; तब तक कमांड त्रुटि लौटाता है, इसलिए फिर से प्रयास करें। अस्वीकृत लेग का सीक्वेंस कभी नहीं चला, इसलिए उसका कोई ट्रेस नहीं भी हो सकता है।

स्वीकृति डायलिंग, उत्तर, या पठनीय कॉल रिकॉर्ड की गारंटी नहीं देती। पंजीकरण से पहले विफल होने वाली कॉल बिना लेग रिकॉर्ड के रन इतिहास में दिख सकती है। उत्तर दी गई कॉल भी यह स्थापित नहीं करती कि sequence ने अपना इच्छित व्यावसायिक कार्य पूरा किया।

त्रुटियाँ और फिर से प्रयास करना

सीधे HTTP अनुरोधों के लिए idempotency वैकल्पिक है। बिना key के, प्रत्येक अनुरोध एक नया कॉल प्रयास स्वीकार करता है। SDK स्वचालित फिर से प्रयासों के लिए key जनरेट करते हैं। अलग-अलग कॉल या सीधे HTTP अनुरोधों में फिर से प्रयासों की सुरक्षा के लिए, पहले प्रयास पर key दें और उसे मूल अनुरोध बाइट्स के साथ पुनः उपयोग करें। Idempotency गाइड देखें।

तीन घंटे के भीतर एक समान रीप्ले मूल स्वीकृति और Idempotency-Replay: true लौटाता है। उस key के साथ बदला हुआ इनपुट 409 लौटाता है। रीप्ले पर प्राधिकरण और कॉलिंग-नंबर अनुमति दोबारा जाँची जाती है। रीप्ले विंडो के बाद, key एक नई कॉल स्वीकार कर सकती है, इसलिए पुनः सबमिट करने से पहले मूल परिणाम का मिलान करें।

CLI और MCP के लिए, पहले प्रयास पर idempotency key दें। उसी अनुरोध और key को उसी OAuth अनुदान के साथ दोहराने पर मौजूदा कन्फ़र्मेशन लौटता है जब तक उसका रिकॉर्ड बना रहता है। मूल इनपुट और कन्फ़र्मेशन ID रखें। Key बदलने से एक और बिल योग्य कॉल तैयार हो सकती है।

यदि CLI कमांड बाधित हो जाए, तो मूल इनपुट, key, और लौटाई गई कन्फ़र्मेशन ID के साथ फिर से शुरू करें:

bird voice calls create --body-file call.json \
  --idempotency-key "${IDEMPOTENCY_KEY:?Set IDEMPOTENCY_KEY to the saved key for this intended call}" \
  --confirmation-id YOUR_CONFIRMATION_ID

MCP के लिए, लौटाई गई अनुरोध स्थिति के साथ मूल टूल आर्ग्युमेंट दोहराएँ, जिसमें वही idempotency_key शामिल हो। स्थिति कन्फ़र्मेशन की पहचान करती है और उन आर्ग्युमेंट का स्थान नहीं लेती। वैकल्पिक रूप से, bird/confirmation-id अनुरोध मेटाडेटा में लौटाई गई ID के साथ वही टूल और आर्ग्युमेंट दोहराएँ। डायनामिक MCP के साथ, वही execute अनुरोध दोहराएँ और उस पर वह मेटाडेटा डालें। फिर से शुरू करने पर मूल कन्फ़र्मेशन पढ़ा जाता है और पूर्ण होने पर उसका रिकॉर्ड किया गया परिणाम लौटाया जाता है।

Create Call कन्फ़र्मेशन 90 मिनट बाद समाप्त हो जाता है। बिना परिणाम वाला pending या expired कन्फ़र्मेशन यह प्रमाणित नहीं करता कि कॉल कभी नहीं लगी। दूसरी कॉल करने का निर्णय लेने से पहले मूल sequence रन और किसी भी कॉल-लेग रिकॉर्ड की जाँच करें; अज्ञात परिणाम हल करने के लिए नई key न बनाएँ। 202 परिणाम वाला एक पूर्ण कन्फ़र्मेशन स्वीकृति प्रमाणित करता है, इसलिए कॉल का परिणाम स्थापित करने के लिए स्वीकृति जाँचें जारी रखें।

अगले कदम

• Create Call API संदर्भ।
• Sequence entry डेटा परिभाषित करें।
• Sequence रन की जाँच करें।
• कॉल इवेंट प्राप्त करें।