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

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

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

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

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

1. בחרו מספר שמאפשר שיחות יוצאות

   השתמשו במספר שבבעלותכם דרך חיבור VoIP, או בקשו הרשאה להשתמש במספרי ThunderPhone שלכם לשיחות יוצאות מדף מספרי הטלפון. מספרי ThunderPhone מתחילים כמספרים לשיחות נכנסות בלבד. ThunderPhone בודקת כל בקשה ידנית; לאחר האישור, מספרים אלה יכולים לבצע שיחות עד למגבלה היומית שאושרה (המתאפסת ב-00:00 UTC) ולהריץ קמפיינים, ותוכלו לבקש מגבלה גבוהה יותר. למספרי VoIP של לקוחות אין מגבלה יומית, לכן אנו ממליצים עליהם לשיחות יוצאות. ראו הביאו מספרים משלכם.

2. צרו סוכן

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

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

   שיחות יוצאות מחזירות 402 Payment Required אם היתרה היא ≤ $0.00. טענו יתרה או הפעילו טעינה אוטומטית תחת ארגון → הגדרות חיוב בלוח הבקרה. מפתח ה-sk_live_ שלכם יכול לבדוק את היתרה באמצעות GET /v1/billing, אך אינו יכול לטעון יתרה או לשנות את הטעינה האוטומטית.

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

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

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

תגובה:

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

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

אם אתם רוצים הנחיה חד-פעמית שלא שווה לשמור כסוכן, העבירו במקום זאת config. המבנה תואם לסכמת התגובה של ה-webhook 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":   "+14155552671",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

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

במקביל, הירשמו ל-webhook של telephony.complete — הדרך המהירה ביותר לדעת ששיחה הסתיימה. אם אינכם יכולים לקבל webhooks נכנסים, בצעו polling ל-GET /v1/calls/{call_id} כל כמה שניות; הרשומה כוללת את end_reason, את duration_seconds ואת כתובת ה-URL של ההקלטה לאחר סיום השיחה.

אם הסוכן שלכם מוגדר לחלץ נתונים מובנים לאחר השיחה, נתונים אלה נמסרים בנפרד לאחר השלמת הסגירה.

העבירו משתנים לכל שיחה לסוכן שמור#

סוכנים שמורים יכולים להשתמש במצייני מקום כגון {{name}} או {{name|there}} בתוך טקסט ההנחיה. כשאתם מבצעים שיחה יוצאת עם agent_id, העבירו variables עם הערכים עבור אותה שיחה:

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}

השתמשו בערכי מחרוזת המקושרים לפי שם מציין המקום. משתנים אלה חלים על סוכנים שמורים; דוגמת ה-config המוטבעת במדריך זה אינה משתמשת בהם.

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

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

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

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

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

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

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