קיבלנו הרבה פניות בנושא חיבור למערכות חיצוניות. גיבשנו רעיון ראשוני למודול API ונשמח לשמוע אם הכיוון עונה על הצרכים שלכם!
המודל מבוסס על מערך של פועולות עם הגדרה לאיזה פעולה לעבור בסיום או ע"פ הקשה
ניתן להגדיר פעולות בשני דרכים:
- הגדרה ראשונית: מערך פעולות בסיסי שמוגדר בשלוחה מראש באתר (בעיקרון עם json אבל אפשר גם עם UI יותר ידודתי)
- הרחבה דינמית: השרת יכול להוסיף פעולות חדשות בזמן ריצה
בהגדרה הראשונית צריך להגדיר מה הפעולה הראשונה שיבצע (עדיף לכאורה מאשר שיבחר באופן אוטומטי את הפעולה הראשונה במערך)
היתרונות המשמעותיים:
- השרת לא צריך להגדיר את כל הפעולות מראש, אלא יכול להוסיף פעולות בהתאם לתשובות המשתמש והתקדמות השיחה
- כל פעולת
curlיכולה לתקשר עם שרת שונה, מה שמאפשר אינטגרציה עם מערכות מרובות בזרימת שיחה אחת - המערכת שומרת משתנים באופן מקומי ומשתמשת בהם לפי הצורך, ללא צורך בתקשורת מול השרת בכל שלב
סוגי פעולות בסיסיות
play_and_get_digits: השמעת הודעה וקבלת קלטplayback: השמעת הודעהcurl: שליחת בקשה ל-APIhangup: ניתוק השיחה
בהמשך כנראה נוסיף פעולות כמו הקלטה או העברה למודל API אחר וכדו'
מבנה הפעולות
כל פעולה במערך מוגדרת עם:
{
"uuid": "שם_ייחודי",
"type": "סוג_הפעולה",
"next_action": "הפעולה_הבאה",
// או
"conditional_map": {
"תנאי": "פעולה_הבאה"
}
}
בפעולת curl יש מפתח מיוחד:
{
"type": "curl",
"curl_command": "...",
"next_action_on_error": "הפעולה_במקרה_שגיאה"
}
משתנים דינמיים
- שמירת משתנים:
"save_variable": "שם_המשתנה" - שימוש במשתנים:
{{שם_המשתנה}} - משתנה מובנה:
{{user}}- מזהה שיחה ייחודי
דוגמה מלאה: אימות PIN
הנה דוגמה מקיפה שמדגימה את כל היכולות. בוא נעקוב אחר המשתמש בתהליך:
-
תחילת השיחה:
- המערכת משמיעה: "ברוכים הבאים למערכת האימות. אנא הקישו קוד PIN בן 3 ספרות"
- המשתמש מקיש את הקוד, נניח 123
- אם המשתמש לא מקיש כלום או מקיש קוד לא תקין, המערכת תעבור להשמעת הודעת שגיאה
-
בדיקת הקוד:
- המערכת שולחת את הקוד לבדיקה בשרת
- בזמן זה המשתמש ממתין לתשובה
- אם יש בעיית תקשורת, המשתמש ישמע: "מצטערים, אירעה שגיאה. אנא נסו שוב מאוחר יותר"
-
אישור הקוד:
- אם הקוד תקין, המערכת משמיעה: "הקשתם את המספר..."
- ואז משמיעה כל ספרה בנפרד: "אחת... שתיים... שלוש..."
- לאחר מכן: "לאישור הקישו 1, להקשה מחודשת הקישו 2"
- המשתמש בוחר: אם מקיש 1 - ממשיך לאישור סופי, אם מקיש 2 - חוזר להקשת הקוד מחדש
-
סיום מוצלח:
- אם המשתמש אישר והכל תקין, ישמע: "הקוד אומת בהצלחה, תודה ולהתראות"
- השיחה מסתיימת
-
טיפול בשגיאות:
- אם הקוד שגוי, המשתמש ישמע: "הקוד שהקשתם שגוי" וחוזר להתחלה
- אם אין קלט או יש שגיאה, המשתמש ישמע הודעת שגיאה מתאימה
הנה ההגדרה הראשונית שתוגדר בממשק שמממש את התהליך הזה:
{
"first_action": "get_pin",
"actions": [
{
"uuid": "get_pin",
"type": "play_and_get_digits",
"audio_files": ["enter_pin.wav"],
"min_digits": 3,
"max_digits": 3,
"tries": 3,
"timeout": 5000,
"terminator_key": "#",
"regex_pattern": "\\d+",
"save_variable": "pin",
"conditional_map": {
"no_input": "fail",
"default": "verify_pin"
}
},
{
"uuid": "verify_pin",
"type": "curl",
"curl_command": "https://server1.dev/verify?pin={{pin}}",
"next_action_on_error": "fail"
}
]
}
דוגמאות לתשובות שרת
תשובה תקינה - הוספת פעולות חדשות:
{
"next_action": "play_pin",
"new_actions": [
{
"uuid": "play_pin",
"type": "playback",
"audio_files": [
"you_entered.wav",
"digits/1.wav",
"digits/2.wav",
"digits/3.wav"
],
"next_action": "get_confirmation"
},
{
"uuid": "get_confirmation",
"type": "play_and_get_digits",
"audio_files": ["confirm.wav"],
"min_digits": 1,
"max_digits": 1,
"tries": 3,
"timeout": 5000,
"terminator_key": "#",
"regex_pattern": "[12]",
"conditional_map": {
"1": "confirm_pin",
"2": "get_pin",
"no_input": "fail"
}
}
]
}
תשובת שגיאה - חזרה למצב קודם:
{
"next_action": "invalid_pin",
"new_actions": [
{
"uuid": "invalid_pin",
"type": "playback",
"audio_files": ["invalid_pin.wav"],
"next_action": "get_pin"
}
]
}
נשמח לשמוע מכם:
- האם המבנה ברור ומספק?
- האם חסרים שדות או יכולות טכניות?
- האם יש לכם הצעות לשיפור המודל?
- האם הדוגמאות מספיק ברורות?
- האם נראה לכם שעבודה בצורה כזאת נוחה בפיתוח מערכות מורכבות?
מוזמנים להתנסות בגרסת הבטא כאן:
️ שימו לב: מדובר בגרסת פיתוח בלבד, ולא במוצר מוגמר לשיווק.
נוחות השימוש בממשק
 { const baseUrl = "https://www.google.co.il/search?q=site:mitmachim.top"; const m = location.pathname.match(/^\/(topic|category)\/(\d+)/); const type = m ? m[1] : null; const id = m ? m[2] : null; let searchInput; function search(path = "") { const query = searchInput.value.trim(); if (query) { window.open(`${baseUrl}${path}%20${encodeURIComponent(query)}`, "_blank"); } } let buttons = {}; buttons.searchAll = { id: "bb-search-all", label: `חיפוש ${type ? "בכל הפורום" : ""}`, className: type ? "btn-secondary" : "btn-primary", callback: () => search(), }; if (type === "topic") { buttons.searchTopic = { label: "חיפוש בנושא זה", className: "btn-primary", callback: () => search(`/topic/${id}`), }; } else if (type === "category") { buttons.searchCategory = { label: "חיפוש בקטגוריה זו", className: "btn-primary", callback: () => search(`/category/${id}`), }; } buttons.cancel = { label: "ביטול", className: "btn-default", "data-bs-dismiss": "modal" }; const dialog = bootbox.dialog({ title: '<div style="text-align:center;"><img src="/assets/uploads/files/1625950269825-mt-google.png" width="400" alt="חיפוש בגוגל"></div>', message: '<input id="bb-inp" class="bootbox-input bootbox-input-text form-control" placeholder="הקלידו כדי לחפש בגוגל" autocomplete="off"/>', buttons, backdrop: true, show: true, onEscape: true }); dialog.on("shown.bs.modal", function () { searchInput = document.getElementById("bb-inp"); if (searchInput) { searchInput.focus(); searchInput.addEventListener("keydown", function (e) { if (e.key === "Enter") { e.preventDefault(); const query = this.value.trim(); if (query) { search(); dialog.modal("hide"); } } else if (e.key === "Escape") { e.preventDefault(); dialog.modal("hide"); } }); } const searchAllButton = document.getElementById("bb-search-all"); if (searchAllButton) { searchAllButton.title = "לחצו על אנטר כדי לחפש"; } }); })(); void 0;){kind=link}