---
title: "בצעו שיחות יוצאות (API)"
description: "הפעילו שיחה יוצאת המונעת על ידי בינה מלאכותית מהקוד שלכם — עבור סקרים, מעקב או תהליכי אישור."
---

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

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

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

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

<Steps>
  <Step title="בחרו מספר שמאפשר שיחות יוצאות">
    השתמשו במספר שבבעלותכם דרך
    [חיבור VoIP](/api-reference/voip-connections), או בקשו הרשאה
    להשתמש במספרי ThunderPhone שלכם לשיחות יוצאות מדף מספרי הטלפון.
    מספרי ThunderPhone מתחילים כמספרים לשיחות נכנסות בלבד. ThunderPhone בודקת כל
    בקשה ידנית; לאחר האישור, מספרים אלה יכולים לבצע שיחות עד
    למגבלה היומית שאושרה (המתאפסת ב-00:00 UTC) ולהריץ קמפיינים, ותוכלו
    לבקש מגבלה גבוהה יותר. למספרי VoIP של לקוחות אין מגבלה יומית, לכן אנו ממליצים
    עליהם לשיחות יוצאות. ראו
    [הביאו מספרים משלכם](/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`. טענו יתרה או הפעילו טעינה אוטומטית תחת
    **ארגון → הגדרות חיוב** בלוח הבקרה. מפתח ה-`sk_live_`
    שלכם יכול לבדוק את היתרה באמצעות
    [`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`. המבנה תואם לסכמת התגובה של
ה-webhook [`call.incoming`](/he/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"
    }
  }'
```

## עקבו אחר השיחה

במקביל, הירשמו ל-[webhook של
`telephony.complete`](/he/webhooks/events) —
הדרך המהירה ביותר לדעת ששיחה הסתיימה. אם אינכם יכולים לקבל
webhooks נכנסים, בצעו polling ל-`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 ניתן להתקשר רק למספרים רגילים בארה״ב ובקנדה, ללא מספרי פרמיום. השדה `reason` מציין איזה מהם; ראו [יעדים חסומים](/api-reference/outbound-calls#blocked-destinations) |
| `409` עם `retryable: false` עבור מספר ThunderPhone | פעלו בהתאם ל-`code`: בקשו שיחות יוצאות בדף מספרי הטלפון, המתינו לביקורת ממתינה או השתמשו במספר זכאי אחר |
| `429` עם `code: platform_outbound_daily_limit_reached` | הארגון ניצל את מכסת השיחות היוצאות להיום ממספרי ThunderPhone. המתינו ל-`resets_at` ‏(00:00 UTC), בקשו מגבלה גבוהה יותר בדף מספרי הטלפון או התקשרו ממספר בחיבור 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` |
| `409` עם `retryable: false` עבור מספר VoIP של לקוח | תקנו את המצב המצוין ב-`code`; במקרה של כשלי אימות, הריצו את [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| התנגשות אידמפוטנטיות `409` | השתמשו שוב במפתח רק עם הבקשה המקורית והמנורמלת, או שלחו מפתח חדש |
| `404 from_number is not registered to this organization` | ודאו שה-`from_number` תואם למספר טלפון פעיל בארגון שלכם. מספר שכבר נמצא בתהליך הקצאה, נכשל, בתהליך שחרור או שוחרר יחזיר גם הוא תגובה זו |
| `500` עם שדה `detail` בלבד | לא מוגדר קו יוצא. פנו לתמיכה; זו אינה בעיית מצב מספר שתוכלו לתקן |
| `502 Bad Gateway` | כשל זמני ב-SIP / LiveKit; בטוח לנסות שוב |

עיינו ב[הפניה לשיחות יוצאות](/api-reference/outbound-calls#error-responses)
לרשימה המלאה והיציבה של קודי זכאות ולשני מבני התגובה של `409`.
אם מספר פעיל הופך ללא זכאי לאחר שהבקשה התקבלה אך לפני
שהשיחה מבוצעת, הבדיקה הסופית מחזירה מטען `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="/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>