---
title: "آؤٹ باؤنڈ کالز کریں (API)"
description: "اپنے کوڈ سے AI کے ذریعے آؤٹ باؤنڈ کال شروع کریں — سروے، فالو اَپ، یا تصدیقی فلوز کے لیے۔"
---

آؤٹ باؤنڈ کالنگ آپ کو ThunderPhone کو منزل کا نمبر اور ایجنٹ
کنفیگریشن دینے اور AI سے آپ کی جانب سے کال کروانے دیتی ہے۔ عام استعمال کے معاملات:

- اپائنٹمنٹ کی تصدیقیں
- سروے کے لیے واپسی کالز
- مسڈ کال کے بعد "دوسری کوشش" کے فالو اپس
- ڈسپیچ طرز کی اطلاعات

<Note>
  پوری فہرست کو کال کرنی ہے؟ ڈیش بورڈ کا
  [**مہمات**](/ur/guides/outbound-campaigns) فیچر
  (`/dashboard/campaigns`) رابطوں کی CSV لیتا ہے اور آپ کے لیے
  ٹائم زون کے مطابق کالنگ ونڈوز، کنکرنسی، اور دوبارہ کوشش کی پالیسی
  سنبھالتا ہے۔ یہ گائیڈ واحد پروگراماتی کالز کا احاطہ کرتی ہے۔
</Note>

## پیشگی شرائط

<Steps>
  <Step title="ایک VoIP نمبر فراہم کریں">
    آؤٹ باؤنڈ کالنگ کے لیے ضروری ہے کہ آپ `from_number` کے مالک ہوں، جو
    ایک [VoIP کنکشن](/api-reference/voip-connections) کے ذریعے ہو۔ ThunderPhone نمبرز
    صرف اِن باؤنڈ کے لیے ہیں۔ ملاحظہ کریں
    [اپنے نمبرز فراہم کریں](/ur/guides/bring-your-own-numbers)۔
  </Step>
  <Step title="ایک ایجنٹ بنائیں">
    آؤٹ باؤنڈ طرز کا prompt عموماً ایجنٹ کے اپنے تعارف اور مقصد بیان کرنے سے شروع ہوتا ہے
    — "Hi, this is Acme calling to
    confirm your appointment for tomorrow at 3pm…" `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
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
{ "call_id": 987654321, "status": "initiated" }
```

<Warning>
  `status: "initiated"` کا صرف یہ مطلب ہے کہ درخواست قبول کر لی گئی — کال
  **ابھی منسلک نہیں ہوئی**۔ براہ راست اسٹیٹس کے لیے
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  کو پول کریں (`in_progress` → `completed` / `failed`)۔
</Warning>

## اِن لائن کنفیگ کے ساتھ کال کریں

اگر آپ کو ایک بار استعمال ہونے والا ایسا prompt چاہیے جسے ایجنٹ کے طور پر محفوظ کرنا مناسب نہ ہو،
تو اس کے بجائے `config` پاس کریں۔ اس کی ساخت
[`call.incoming` ویب ہک](/ur/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":   "+14155550199",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'
```

## کال کی پیروی کریں

متوازی طور پر
[`telephony.complete` ویب ہک](/ur/webhooks/events) کو سبسکرائب کریں —
یہ جاننے کا تیز ترین طریقہ ہے کہ کال مکمل ہو گئی ہے۔ اگر آپ اِن باؤنڈ
ویب ہکس قبول نہیں کر سکتے، تو ہر چند سیکنڈ بعد `GET /v1/calls/{call_id}` کو پول کریں؛
کال ختم ہونے پر ریکارڈ میں `end_reason`، `duration_seconds`، اور ریکارڈنگ URL شامل ہوتے ہیں۔

## وہ ناکامی کی صورتیں جنہیں سنبھالنا ضروری ہے

| خرابی | حل |
|-------|-----|
| `402 Payment Required` | بیلنس بڑھائیں یا آٹو ری لوڈ فعال کریں |
| `403` آؤٹ باؤنڈ بلاک ہے (ThunderPhone نمبر) | اس کے بجائے 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
{
  "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="/ur/webhooks/call-complete">
    مکمل شدہ آؤٹ باؤنڈ کالز کو اپنے سسٹم میں اسٹریم کریں۔
  </Card>
  <Card title="بلنگ" icon="credit-card" href="/api-reference/billing">
    آٹو ری لوڈ، تاکہ بیلنس کی وجہ سے آؤٹ باؤنڈ کبھی ناکام نہ ہو۔
  </Card>
  <Card title="آؤٹ باؤنڈ ایجنٹس کی جانچ کریں" icon="flask" href="/ur/guides/test-agents">
    پروڈکشن سے پہلے اپنے آؤٹ باؤنڈ ایجنٹ کا ڈرائی رن کریں۔
  </Card>
</CardGroup>