---
title: "आउटबाउंड कॉल करें (API)"
description: "अपने कोड से AI-संचालित आउटबाउंड कॉल ट्रिगर करें — सर्वे, फॉलो-अप या कन्फर्मेशन फ्लो के लिए।"
---

आउटबाउंड कॉलिंग से आप ThunderPhone को एक डेस्टिनेशन नंबर और एजेंट कॉन्फ़िगरेशन दे सकते हैं, ताकि AI आपकी ओर से कॉल कर सके। सामान्य उपयोग के मामले:

- अपॉइंटमेंट कन्फर्मेशन
- सर्वे कॉलबैक
- मिस्ड कॉल के बाद "दूसरी कोशिश" वाले फॉलो-अप
- डिस्पैच-शैली के नोटिफिकेशन

<Note>
  पूरी सूची पर कॉल करना है? डैशबोर्ड का
  [**कैम्पेन**](/hi/guides/outbound-campaigns) फीचर
  (`/dashboard/campaigns`) कॉन्टैक्ट्स की CSV लेता है और आपके लिए
  टाइमज़ोन-अनुकूल कॉलिंग विंडो, कॉन्करेंसी और रीट्राई पॉलिसी संभालता है।
  यह गाइड एकल प्रोग्रामैटिक कॉल के बारे में है।
</Note>

## आवश्यकताएँ

<Steps>
  <Step title="आउटबाउंड-सक्षम नंबर चुनें">
    अपने स्वामित्व वाले नंबर का उपयोग
    [VoIP कनेक्शन](/api-reference/voip-connections) के माध्यम से करें, या Phone Numbers
    पेज से अपने ThunderPhone नंबरों को आउटबाउंड कॉल के लिए उपयोग करने की अनुमति का अनुरोध करें।
    ThunderPhone नंबर शुरुआत में केवल इनबाउंड होते हैं। ThunderPhone हर
    अनुरोध की मैन्युअल समीक्षा करता है; स्वीकृति मिलने के बाद, वे नंबर स्वीकृत दैनिक सीमा तक
    कॉल कर सकते हैं (जो 00:00 UTC पर रीसेट होती है) और कैंपेन चला सकते हैं, और आप
    अधिक सीमा का अनुरोध कर सकते हैं। ग्राहक VoIP नंबरों की कोई दैनिक सीमा नहीं होती, इसलिए हम
    आउटबाउंड कॉलिंग के लिए उनकी अनुशंसा करते हैं। देखें
    [अपने नंबर लाएँ](/hi/guides/bring-your-own-numbers)।
  </Step>
  <Step title="एजेंट बनाएं">
    आउटबाउंड-उन्मुख प्रॉम्प्ट आमतौर पर एजेंट के
    अपना और अपने उद्देश्य का परिचय देने से शुरू होता है — "नमस्ते, Acme बोल रहा है,
    कल दोपहर 3 बजे के लिए आपकी अपॉइंटमेंट की पुष्टि करने के लिए कॉल कर रहा हूँ…" 
    `outbound_speak_order` को `agent_first` (डिफ़ॉल्ट) पर सेट करें।
  </Step>
  <Step title="पॉज़िटिव बैलेंस बनाए रखें">
    बैलेंस ≤
    `$0.00` होने पर आउटबाउंड कॉल `402 Payment Required` लौटाती हैं। डैशबोर्ड में
    **संगठन → बिलिंग सेटिंग्स** के अंतर्गत टॉप अप करें या ऑटो-रीलोड सक्षम करें। आपकी `sk_live_`
    key
    [`GET /v1/billing`](/api-reference/billing#get-billing-account) से बैलेंस जाँच सकती है, लेकिन
    टॉप अप नहीं कर सकती या ऑटो-रीलोड बदल नहीं सकती।
  </Step>
</Steps>

## सेव किए गए एजेंट के साथ कॉल करें

सबसे सरल तरीका — किसी एजेंट को id से रेफ़रेंस करें:

```bash
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155552671",
    "agent_id":    12
  }'
```

रिस्पॉन्स:

```json
{ "call_id": 987654321, "status": "initiated" }
```

<Warning>
  `status: "initiated"` का मतलब केवल इतना है कि अनुरोध स्वीकार कर लिया गया है — कॉल
  **अभी कनेक्ट नहीं हुई है**। लाइव स्टेटस के लिए
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  को पोल करें (`in_progress` → `completed` / `failed`)।
</Warning>

## इनलाइन कॉन्फ़िग के साथ कॉल करें

अगर आपको एक बार का ऐसा प्रॉम्प्ट चाहिए जिसे एजेंट के रूप में सेव करना उचित नहीं है,
तो इसके बजाय `config` पास करें। इसका स्वरूप
[`call.incoming` webhook](/hi/webhooks/call-incoming) के
रिस्पॉन्स स्कीमा से मेल खाता है:

```bash
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155552671",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'
```

## कॉल को ट्रैक करें

समानांतर रूप से,
[`telephony.complete` वेबहुक](/hi/webhooks/events) को सब्सक्राइब करें —
कॉल समाप्त होने का पता लगाने का सबसे तेज़ तरीका। यदि आप इनबाउंड
वेबहुक स्वीकार नहीं कर सकते, तो हर कुछ सेकंड में `GET /v1/calls/{call_id}` को पोल करें; कॉल समाप्त होने पर
रिकॉर्ड में `end_reason`, `duration_seconds`, और रिकॉर्डिंग
URL शामिल होता है।

यदि आपका एजेंट कॉल के बाद स्ट्रक्चर्ड डेटा एक्सट्रैक्ट करने के लिए सेट अप है,
तो फाइनलाइज़ेशन पूरा होने के बाद वह डेटा अलग से डिलीवर किया जाता है।

### सेव किए गए एजेंट को प्रति-कॉल वेरिएबल पास करें

सेव किए गए एजेंट प्रॉम्प्ट टेक्स्ट में `{{name}}` या `{{name|there}}` जैसे प्लेसहोल्डर का उपयोग कर सकते हैं।
जब आप `agent_id` के साथ आउटबाउंड कॉल करते हैं, तो उस कॉल के मानों के साथ
`variables` पास करें:

```json
{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}
```

प्लेसहोल्डर नाम से की गई स्ट्रिंग वैल्यू का उपयोग करें। ये वेरिएबल
सेव किए गए एजेंट पर लागू होते हैं; इस गाइड का इनलाइन `config` उदाहरण इनका उपयोग नहीं करता।

## हैंडल करने योग्य फेल्योर मोड

| त्रुटि | समाधान |
|-------|-----|
| `402 Payment Required` | बैलेंस टॉप अप करें या ऑटो-रीलोड सक्षम करें |
| `400` के साथ `code: destination_not_allowed` | ThunderPhone उस नंबर पर कॉल नहीं करता: अमान्य नंबर, आपातकालीन नंबर, प्रीमियम-रेट नंबर, शॉर्ट कोड या प्रतिबंधित देशों के नंबर। ThunderPhone नंबरों से केवल सामान्य US और कनाडाई नंबरों पर कॉल की जा सकती है (प्रीमियम-रेट नहीं)। `reason` बताता है कि कौन-सा; [ब्लॉक किए गए डेस्टिनेशन](/api-reference/outbound-calls#blocked-destinations) देखें |
| ThunderPhone नंबर के लिए `retryable: false` के साथ `409` | `code` का पालन करें: Phone Numbers पेज पर आउटबाउंड कॉलिंग का अनुरोध करें, लंबित रिव्यू की प्रतीक्षा करें या कोई अन्य योग्य नंबर इस्तेमाल करें |
| `429` के साथ `code: platform_outbound_daily_limit_reached` | संगठन ने ThunderPhone नंबरों से आज की आउटबाउंड कॉल सीमा इस्तेमाल कर ली है। `resets_at` (00:00 UTC) तक प्रतीक्षा करें, Phone Numbers पेज पर अधिक सीमा का अनुरोध करें या अपने VoIP कनेक्शन के किसी नंबर से कॉल करें |
| `429` के साथ `code: concurrent_call_limit_reached` | संगठन में उतनी ही कॉल प्रगति पर हैं जितनी उसकी [कन्करेंट-कॉल सीमा](/api-reference/introduction#call-limits) है (डिफ़ॉल्ट रूप से 20, जिसमें इनबाउंड, आउटबाउंड, वेब और टेस्ट कॉल शामिल हैं)। `Retry-After` हेडर के सेकंड बीतने के बाद या कोई कॉल समाप्त होने पर फिर प्रयास करें; सीमा बढ़ाने के लिए support@thunderphone.com पर ईमेल करें |
| `429` के साथ `code: same_number_too_soon` | आपने उसी `to_number` पर 10 सेकंड से कम समय पहले कॉल किया था। `Retry-After` हेडर के सेकंड बीतने के बाद फिर प्रयास करें |
| ग्राहक के VoIP नंबर के लिए `retryable: false` के साथ `409` | `code` द्वारा बताई गई स्थिति ठीक करें; वेरिफिकेशन विफल होने पर [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) चलाएँ |
| `409` idempotency कॉन्फ्लिक्ट | कुंजी का दोबारा उपयोग केवल मूल नॉर्मलाइज़्ड रिक्वेस्ट के साथ करें या नई कुंजी भेजें |
| `404 from_number is not registered to this organization` | पुष्टि करें कि `from_number` आपके संगठन के सक्रिय फ़ोन नंबर से मेल खाता है। जो नंबर पहले से प्रोविज़निंग में है, विफल है, रिलीज़ हो रहा है या रिलीज़ हो चुका है, वह भी यही रिस्पॉन्स लौटाता है |
| केवल `detail` फ़ील्ड के साथ `500` | कोई आउटबाउंड ट्रंक कॉन्फ़िगर नहीं है। सहायता टीम से संपर्क करें; यह नंबर-स्थिति की ऐसी समस्या नहीं है जिसे आप ठीक कर सकते हैं |
| `502 Bad Gateway` | अस्थायी SIP / LiveKit विफलता; फिर प्रयास करना सुरक्षित है |

स्थिर एलिजिबिलिटी-कोड की पूरी सूची और दोनों `409` रिस्पॉन्स शेप के लिए
[आउटबाउंड कॉल्स रेफरेंस](/api-reference/outbound-calls#error-responses) देखें।
यदि रिक्वेस्ट स्वीकार होने के बाद लेकिन कॉल किए जाने से पहले कोई सक्रिय नंबर अयोग्य हो जाता है,
तो अंतिम जाँच गैर-रिट्राएबल `409` पेलोड लौटाती है।

## होल्ड समय नियंत्रित करना

रिसीवर के धीमे जवाब देने के कारण लंबे चलने वाली आउटबाउंड कॉल
(IVR ट्री, क्यू) को `max_hold_seconds` के साथ सीमित किया जा सकता है:

```json
{
  "from_number": "+15551234567",
  "to_number":   "+14155552671",
  "agent_id":    12,
  "max_hold_seconds": 120
}
```

यदि पिछले N सेकंड में कोई मानव ऑडियो प्राप्त नहीं हुआ है, तो एजेंट कॉल समाप्त कर देता है। डिफ़ॉल्ट 900 सेकंड (15 मिनट) है।

---

## अगले चरण

<CardGroup cols={2}>
  <Card title="आउटबाउंड कॉल्स रेफरेंस" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    हर रिक्वेस्ट फ़ील्ड और त्रुटि कोड।
  </Card>
  <Card title="call.complete प्राप्त करें" icon="bolt" href="/hi/webhooks/call-complete">
    पूरी हुई आउटबाउंड कॉल को अपने सिस्टम में स्ट्रीम करें।
  </Card>
  <Card title="बिलिंग" icon="credit-card" href="/api-reference/billing">
    ऑटो-रीलोड करें ताकि बैलेंस के कारण आउटबाउंड कभी फेल न हो।
  </Card>
  <Card title="आउटबाउंड एजेंट का टेस्ट करें" icon="flask" href="/hi/guides/test-agents">
    प्रोडक्शन से पहले अपने आउटबाउंड एजेंट का ड्राई रन करें।
  </Card>
</CardGroup>