ThunderPhone v3 כבר באוויר.בשירות עצמי, החל מ-2¢/דקה.קראו את הודעת ההשקה

Developer cookbook

הפעילו שיחות מ-Slack או מאפליקציית צ׳אט

בנו בוט משלכם עבור Slack, Teams או צ׳אט אינטרנטי שמתחיל שיחות, עוקב אחריהן בזמן אמת, מכוון את הסוכן ועונה על שאלותיו, באמצעות ה-API הציבורי.

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

ThunderPhone לא מארחת את הבוט הזה עבורכם. אתם (או סוכן הקוד שלכם) בונים שרת קטן שמחבר את אפליקציית הצ'אט שלכם ל-API הציבורי. דף זה מציג את הרכיבים. הם זהים עבור Slack, Microsoft Teams, Discord או דף צ'אט פרטי באינטרנט; הדוגמאות משתמשות ב-Slack.

איך הכול משתלב

מה אתם עושים בצ'אטמה הבוט שלכם קוראמה קורה
שולחים "התקשרו ל-Comcast ובררו את זמן ההגעה המשוער לתיקון התקלה"POST /v1/call עם ההודעה בתור contextהסוכן מחייג. הבוט שלכם פותח שרשור עבור השיחה
עוקבים אחר השרשורמקבל webhooks מסוג telephony.turnכל שורה שהסוכן או האדם השני אומרים מופיעה בשרשור
מגיבים בשרשור במהלך השיחהPOST /v1/calls/{call_id}/whisperהסוכן מקבל את ההערה שלכם באופן פרטי ופועל לפיה. האדם השני לעולם לא שומע אותה
עונים על שאלת הסוכןנקודת הקצה של הכלי שלכם מחזירה את תשובתכם, או שולחת אותה מאוחר יותר באמצעות POST /v1/calls/{call_id}/tool-resultsהסוכן ממשיך את השיחה עם התשובה; במצב המתנה האדם השני שומע מוזיקת המתנה בינתיים
קוראים את התוצאהמקבל webhooks מסוג telephony.completeהבוט שלכם מפרסם את הסיכום והתוצאה

הבוט שלכם שומר מיפוי אחד: איזה שרשור צ'אט שייך לאיזה call_id.

לפני שמתחילים

  • מפתח API, שנשמר בשרת שלכם ולעולם לא בדפדפן או בצ'אט. צרו אחד תחת אינטגרציות → מפתחות API (ראו יצירת מפתח API לשרת).
  • מספר שמאפשר שיחות יוצאות וסוכן עבור השיחות. ההודעה הופכת ל-context לכל שיחה, כך שסוכן כללי אחד מטפל בכל משימה.
  • שרת שיכול לקבל webhooks, כגון Railway, Fly.io, Render או מארח משלכם.
  • נקודת קצה של webhook שמפנה לשרת זה ומנויה ל- telephony.turn ול-telephony.complete. אירועי סבב נשלחים רק אל נקודות קצה שמציינות אותם. ראו Webhooks. אירועי סבב דורשים שהקלטת השיחות של הסוכן תהיה מופעלת, והשדה summary בסיום השיחה דורש את הגדרת יצירת סיכום שיחה של הסוכן; בלעדיהם שדות אלה נשארים ריקים.
  • אפליקציית צ'אט משלכם. עבור Slack, צרו אפליקציה במרחב העבודה שלכם ב- api.slack.com/apps.

1. התחלת שיחה מהודעה

כאשר הבוט שלכם מקבל הודעה (הודעה ישירה או אזכור @), אשרו מיד את הבקשה של Slack‏ (Slack מנסה שוב כל בקשה שלא אושרה בתוך 3 שניות) ובצעו את השאר ברקע. בדקו שהשולח מורשה לבצע שיחות, ואז התחילו את השיחה עם ההודעה בתור context:

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":   "+18005550100",
    "agent_id":    12,
    "context":     "Matthew asked: get the outage ETA for account 4471. Wait on hold if needed.",
    "idempotency_key": "slack-D012AB3CD-1731000000.000100"
  }'

שמרו את call_id שהוחזר מול שרשור ה-Slack‏ (channel בתוספת ה-ts של ההודעה) והשיבו בשרשור ("מחייגים…"). בנו את idempotency_key מהערוץ ומה-ts של ההודעה (ts ייחודי רק בתוך הערוץ שלו), כדי שאירוע Slack שמנוסה מחדש לא יבצע שיחה שנייה. אם הבקשה מציינת אדם במקום מספר, הבוט שלכם מאתר תחילה את המספר. ThunderPhone מחייגת רק אל ה-to_number שאתם שולחים.

2. מעקב אחר השיחה בשרשור

כל webhook מסוג telephony.turn כולל את call_id, את הדובר (role: assistant עבור הסוכן, user עבור האדם האחר), את text ואת ה-position של התור. אתרו את השרשור לפי call_id ופרסמו את השורה.

  • אמתו כל webhook לפני שתפעלו לפיו. ראו אימות חתימות webhook.
  • בצעו ביטול כפילויות לפי event_id של המעטפת וסדרו לפי position. המסירה מתבצעת לפחות פעם אחת, ותורים עשויים להגיע בסדר שגוי.
  • אחדו שורות לאצווה אם שיחה עמוסה עלולה להציף את השרשור; פרסום כל כמה שניות קריא יותר מהודעה אחת לכל שורה.

כאשר מגיע telephony.complete, פרסמו כיצד השיחה הסתיימה (ה-status וה-end_reason שלה), את ה-summary, וכל נתון שחולץ, וסגרו את השרשור. ראו השלמת שיחה עבור השדות.

3. הכוונת השיחה מהשרשור

כאשר מישהו משיב בשרשור של שיחה פעילה, שלחו את התשובה כלחישה, אלא אם הסוכן ממתין לתשובה על שאלה (שלב 4), ובמקרה זה התשובה משמשת כמענה:

curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ask whether they can waive the late fee."}'

הסוכן שומע אותה באופן פרטי ומשלב אותה בתור הבא שלו; האדם האחר לעולם אינו שומע את הלחישה עצמה. לחישה היא באורך של 1 עד 1000 תווים. קוד 409 פירושו שהשיחה כבר אינה פעילה: עדכנו את השרשור שהשיחה הסתיימה.

4. אפשרו לסוכן לשאול אתכם

תנו לסוכן כלי, לדוגמה ask_owner עם פרמטר question אחד, שמפעיל קריאה לשרת שלכם. צרו אותו בתור חיבור API וקשרו אותו לסוכן. מזהה השיחה מועבר בכל בקשת כלי בכותרת X-ThunderPhone-Call-ID שלה.

יש שלוש דרכים לקבל את התשובה בחזרה.

החזיקו את השיחה (עד 10 דקות). הגדירו את הכלי למצב החזקה: spec.wait_mode "hold" ואת spec.timeout לעד 600 שניות (ללא זמן קצוב, החזקה נמשכת 20 שניות), באמצעות ה- API, או בקשו מ-Zeus להגדיר אותם (לעורכי האפליקציה עדיין אין אף אחד מהשדות האלה). נקודת הקצה שלכם מפרסמת את השאלה לשרשור השיחה ומשיבה מיד עם תוצאה בהמתנה:

{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}

הצד השני שומע משפט אחד מהסוכן, ולאחר מכן מוזיקת המתנה. בתפריט טלפוני או בתא קולי, הסוכן משתמש במקום זאת בעדכונים מדוברים, וסוכן בתקשורת דו-כיוונית מלאה אינו משהה: הוא מקבל את התגובה הממתינה כתוצאה. כשהתשובה מגיעה לשרשור, העבירו אותה באמצעות POST /v1/calls/{call_id}/tool-results:

curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "q-C012AB3CD-1731000042.000300", "result": {"answer": "Yes, book Tuesday at 10."}}'

מוזיקת ההמתנה נחלשת והסוכן ממשיך עם התשובה שלכם. אם אף אחד לא עונה לפני ה-timeout, הסוכן מקבל הודעה שלא התקבלה תשובה ומציע לצד השני את הצעדים הבאים. בזמן ששאלה ממתינה עבור שיחה, התשובה הבאה בשרשור עונה עליה: העבירו אותה כתוצאת הכלי ואל תשלחו אותה גם כלחישה (לחישה מגיעה לסוכן רק לאחר שהכלי מחזיר תוצאה). ראו המתנות ארוכות.

המתינו בתוך הבקשה (עד 3 דקות). נקודת הקצה שלכם שולחת את השאלה, ממתינה לתשובה ומחזירה אותה, למשל {"answer": "Yes, book Tuesday at 10."}. הגדירו את spec.timeout של הכלי באמצעות ה-API, לעד 180 שניות (ברירת המחדל היא 20). הגדירו לנקודת הקצה שלכם מועד אחרון משלה, מוקדם בכמה שניות (לדוגמה 170 שניות), כך שכאשר אף אחד לא עונה היא עדיין תחזיר משהו שהסוכן יכול לפעול לפיו, למשל {"answer": null, "note": "No reply yet. Offer to take a message."}. כלי שמגיע ל-timeout שלו מגיע לסוכן כשגיאה, והשרת המארח שלכם חייב להשאיר בקשה פתוחה למשך זמן זה. בזמן ההמתנה, הסוכן אומר לצד השני שהוא בודק, מציין שהוא עדיין מטפל בכך לאחר כ-12 שניות, ולאחר מכן נותן עדכון קצר בערך כל 15 שניות. גם כאן אפשר להשתמש במצב השהיה: הגדירו את spec.wait_mode ל-"hold" והצד השני ישמע מוזיקה במקום העדכונים.

ענו באמצעות לחישה. נקודת הקצה שלכם שולחת את השאלה ומחזירה מיד, למשל {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}. כשהתשובה מגיעה, שלחו אותה כלחישה (שלב 3), והסוכן מגיב אליה מיד. השתמשו בכך עבור תשובות שעשויות להימשך יותר מ-10 דקות. השיחה אינה מושהית: בהנחיה שלכם יש לציין לסוכן מה לעשות בינתיים, למשל לשוחח עם האדם או להציע להתקשר אליו בחזרה.

בכל מקרה, ציינו בהנחיה לסוכן מתי להשתמש בכלי ומה לומר לצד השני בזמן ההמתנה:

When you need Matthew's decision, use ask_owner with a short question.
Tell the person you're checking with Matthew and it may take a minute.
If there's no answer, offer to take a message or have Matthew call back.

מגבלות שכדאי לתכנן לפיהן

  • נקודת הקצה שלכם חייבת להשיב בתוך ה־timeout של הכלי, לכל היותר בתוך 180 שניות. כלי במצב המתנה יכול להשאיר את השיחה בהמתנה עד 600 שניות עם תוצאה ממתינה.
  • בזמן שכלי ממתין, הסוכן אינו משיב לאדם השני. במצב המתנה הם שומעים מוזיקה; אחרת, עדכונים קוליים קצרים.
  • לחישה מוגבלת לכל היותר ל־1000 תווים.
  • המסירה של telephony.turn מתבצעת לפחות פעם אחת ועשויה להגיע שלא לפי הסדר.

רשימת בדיקות אבטחה

  • שמרו את מפתח ה־API בשרת שלכם.
  • אמתו את החתימות של ThunderPhone בוובהוקים ובבקשות לכלים, ואת סוד החתימה של Slack בבקשות של Slack. שתי החתימות של ThunderPhone משתמשות בסודות שונים: מסירות וובהוק משתמשות בסוד של נקודת הקצה של הוובהוק עצמו, ובקשות לכלים משתמשות בסוד הוובהוק של הארגון שלכם מתוך GET /v1/webhook.
  • החליטו מי רשאי להתחיל שיחות: בדקו את מזהה המשתמש ב־Slack לפני ביצוע שיחה.
  • שיחות יוצאות כפופות לאותם כללים כמו כל שיחה אחרת. ראו חוקי שיחות יוצאות.

בנו זאת עם סוכן תכנות

הפנו את סוכן התכנות שלכם אל שרת ה־MCP של התיעוד ואל דף זה, ובקשו ממנו "בוט Slack עבור סוכן ThunderPhone שלי שפועל לפי מדריך זה". Zeus, העוזר באפליקציית ThunderPhone, יכול להגדיר את הצד של הסוכן (נקודת הקצה של הוובהוק, הכלי ושורות ההנחיה) ולכתוב קוד התחלתי עבור הבוט בצ'אט.