> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# आउटबाउंड कॉल करें (API)

> अपने कोड से AI-संचालित आउटबाउंड कॉल ट्रिगर करें — सर्वे, फॉलो-अप या पुष्टि फ़्लो के लिए।

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

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

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

## आवश्यक शर्तें

<Steps>
  <Step title="एक VoIP नंबर लाएँ">
    आउटबाउंड कॉलिंग के लिए आपका `from_number` किसी
    [VoIP कनेक्शन](/api-reference/voip-connections) के माध्यम से आपका अपना होना
    चाहिए। डेमो नंबर केवल इनबाउंड के लिए हैं। देखें
    [अपने नंबर लाएँ](/hi/guides/bring-your-own-numbers)।
  </Step>

  <Step title="एक एजेंट बनाएँ">
    आउटबाउंड-उन्मुख प्रॉम्प्ट आमतौर पर एजेंट के अपना परिचय और उद्देश्य
    बताने से शुरू होता है — "नमस्ते, मैं Acme से बोल रहा हूँ और कल दोपहर 3 बजे के आपके अपॉइंटमेंट की पुष्टि करने के लिए कॉल कर रहा हूँ…" `outbound_speak_order` को `agent_first` पर सेट करें (डिफ़ॉल्ट)।
  </Step>

  <Step title="पॉज़िटिव बैलेंस बनाए रखें">
    यदि बैलेंस ≤ `$0.00` है, तो आउटबाउंड कॉल `402 Payment Required` लौटाती हैं।
    इसके माध्यम से टॉप अप करें
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    या [ऑटो-रीलोड](/api-reference/billing#update-auto-reload) सक्षम करें।
  </Step>
</Steps>

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

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

```bash theme={null}
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":   "+14155550199",
    "agent_id":    12
  }'
```

रिस्पॉन्स:

```json theme={null}
{ "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` वेबहुक](/hi/webhooks/call-incoming) के रिस्पॉन्स स्कीमा से मेल खाता है:

```bash theme={null}
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":   "+14155550199",
    "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 शामिल होते हैं।

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

| एरर                                                      | समाधान                                                                                                       |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `402 Payment Required`                                   | बैलेंस टॉप अप करें या ऑटो-रीलोड सक्षम करें                                                                   |
| `403` आउटबाउंड ब्लॉक्ड (डेमो नंबर)                       | इसके बजाय VoIP नंबर लाएँ                                                                                     |
| `403` आउटबाउंड ब्लॉक्ड (अनवेरिफ़ाइड VoIP)                | [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) चलाएँ |
| `404 from_number is not registered to this organization` | पुष्टि करें कि `from_number` आपके स्वामित्व वाले फ़ोन नंबर से मेल खाता है                                    |
| `502 Bad Gateway`                                        | अस्थायी SIP / LiveKit फेल्योर; रिट्राई करना सुरक्षित है                                                      |

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

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

```json theme={null}
{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "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>