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

מה זה Webhook?

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

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

הגדרת Webhook בשירותי אקסטרה

בשירותים שלנו שדרכם מתאפשרת שיחת טלפון, ניתן להגדיר Webhook:

  1. בקו הסלולרי בסיום שיחה.
  2. בסופטפון בסיום שיחה.
  3. במספר הוירטואלי בתחילה ובסיום שיחה.
  4. בנתב הוירטואלי בתחילה ובסיום שיחה.

כדי להירשם לאירועים ולהגדיר URL לוובהוק, יש להיכנס להגדרות השירות המבוקש באיזור האישי.

מידע טכני על הוובהוק שלנו

המערכת שלנו תבצע בקשת HTTP אל כתובת ה-URL שתוגדר במסך הגדרות של השירות שבעבורו הפעלתם וובהוק.

  1. סוג הבקשות האפשריות: HTTP GET או HTTP POST - בשתיהן יועבר מידע לגבי השיחה, במבנה ובפורמט שונה. הפורמטים מפורטים בהמשך הכתוב.
  2. הבקשה תגיע מאחת מכתובות ה-IP היוצאות שלנו.
  3. על כתובת הוובהוק להיות מאובטחת SSL. סכימת ה-URL חייבת להיות https.
  4. התגובה שתתקבל לבקשה לא תישמר.
  5. אם לא תתקבל תגובה תוך 10 שניות, הבקשה תיכשל סופית. אין מנגנון retry.

אירועים

יש לנו 3 סוגי אירועים בעבור שיחות טלפון:

  1. תחילת שיחה - במספר הוירטואלי ובנתב הוירטואלי.
  2. סיום שיחה - בכל השירותים.
  3. סיום עיבוד AI - אם מופעל בחשבון.

 בכל אחד מהאירועים נשלח אל הוובהוק את אובייקט השיחה המלא ונכלול את הפרטים ככל שאנחנו יכולים.
למשל: באירוע תחילת שיחה, אין מידע על משך השיחה שכן היא טרם התחילה, אז נעביר את הערך 0.  באירוע סוף שיחה אין לנו עדיין סיכום שיחה שכן זהו עיבוד אסינכרוני שמוזנק בדיוק באירוע סיום שיחה, ורק בסיומו האובייקט יכיל את סיכום ה-AI.

POST Request

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

אם תבחרו בהגדרת הוובהוק שהמידע יישלח בשיטת POST, אנו נייצר אובייקט JSON ונשלח אותו בתוך HTTP BODY. דוגמה לאובייקט כזה:

{ "id":"JUXglqw", "event":"end", "type":"outgoing", "own_type":"VIVR", "ivr_dialed":3, "duration":12, "note":"A note by the user", "starred": false, "time":{ "timezone":"Israel", "gmt_offset":"+02:00", "start":"2024-01-01 22:22:22", "end":"2024-01-01 22:22:22" }, "numbers":{ "own":{ "friendly":"077-8038038", "e164":"+972778038038" }, "caller":{ "friendly":"053-7654321", "e164":"+972537654321" }, "destination":{ "friendly":"053-1234567", "e164":"+972531234567" } }, "contact": { "id": "bsn6HIpx", "name": "שליח HFD" }, "AI":{ "status":"COMPLETED", "summary":{ "gist":"השיחה כוללת הודעה מוקלטת על הקלטת שיחות", "body":"השיחה היא למעשה מענה קולי אוטומטי של קופת חולים כללית. המערכת מספקת מידע על אפשרויות זימון תורים טלפוני או דיגיטלי, שעות פעילות, אפשרות לקבלת מענה טלפוני בנושא הולטר לב והולטר לחץ דם בימים ראשון עד חמישי בין 9:00 בבוקר ל-13:00, ואפשרות לשיחה עם נציג בנושאים אחרים. בנוסף, מוזכרת אפשרות לזימון תורים דרך אתר ואפליקציית כללית בסמארטפון או במערכת הזימון בשירות העצמי בטלפון.", "questions":{ "next_steps":[ "לבדוק את שעות הפעילות של המוקד הטלפוני", "לשקול שימוש באפליקציית כללית לזימון תורים", "לבדוק אפשרות לקבלת מענה טלפוני בנושא הולטר לב/לחץ דם" ] } } } }

GET Request

בהגדרת הוובהוק, אם תבחרו שהמידע יישלח בבקשת GET, אנחנו נבצע קריאה אל ה-URL שהגדרתם ונשרשר את הפרמטרים הבאים כ-Url-encoded Query String. ניתן להגדיר כתובת עם querystring או בלעדיה, ואף ניתן לשרשר פרמטרים. כל הכתובות הבאות תקינות:

https://www.example.com/
https://www.example.com/?
https://www.example.com/?my_id=12345

ולאחר שרשור הפרמטרים של השיחה זה ייראה כך:

https://www.example.com/?my_id=12345&id=JUXglqw&type=end&(...)

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

רשימת פרמטרים GET

בטבלה מפורטים כל הפרמטרים המועברים בקריאת GET אל הוובהוק.
שימו לב: אובייקט AI והתכונה note - שניהם אינם מועברים בוובהוק ב-GET אלא רק בקריאת POST!

 

שם הפרמטר תיאור דוגמה
id מזהה ייחודי של השיחה באקסטרה. JUXglqw
event האירוע שעליו הוובהוק מדווח. שימו לב: לכל שירות יש את האירועים שלו, למשל: בקו הסלולרי הדיווח הוא רק בסיום שיחה בעוד במספר הוירטואלי יש קריאה גם בהתחלה וגם בסיום שיחה. end
start
AI-DONE
type סטטוס \ סוג השיחה: נכנסת נענתה, יוצאת לא נענתה וכו' outgoing
outgoing_missed
outgoing_start
incoming
incoming_missed
incoming_start
own_type מזהה השירות באקסטרה: מספר וירטואלי, נתב וירטואלי, קו סלולרי VIVR
VNUM
MOBL
starred האם השיחה מסומנת בכוכב? 0
1
ivr_dialed מספר שהוקש בנתב הוירטואלי. אם לא הוקש או לא נתב או הייתה הקשה שגויה, שדה זה יושמט 3
own_number_friendly מספר הקו שלכם באקסטרה, שממנו הוצאתם שיחה או אליו קיבלתם שיחה. 077-8038038
own_number_e164 מספר הקו שלכם באקסטרה בפורמט בינלאומי +972778038038
caller_number_friendly מספר הטלפון של יוזם השיחה בפורמט ידידותי. ריק אם המספר חסום 053-7654321
caller_number_e164 מספר הטלפון של יוזם השיחה בפורמט בינלאומי +972537654321
destination_number_friendly מספר הטלפון של מקבל השיחה בפועל בפורמט ידידותי. לרוב יהיה זהה ל-own_number אבל במקרה של "עקוב אחריי" או בניתוב בנתב הוירטואלי, יחזיק את המספר שאליו השיחה חוברה בפועל. 053-1234567
destination_number_e164 מספר הטלפון של מקבל השיחה בפורמט בינלאומי. +972531234567
time_duration_seconds משך השיחה בשניות. לא יועבר באירועי תחילת שיחה. 126
0
time_timezone אזור זמן Israel
time_gmt_offset ההפרש מ-GMT +02:00
time_started הזמן שבו התחילה השיחה בפורמט רגיל. 2024-01-01 22:22:22
time_started_8601 הזמן שבו התחילה השיחה בפורמט 8601. 2024-02-13T15:19:21+00:00
time_ended הזמן שבו הסתיימה השיחה בפורמט רגיל. לא יועבר באירועי תחילת שיחה. 2024-01-01 23:23:23
time_ended_8601 הזמן שבו הסתיימה השיחה בפורמט 8601. לא יועבר באירועי תחילת שיחה. 2024-02-13T15:19:21+00:00

פרמטרים נוספים Custom Data

הדרך לצרף פרמטרים שלכם לוובהוק, כמו למשל: מזהה פנימי אצלכם במערכת, היא באמצעות שרשור שלהם אל ה-URL של הבקשה. למשל:
https://www.example.com/?my_id=12345

בקריאה ל-URL זה, לא משנה אם זו קריאת POST עם JSON Body או קריאת GET עם Querystring, בשניהם אותם פרמטרים "יחזרו" אליכם כחלק מה-URL ותוכלו לחלץ אותם.

קובץ הקלטת שיחה

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

עם זאת, הצורך באחזור הקלטת השיחה ברור ומתבקש ואנחנו מציעים כמה אפשרויות לקבל את הקלטת השיחה:

אחזור קובץ ההקלטה עם API

קריאת API אל מתודת /calls/recording/ מחזירה את הקובץ עצמו כתגובת HTTP. זו השיטה המומלצת בעינינו כי בשום שלב אין בה url ציבורי שגישה אליו תאפשר האזנה להקלטת השיחה.

במידה והמטרה היא שמירת ההקלטה, שיטה זו גם "חוסכת" שלב אחד: במקום לאחזר בשני שלבים של הפקדת url ציבורי ואז קריאה נוספת להוריד את קובץ ההקלטה, קריאה זו מחזירה ישירות את קובץ ההקלטה.

הפקת url חתום זמני לגישה להקלטה

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

חשוב: URL ציבורי או מוגבל בזמן חוזר רק בקריאת API ובוובהוק שהוגדר לקריאה במתודת POST. 

ניתן להפיק url כזה בשני אופנים:

  1. אחזור באמצעות קריאת API אל /calls/get-recording-urls/ - הקריאה מקבלת זמן תפוגה בדקות ורשימה של מזהה (או מזהים רבים) של שיחה ומחזירה רשימה של כתובות url חתומות ההופכות את ה-URL לנגיש למספר דקות, לפי הפרמטר שהועבר.
    אופן הביצוע: קריאת API על פי התיעוד.
  2. בקריאת ה-Webhook באמצעות הוספת פרמטר ל-URL - ואז בהטרגה של הוובהוק יישלח בתוך אובייקט השיחה גם פרמטר עם url מוגבל בזמן.
    אופן הביצוע: הוספת פרמטר ל-URL בשם: config[ttl] עם ערך מספרי בין 1 ל-10 לציון מספר הדקות לתפוגה, למשל:
    https://mywebhook.make.com/?config[ttl]=3

 

בצעו בדיקות עם Webhook.site

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

  1. הפיקו url בשירות הנ"ל. אין צורך בהרשמה, עם כניסה לשירות תופק בעבורכם כתובת באופן אוטומטי.
  2. הדביקו את הURL שהופק אל התיבה המתאימה בהגדרת הוובהוק.
  3. בצעו שיחת ניסיון אל המספר באקסטרה.
  4. חזרו אל השירות webhook.site ובחנו את הבקשה שנשלחה מהשרת שלנו.