טעינת הגדרות תור ומספרים לחיוג ב-API
הגדרות בקובץ ext
כללי
כברירת מחדל המערכת טוענת את הגדרות התור ואת רשימת המספרים לחיוג מקובץ queue.ini.
ניתן להגדיר כי נתוני התור ייטענו באמצעות API.
ההגדרה היא:
queue_url_link=https://example.com/queue.php
כמובן שאחרי ה = יש לרשום את כתובת ה-URL של השרת שלכם
במקרה כזה, בכל כניסה של משתמש לשלוחה תתבצע פנייה בAPI לקבלת נתוני התור.
את תגובת השרת יש להחזיר בהתאם לפורמט המובא להלן.
במידה ואין התייחסות בתגובת השרת להגדרות התור, המערכת תטען את ההגדרות מקובץ queue.ini.
במקרה של סתירה בהגדרות התור בין המופיע בתגובת השרת למופיע בקובץ queue.ini, ההגדרות המופיעות בתגובת השרת גוברות.
את רשימת המספרים לחיוג המערכת טוענת אך ורק מתגובת השרת. ולא מקובץ queue.ini.
הערה: מדובר בהחלפת ערכים מלאה של הגדרות התור כולה, ולא רק של הגדרות שיחה ספציפית.
פרמטרים המצורפים לשליחה
פרמטרים ברירת מחדל
כברירת מחדל המערכת מצרפת לכל פנייה פרמטרים הכוללים מידע על השיחה
הפרמטרים המצורפים הם
ApiCallId=מזהה ייחודי לאורך הפנייה לשרת
YemotCallID=מזהה ייחודי לאורך השיחה
ApiPhone=מספר הטלפון של המשתמש
ApiDID= מספר טלפון הראשי של המערכת שלכם
ApiRealDID=המספר אליו חייג המשתמש.
(במידה ויש כמה מספרים למערכת שלכם, והמשתמש חייג למספר משנה, הערך הזה יהיה שונה מהערך הקודם)
ApiExtension=שם התיקייה/שלוחה בה נמצא המשתמש
ApiEnterID=במידה ובוצעה התחברות לפי זיהוי אישי, יצורף ערך זה המכיל את סוג ההתחברות וה-ID של המשתמש (מידע נוסף כאן)
ApiEnterIDName= שם משויך לזיהוי האישי (כפי שמוסבר כאן)
ApiTime= זמן בשניות מ1970, Epoch, i.e., since 1970-01-01 00:00:00 UTC.
כדי לבטל את שליחת הפרמטרים הנ"ל או את חלקם יש להגדיר (בהתאמה)
queue_api_did_send=no /// Deleting a parameters "ApiDID" "ApiRealDID"
queue_api_phone_send=no /// Deleting a parameter "ApiPhone"
queue_api_extension_send=no /// Deleting a parameter "ApiExtension"
queue_api_enter_id_send=no /// Deleting a parameter "ApiEnterID"
queue_api_enter_id_name_send=no /// Deleting a parameter "ApiEnterIDName"
queue_api_time_send=no /// Deleting a parameter "ApiTime"
queue_api_call_id_send=no /// Deleting a parameter "ApiCallId"
queue_api_yemot_call_id_send=no /// Deleting a parameter "YemotCallID"
פרמטרים קבועים
ניתן להגדיר שבכל פנייה, המערכת תצרף פרמטרים קבועים שיישלחו לשרת.
(הערה: לא ניתן לצרף פרמטרים הנשלחים כברירת מחדל)
לדוגמה אם ברצונכם שבכל פנייה לשרת המערכת תצרף את הפרמטרים p1=v1 p2=v2 יש להגדיר בהגדרות השלוחה
queue_api_add_0=p1=v1
queue_api_add_1=p2=v2
במקרה כזה הבקשה ב-GET תראה כך
https://example.com/queue.php?p1=v1&p2=v2
כמובן שניתן לצרף פרמטרים נוספים (queue_api_add_X=), כשבמקום X יש לרשום את מספר הפרמטר.
שימו לב שחשוב לשמור על רצף סידורי החל מהספרה 0.
מתודת שליחה
כברירת מחדל הפנייה נשלחת בHTTP GET
אם ברצונכם שהפנייה תישלח בHTTP POST יש להגדיר
queue_api_url_post=yes
תגובת שרת
את תגובת השרת יש להחזיר בתבנית JSON.
הנתונים שניתן להחזיר הם בדומה להגדרות האפשריות בקובץ queue.ini
דוגמה
{
"description" : x,
"queueactive" : x,
"autofill" : x,
"context" : x,
"monitor-type" : x,
"monitor-format" : x,
"servicelevel" : x,
"keepstats" : x,
"maxlen" : x,
"autopause" : x,
"announce-position" : x,
"announce-position-limit" : x,
"announce-holdtime" : x,
"announce-frequency" : x,
"relative-periodic-announce" : x,
"random-periodic-announce" : x,
"min-announce-frequency" : x,
"announce-round-seconds" : x,
"periodic-announce" : x,
"periodic-announce-frequency" : x,
"reportholdtime" : x,
"strategy" : x,
"joinempty" : x,
"leavewhenempty" : x,
"retry" : x,
"wrapuptime" : x,
"timeout" : x,
"timeoutrestart" : x,
"musicclass" : x,
"ringinuse" : x,
"queue-thankyou" : x,
"queue-youarenext" : x,
"queue-thereare" : x,
"queue-callswaiting" : x,
"queue-holdtime" : x,
"queue-minutes" : x,
"queue-seconds" : x,
"queue-less-than" : x,
"queue-reporthold" : x,
"members" : [
"0507707701",
"SIP-0773137770"
]
}
בפרמטר members יש להחזיר את רשימת המספרים לחיוג.
שימו לב!
המערכת טוענת את כל הגדרות התור מתוך תגובת השרת בלבד!
אין כל הסתמכות על קובץ queue.ini!!
אין מיזוג בין תגובת השרת לבין queue.ini.
אין fallback לקובץ queue.ini במקרה שחסר פרמטר בתגובה.
חסימת שיחה באמצעות API
כדי לחסום שיחה באופן יזום דרך ה-API יש להחזיר JSON במבנה הבא:
{
"status": "error",
"action": "API_MODULE",
"action_data": "id_list_message=t-שלום עולם.g-/1"
}
בדוגמה, השיחה לא תיכנס לתור.
המשתמש ישמע 'שלום עולם' בהקראה רובוטית ויעבור לשלוחה אחת תחת השלוחה הראשית.
כאשר מתקבלת תגובה זו:
המערכת אינה ממשיכה לתהליך התור.
אין ניסיון לחייג למספרים.
אין טעינה של הגדרות תור.
התגובה מטופלת בהתאם למנגנון מודול API.
כלומר, במקום כניסה לתור, המערכת מתייחסת לתגובה כאילו הופעל מודול API רגיל, ומבצעת את הפעולה בהתאם לערך action_data.
המשמעות המעשית
באמצעות action_data ניתן:
להעביר לשלוחה אחרת
להשמיע הודעה
להפעיל מוזיקה בהמתנה
לבצע ניתוק
או כל פעולה אחרת הנתמכת במודול API
כך ניתן לשלוט באופן מלא בזרימת השיחה במקרה שהחלטתם לא להכניס את המתקשר לתור (לדוגמה: חסימה לפי זיהוי, שעות פעילות, בדיקת הרשאות וכד').
הפירוט המלא של מבנה ואפשרויות action_data מופיע בתיעוד מודול API:
https://f2.freeivr.co.il/post/77904
טיפול במצב שגיאה בתגובת ה-API
מצב שגיאה כולל בין היתר:
action אינו API_MODULE
action_data ריק
JSON לא תקין
תגובה ריקה
שגיאת כל שהיא בשרת
ההתנהגות תיקבע לפי queue_error_api_status כמובא בהמשך.
יש 3 מצבים שאפשר להגדיר במצב שגיאה:
1. יציאה מהשלוחה (ברירת מחדל)
queue_error_api_status=exit
המעבר יתבצע לפי:
queue_error_api_goto=/1/1
בדוגמה זו המערכת תעבור לשלוחה /1/1 מהתפריט הראשי.
אם לא הוגדר queue_error_api_goto, המערכת תפעל לפי:
queue_error_goto=/2/2
אם גם זה אינו מוגדר, תתבצע חזרה של שלוחה אחת אחורה (exit רגיל).
2. קריאה מקובץ queue.ini
queue_error_api_status=read_ini_file
במצב זה המערכת תטען את הגדרות התור מקובץ queue.ini.
3. שימוש בנתונים מהשיחה הקודמת
queue_error_api_status=read_cash
במצב זה המערכת תשתמש בהגדרות התור המעודכנות מהשיחה הקודמת, ללא רענון חדש מה-API.