Developer cookbook

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

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

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

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

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

1. צרו סוכן#

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

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:

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. מספרי הדגמה מתחילים ב-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, כך שהמספר יהיה מוכן גם להוצאת שיחות.

4. קבלו שיחה#

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

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

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"

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

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