> ## 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)

> הפעילו שיחה יוצאת המונעת על ידי בינה מלאכותית מהקוד שלכם — עבור סקרים, המשך טיפול או תהליכי אישור.

שיחות יוצאות מאפשרות לכם למסור ל-ThunderPhone מספר יעד ותצורת סוכן,
ולבקש מה-AI לבצע את השיחה בשמכם. תרחישי שימוש נפוצים:

* אישורי פגישות
* שיחות חוזרות לסקרים
* מעקבי "ניסיון שני" לאחר שיחה שלא נענתה
* התראות בסגנון שיגור

<Note>
  מתקשרים לרשימה שלמה? התכונה
  [**קמפיינים**](/he/guides/outbound-campaigns) בלוח הבקרה
  (`/dashboard/campaigns`) מקבלת CSV של אנשי קשר ומטפלת עבורכם
  בחלונות חיוג מותאמים לאזור זמן, במקביליות ובמדיניות ניסיונות חוזרים.
  מדריך זה עוסק בשיחות תוכנתיות בודדות.
</Note>

## דרישות מוקדמות

<Steps>
  <Step title="הביאו מספר VoIP">
    שיחות יוצאות מחייבות אתכם להיות הבעלים של `from_number` דרך
    [חיבור VoIP](/api-reference/voip-connections). מספרי הדגמה
    מיועדים לשיחות נכנסות בלבד. ראו
    [הביאו מספרים משלכם](/he/guides/bring-your-own-numbers).
  </Step>

  <Step title="צרו סוכן">
    הנחיה המותאמת לשיחות יוצאות נוטה להתחיל בכך שהסוכן
    מזדהה ומציג את מטרתו — "שלום, כאן Acme, ואנו מתקשרים כדי
    לאשר את הפגישה שלכם למחר בשעה 15:00…". הגדירו את
    `outbound_speak_order` לערך `agent_first` (ברירת המחדל).
  </Step>

  <Step title="שמרו על יתרה חיובית">
    שיחות יוצאות מחזירות `402 Payment Required` אם היתרה היא ≤
    `$0.00`. טענו יתרה באמצעות
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    או הפעילו [טעינה אוטומטית](/api-reference/billing#update-auto-reload).
  </Step>
</Steps>

## בצעו שיחה עם סוכן שמור

הדרך הפשוטה ביותר — הפניה לסוכן לפי מזהה:

```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`](/he/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`](/he/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="/he/webhooks/call-complete">
    הזרימו שיחות יוצאות שהסתיימו למערכת שלכם.
  </Card>

  <Card title="חיוב" icon="credit-card" href="/api-reference/billing">
    טעינה אוטומטית כדי ששיחות יוצאות לא ייכשלו בגלל יתרה.
  </Card>

  <Card title="בדיקת סוכנים יוצאים" icon="flask" href="/he/guides/test-agents">
    הריצו בדיקה ללא ביצוע של הסוכן היוצא שלכם לפני ייצור.
  </Card>
</CardGroup>