Developer cookbook

ביצוע שיחות יוצאות (API)

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

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

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

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

1. הביאו מספר VoIP

   שיחות יוצאות מחייבות אתכם להיות הבעלים של from_number דרך חיבור VoIP. מספרי הדגמה מיועדים לשיחות נכנסות בלבד. ראו הביאו מספרים משלכם.

2. צרו סוכן

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

3. שמרו על יתרה חיובית

   שיחות יוצאות מחזירות 402 Payment Required אם היתרה היא ≤ $0.00. טענו יתרה באמצעות POST /v1/billing/top-up או הפעילו טעינה אוטומטית.

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

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

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
  }'

תגובה:

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

בצעו שיחה עם תצורה מוטמעת#

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

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 — זו הדרך המהירה ביותר לדעת ששיחה הסתיימה. אם אינכם יכולים לקבל וובהוקים נכנסים, בצעו בדיקה מחזורית של GET /v1/calls/{call_id} כל כמה שניות; הרשומה כוללת את end_reason, את duration_seconds ואת כתובת ה-URL של ההקלטה לאחר שהשיחה מסתיימת.

מצבי כשל שכדאי לטפל בהם#

שליטה בזמן ההמתנה#

ניתן להגביל שיחות יוצאות שמתארכות משום שהצד המתקשר מגיב לאט (עצי IVR, תורים) באמצעות max_hold_seconds:

{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}

הסוכן מנתק אם לא התקבל שמע אנושי ב-N השניות האחרונות. ברירת המחדל היא 900 (15 דקות).

השלבים הבאים#