טיפול בשיחות נכנסות (API)

מקצה לקצה: הגדירו סוכן, הקצו אותו למספר טלפון, קבלו שיחה ובדקו את התמלול.

התהליך המקובל של "מענה לטלפון באמצעות AI", ישירות מהמסוף שלכם. אתם תבצעו:

1. צרו סוכן עם הנחיה וקול.
2. הקצו (או הביאו) מספר טלפון והגדירו את הסוכן כמטפל בשיחות הנכנסות שלו.
3. חייגו למספר. עקבו אחר יומן השיחות, התמליל וההקלטה.

סך קריאות ה-API: ארבע. זמן כולל: פחות מחמש דקות.

1. יצירת סוכן#

סוכן מאגד את ההנחיה, הקול ורמת המוצר שיפעילו את השיחה. תוכלו גם להגדיר לסוכן מגבלות שיחה כגון max_call_duration_seconds ו-ring_duration_seconds. סוכנים תומכים גם ב-intro_clip וב-intro_ring_count כדי להשמיע פתיח שהוקלט מראש ועד שתי צלצולים לפני שהסוכן מדבר. סוכנים חדשים זקוקים גם לאזור זמן. אם הסוכן שלכם רב-לשוני, תוכלו להגדיר את language_switching כדי לקבוע אם הוא ישאל לפני החלפת שפות או יפעל לפי שפת המתקשר. ראו סוכנים עבור כל שדות התצורה; המינימום הוא:

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'

שמרו את ה-id המוחזר — תזדקקו לו בשלב 2.

2. קבלת מספר טלפון#

אם אתם זקוקים רק למספר שאפשר לחייג אליו, קבלו מספר ThunderPhone ממאגר ThunderPhone:

curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

התשובה כוללת id ו-number בפורמט E.164. מספרי ThunderPhone מתחילים ב-status="provisioning" והופכים ל-active בתוך כמה שניות — בצעו בקשות חוזרות אל GET /v1/phone-numbers/{id} כדי לעקוב אחר המעבר, אם חשוב לכם.

3. שיוך הסוכן#

קשרו את הסוכן משלב 1 להגדרת השיחות הנכנסות של המספר:

curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

זה הכול — המספר פעיל. לאחר אישור שיחות יוצאות עבור הארגון שלכם, תוכלו גם להגדיר outbound_agent_id באותו PATCH. עד אז, ה-API דוחה את השיוך הזה עם 400.

אם אתם מנתבים שיחות נכנסות דרך webhook של תצורה במקום inbound_agent_id קבוע, ה-webhook יכול כעת להחזיר timezone לכל שיחה יחד עם agent_id ו-variables.

4. קבלת שיחה#

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

בזמן שהשיחה בעיצומה, היא מופיעה ב- GET /v1/calls עם status="in_progress". כשהיא מסתיימת, הרשומה מתעדכנת עם end_reason, duration_seconds, billable_minutes, ובסופו של דבר כתובת URL של הקלטה וציון AI.

שיחות נכנסות נספרות במסגרת מגבלת השיחות המקבילות של הארגון שלכם (20 שיחות בתהליך כברירת מחדל, המשותפות לשיחות יוצאות, שיחות ווב ושיחות בדיקה). שיחה שמגיעה בעת הגעה למגבלה נדחית ומנותקת לפני שהסוכן עונה, אינה מחויבת, ונרשמת כשיחה שנכשלה עם סיבת סיום concurrent_call_limit_reached. שלחו אימייל ל-support@thunderphone.com אם אתם זקוקים למגבלה גבוהה יותר.

5. בדקו את התוצאות#

אחזרו את רשימת השיחות האחרונות:

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

אחזרו את התמלול:

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

ואת כתובת ה-URL של ההקלטה (קצרת-תוקף, חתומה):

curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

אם נרשמתם ל-Webhook של telephony.complete, תקבלו את אותם הנתונים כבקשת POST לשרת שלכם — ראו call.complete.

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

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