Developer cookbook

הביאו מספרים משלכם (VoIP, API)

חברו את Twilio או Telnyx — או כל קו SIP — ייבאו את מספרי הטלפון שכבר בבעלותכם, ותנו לסוכני ThunderPhone לענות לשיחות ולהוציא שיחות באמצעותם.

מספרי הדגמה מתאימים לאב־טיפוס, אך תעבורת ייצור צריכה להשתמש במספרים שבבעלותכם דרך ספק ה-VoIP שלכם. מדריך זה מוביל אתכם בתהליך בן שלושה שלבים: בדיקת אישורים → יצירת חיבור → ייבוא מספרים → אימות.

ספקים נתמכים#

1. בדיקת אישורים#

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

curl -X POST https://api.thunderphone.com/v1/voip-connections/test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider":    "telnyx",
    "credentials": { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":  { "domain": "acme.sip.telnyx.com" }
  }'

{
  "status": "pass",
  "verification_evidence_id": "b9a2...",
  "suggested_connection_name": "Telnyx: Acme Main (+15550001234)",
  "checks": {
    "credentials_valid": true,
    "inbound_reachable": true,
    "outbound_authorized": true
  }
}

אם בדיקה כלשהי נכשלת, ערך התגובה status יהיה fail, ו-checks יציג איזה שלב נכשל. תקנו את תצורת צד הספק (הקצאת trunk, רשימת היתרי IP, הרשאת שיחות יוצאות) ונסו שוב.

2. יצירת החיבור#

העבירו את ה-verification_evidence_id שקיבלתם כעת:

curl -X POST https://api.thunderphone.com/v1/voip-connections \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":         "Acme Telnyx Main",
    "provider":     "telnyx",
    "setup_method": "api_key",
    "credentials":  { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":   { "domain": "acme.sip.telnyx.com" },
    "verification_evidence_id": "b9a2..."
  }'

התגובה היא אובייקט VoipConnection עם status="connected". האישורים נשמרים בצד השרת ולעולם אינם מוחזרים כטקסט גלוי בבקשות GET עוקבות — כדי לבצע רוטציה, הריצו test חדש ושלחו PATCH עם הראיה החדשה.

3. הצגת מספרים וייבואם#

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

curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

לאחר מכן ייבאו את המספרים הרצויים:

curl -X POST https://api.thunderphone.com/v1/voip-connections/5/import-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["+15550001234", "+15550009999"]}'

כל ייבוא הופך למשאב מספר טלפון בארגון שלכם עם source="voip" ו-status="provisioning".

4. אמתו כל מספר שיובא#

הייבוא רושם את המספר כ-זמין; ניתוב שיחות בפועל דרכו דורש אימות. עבור חיבורי ספקים (Twilio, Telnyx), הפעולה בודקת מחדש את אישורי הספק ואת נגישות ה-SIP. עבור חיבור SIP ידני, היא מבצעת שיחת בדיקה קצרה (כמה שניות, מנותקת אוטומטית) מהמספר, דרך קו ה-SIP שלכם, אל מספר ThunderPhone — כך ששם המשתמש, הסיסמה, התעבורה והניתוב היוצא של הקו מוכחים בפועל. הספק שלכם מחייב אתכם על השיחה הזו כמו על כל שיחה אחרת.

curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

במקרה של הצלחה, voip_verification_status משתנה ל-verified והמספר נכנס למצב status="active". במקרה של כישלון, התגובה מפרטת מה נכשל — עבור קו ידני זו תשובת ה-SIP של הספק, לדוגמה "דחה את האישורים של ThunderPhone ‏(SIP 401)" או "לא ניתן לנתב שיחה ‏(SIP 404)" — תקנו את הבעיה (אישורים, כתובות IP של מקור מורשה, הקצאת קו חסרה בלוח הבקרה של הספק) והתקשרו שוב.

5. הקצו סוכנים וקבלו שיחה#

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

החלפת אישורים#

כאשר מפתח ספק מוחלף, הריצו מחדש את תהליך הבדיקה ולאחריה העדכון:

# 1. Test the new credentials
curl -X POST https://api.thunderphone.com/v1/voip-connections/test ...
 
# 2. PATCH the connection with the new evidence
curl -X PATCH https://api.thunderphone.com/v1/voip-connections/{id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": { "apiKey": "NEW_KEY..." },
    "verification_evidence_id": "fresh-evidence-id"
  }'

החיבור נשאר במקומו — אין צורך לייבא מחדש מספרים.

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