**הסבר על מבנה ה API** > ## 🔒 נתונים רגישים בלוג — חובה לקרוא לפני איסוף אשראי / CVV / ת.ז. > > כל קלט שהמאזין מקיש נשמר בלוג ה-API (`ivrApiLog`) כחלק מכתובת ה-URL. כדי **שלא** יישמר נתון רגיש בלוג — הוסיפו **`"maskLog": true`** לאלמנט הקלט (`getDTMF` / `simpleMenu` / `record` / `stt`). > > הערך **המלא נשלח לשרת שלכם כרגיל** (כדי לסלוק/לעבד) — רק העותק שנשמר בלוג ממוסך: **2 תווים ראשונים + 2 אחרונים והשאר `XXXX`** (קלט קצר עד 4 תווים — התו הראשון בלבד). > > דוגמה: כרטיס `1234567890123456` ← לשרת נשלח מלא, בלוג נשמר `12XXXX56`; ‏CVV `123` ← בלוג `1XXXX`. > > **וכדי שהערך גם לא יופיע ב-URL כלל** (ולא ב-access-logs של שרתי web/proxy) — הוסיפו **`"post": true`**: הקריאה החוזרת תישלח ב-**POST** והפרמטרים יעברו לגוף הבקשה. ה-GET הרגיל אינו משתנה. פירוט בהמשך. מודול ה API עובד באינטראקציה בין המרכזיה לשרת שלכם, בכניסה לשלוחה, המרכזיה תפנה לכתובת שהגדרתם, ויצורפו במחרוזת ה URL הפרמטרים הקבועים כדלהלן, עליכם להשיב במבנה JSON לפי אחד המודולים שבמסמך זה, על כל פרמטר שתשלחו, המרכזיה תבצע את המודול שהגדרתם ולאחר מכן תפנה שוב לשרת שלכם כאשר ל URL יצורף בנוסף הערך שהוחזר עבור המודול שהפעלתם, לדוגמה, אם הפעלתם מודול קבלת הקשות, והגדרתם את הערך name ל- myData, והמאזין הקיש 123, יצורף לURL myData=123, כך ישורשרו כל הערכים במהלך התקשורת בשלוחה. אם לא תתקבל תגובה התואמת לאחת המודולים הבאים המאזין יוחזר לתפריט הקודם. ניתן לשלוח מערך בודד של פקודה, וכן ניתן לשרשר מספר פקודות יחד במערכת של מערכים שכל מערך הוא פקודה בודדת, במקשר של כמה פקודות קלט בשליחה אחת כולם יוחזרו ב return api לדוגמה, ניתן לשלוח מערך מקונן של בקשה לשם פרטי, משפחה, טלפון, כתובת וכדו' **הפרמטרים הקבועים שיצורפו לכל פניית API מהמרכזיה ללינק שלכם:** | שם הפרמטר | הסבר | | ----- | ----- | | PBXphone | מספר הטלפון של המאזין | | PBXnum | מספר המרכזיה | | PBXdid | המספר לשם בוצעה החיוג (במידה ויש למרכזיה כמה מספרי גישה) | | PBXcallId | מזהה השיחה (לכל חיוג מזהה שיחה ייחודי) | | PBXcallType | מקור השיחה (in=שיחה נכנסת, out=שיחה יוצאת-קמפיין) | | PBXcallStatus | סטטוס השיחה (CALL=בשיחה, HANGUP=מנותק) | | PBXextensionId | קוד השלוחה | | PBXextensionPath | נתיב השלוחה | **מודולים:** | פרמטר | ערך | הסבר | | ----- | ----- | ----- | | **הודעה פשוטה** | | | | השמעת קובץ/קבצי שמע למאזין ללא קבלת הקשה. בסיום עובר אוטומטית להמשך התזרים / חוזר לשרת. | | | | type | simpleMessage | סוג המודול | | files | | אובייקט קבצים להשמעה \- ראה להלן | | **דוגמה לשימוש במודול:** { "type": "simpleMessage", "files": \[ { "fileId": "1111" } \] } | | | | | | | | **תפריט פשוט** | | | | במודול זה ניתן להקיש רק על מקש אחד ממקשי הטלפון (1234567890\*\#) שהוגדרו מראש, כל הקשה אחרת לא תביא שום תגובה | | | | type | simpleMenu | סוג המודול | | name | דוגמה: "myParameter" | שם הערך שישלח חזרה עם ההקשה שהתקבלה | | times | | מספר פעמים בו התפריט יחזור על עצמו, לאחמ"כ יוחזר ערך "ERROR" | | timeout | | זמן המתנה להקשה (שניות) \- לפני חזרה על התפריט או החזרת שגיאה | | enabledKeys | 1,2,3,4,5,6,7,8,9,0,\*,\# | מקשים מותרים להקשה \- יש להפריד באמצעות פסיק | | setMusic | yes/no | אם מוגדר yes יושמע "מוזיקה בהמתנה" עד לקבלת תגובה מהשרת | | files | | אובייקט קבצים להשמעה \- ראה להלן | | errorReturn | ERROR | ערך שיוחזר אם תם הזמן ללא הקשה | | extensionChange | | לאן לעבור אם סיים את ההשמעה לפי מספר הפעמים המוגדר בערך times קיימים מספר אפשרויות: 1\. ID של שלוחה. 2\. ניתן לרשום נקודה (.) עבור הפעלה חוזרת של השלוחה הנוכחית. 3\. ניתן לרשום שתי נקודות (..) עבור חזרה לשלוחה קודמת. | | maskLog | true | **הסתרת הקלט בלוג** \- ממסך בלוג את ההקשה שנבחרה. ראה "קבלת הקשות" לפירוט. | | **דוגמה לשימוש במודול:** { "type": "simpleMenu", "name": "myParameter", "times": 3, "timeout": 5, "enabledKeys": “1,2,3,4,5,6,7,8,9,0,\*,\#”, , "setMusic": "yes", "extensionChange": "", "files": \[ { "fileId": "1111", "extensionId": "11" }, { "fileId": "2222", "extensionId": "" } \] } Response: YOUR\_YRL?ALL\_PARAMETERS\&myParameter={THE\_DIGIT} | | | | | | | | **קבלת הקשות** | | | | type | getDTMF | סוג המודול | | name | דוגמה: "myParameter" | שם הערך שישלח חזרה עם ההקשה שהתקבלה | | max | | מקסימום ספרות | | min | | מינימום ספרות מותר | | timeout | | זמן המתנה להקשה | | skipKey | | מקש דילוג (הקשה על מקש זה ידלג על הבקשה וישלח את הערך כדלהלן) | | skipValue | | אם הוגדר מקש דילוג הערך הבא יישלח על הפרמטר הנוכחי | | confirmType | number/digits/no | אופן החזרה על הקשת המאזין השמעת ההקשה במספר (ברירת מחדל) \= number השמעת ההקשה בספרות \= digits ללא השמעה חוזרת ובקשת אישור \= no | | setMusic | yes/no | אם מוגדר yes יושמע "מוזיקה בהמתנה" עד לקבלת תגובה מהשרת | | files | | אובייקט קבצים להשמעה \- ראה להלן | | maskLog | true | **הסתרת הקלט בלוג** \- הקלט המלא נשלח לשרתכם; בלוג ה-API (ivrApiLog) יישמר ערך ממוסך: 2 תווים ראשונים \+ 2 אחרונים \+ XXXX (קלט קצר עד 4 תווים \- התו הראשון בלבד). לנתונים רגישים כמו אשראי / CVV / ת.ז. | | post | true | **שליחה ב-POST** \- הקריאה החוזרת (ואילך) תישלח ב-POST במקום GET; הקלט עובר לגוף הבקשה ולא ל-URL. דביק עד סוף השיחה. ראה "שיטת שליחה \- GET / POST" להלן. | | **דוגמה לשימוש במודול:** { "type": "getDTMF", "name": "dataGet", "max": 10, "min": 9, "timeout": 5, "skipKey": "\#", "skipValue": "NO\_VALUE", "confirmType": "digits", "files": \[ { "fileId": "1111", "extensionId": "11" }, { "fileId": "2222", "extensionId": "" } \] } Response: YOUR\_YRL?ALL\_PARAMETERS\&dataGet={THE\_INPUT} | | | | | | | | **קבלת הקלטות** | | | | type | record | סוג המודול | | name | דוגמה: "myParameter" | שם הערך שישלח חזרה עם אישור ההקלטה | | max | | מקסימום אורך ההקלטה \- בשניות | | min | | מינימום אורך ההקלטה \- בשניות | | confirm | confirmOnly/ful/no | אופן בקשת אישור המאזין להקלטה בקשת אישור ואפשרות לשמיעת ההקלטה בהקשה על 2 (ברירת מחדל) \= confirmOnly השמעת ההקלטה ובקשת אישור \= ful ללא בקשת אישור \= no | | fileName | | שם הקובץ כפי שישמר במערכת | | saveFolder | | מזהה שלוחה לשמירת ההקלטה \- עבור שמירה לתקיה שאינה השלוחה הנוכחית **(יש להזין ID של שלוחה)** | | files | | אובייקט קבצים להשמעה \- ראה להלן | | maskLog | true | **הסתרת הקלט בלוג** \- ממסך בלוג את ערכי ההקלטה (כולל טקסט TEXT\_ אם קיים). ראה "קבלת הקשות" לפירוט. | | **דוגמה לשימוש במודול:** { "type": "record", "name": "myRecord", "max": 10, "min": 2, "confirm": "confirmOnly", "fileName": "record\_XXX", "saveFolder": 19, "files": \[ { "fileId": "2222", "extensionId": "" } \] } | | | | **צורת התגובה: המערכת תחזיר בשם הפרמטר שקבעתם את שם הקובץ ומידע נוסף יתווסף עם שם מוביל מופרד עם מקף תחתון כדלהלן** לURL יתווסף ערכים כדלהלן: {שם הפרמטר}=שם הקובץ שנוצר {PATH\_שם הפרמטר}=נתיב מלא של הקובץ {DIGIT\_שם הפרמטר}=מקש בו אושר ההודעה {SIZE\_שם הפרמטר}=משקל הקובץ ב MB {DURATION\_שם הפרמטר}=משך אורך שמע הקובץ בשניות {FILE\_שם הפרמטר}=שם הקובץ | | | | | | | | **נגן מדיה audioPlayer** | | | | במודול "נגן מדיה" עליכם לשלוח את מערך הקבצים להשמעה בערך files בסיום ההאזנה המערכת תשלח לכם חזרה את סטטוס ההאזנה ומשך האזנה לכל קובץ, ובנוסף הקובץ בו סיים את ההאזנה, ובאיזה נקודת זמן, באם תרצו ליצור "המשך האזנה מהמיקום האחרון" עליכם לשמור את נקודת הזמן בו המאזין עצר, ולהמשיך את ההשמעה מנקודת הזמן בו עצר לתשומת לב\! מודול המשך האזנה אחרונה לא פועל על נגן מדיה מAPI ויש ליישם זאת עצמאית | | | | type | audioPlayer | סוג המודול | | name | דוגמה: "myParameter" | שם הערך שישלח חזרה עם אישור ההקלטה | | startFile | | מס. קובץ במערך הקבצים להתחיל את ההשמעה (ספירה מ 1\) | | startSecond | | מיקום במילי שניות להתחיל את ההשמעה (כל שניה \= 1,000) | | beepPlay | YES / NO | השמעת "ביפ" בין ההשמעות (ברירת מחדל YES) | | playLength | YES / NO | השמעת אורך הקובץ (ברירת מחדל NO) \-בהשמעת שלא מתחילת הקובץ ערך זה לא יופעל | | digitsSource | | מקור הגדרת המקשים template \= תבנית שמורה (יש להזין את מזהה התבנית בערך "playTemplate") כל ערך אחר \- הגדרה מקומית | | playTemplate | | מזהה תבנית הגדרת מקשים | | keyActions | | מיפוי מקשים מלא לניגון \- אובייקט מקש→פעולה. פעולות אפשריות: end (יציאה), next (קובץ הבא), back (קובץ קודם), secondsForward/secondsBack (דילוג בשניות), minutesForward/minutesBack (דילוג בדקות), break (השהיה/המשך), speedUp/speedDown (מהירות), volumeUp/volumeDown (עוצמה), lastPositions (חזרה למיקום קודם), none (לא פעיל), **apiCall (קריאה ל-API \- ראה "שליטה בנגן" להלן)** | | apiUrls | | למקשים שהוגדרו apiCall \- אובייקט מקש→כתובת ה-API שתיקרא בלחיצה. דוגמה: {"5": "https://your-server.com/player-key"} | | apiAfters | | למקשי apiCall \- מה קורה בסיום הקריאה כשלא הוחזרה פעולת playerControl: resume (המשך מאותו מיקום \- ברירת מחדל) / restart (מההתחלה) / next (קובץ הבא) / exit (יציאה מהנגן) | | files | | אובייקט קבצים להשמעה \- ראה להלן | | **דוגמה לשימוש במודול:** { "type": "audioPlayer", "name": "listen", "startFile": 1, "startSecond": 0, "beepPlay": "NO", "files": \[ { "fileId": "2222", "extensionId": "" } \] } | | | | | | | | | | | | **דוגמה עם מקש API חכם:** { "type": "audioPlayer", "name": "listen", "files": \[ { "fileId": "2222" } \], "keyActions": { "1": "secondsBack", "3": "secondsForward", "5": "apiCall", "0": "end" }, "apiUrls": { "5": "https://your-server.com/player-key" }, "apiAfters": { "5": "resume" } } | | | | | | | | **שליטה בנגן \- מקש API בזמן השמעה (playerControl)** | | | | בנגן המדיה (בהגדרות השלוחה בממשק, בתבנית מקשים, או ב-keyActions של מודול audioPlayer) ניתן להגדיר לכל מקש את הפעולה **apiCall** \- "קריאה ל-API". בלחיצה על המקש באמצע ההשמעה, המרכזיה קוראת לכתובת שהוגדרה למקש ומבצעת את פעולות ה-JSON שיוחזרו \- **בדיוק כמו כל מודול API במסמך זה** (השמעת קובץ/טקסט, תפריט, הקלטה, גבייה, מעבר לשלוחה...). בנוסף לפרמטרים הקבועים, בקריאה יישלחו: event=playerKey, playerKey=המקש שנלחץ, playerFileId=מזהה הקובץ, playerFileName=שם המערכת של הקובץ, playerFileTitle=השם התצוגתי, playerPosition=המיקום בקובץ בשניות (למשל 73.4), playerFileIndex=מספר הקובץ ברצף (מ-1), playerFilesCount=סך הקבצים. בתשובה ניתן להחזיר \- בנוסף לכל מודול רגיל \- את פעולת playerControl שקובעת מה הנגן יעשה כשהשליטה חוזרת אליו: | | | | type | playerControl | סוג הפעולה | | action | | resume \= המשך מאותו מיקום (ברירת המחדל גם כשאין playerControl בתשובה) restart \= השמעת הקובץ מההתחלה position \= קפיצה למיקום מוחלט (לפי הערך position) secondsForward / secondsBack \= דילוג קדימה/אחורה בשניות (לפי seconds, ברירת מחדל 10\) minutesForward / minutesBack \= דילוג קדימה/אחורה בדקות (לפי minutes, ברירת מחדל 10\) next / back \= מעבר לקובץ הבא/הקודם speedUp / speedDown \= שינוי מהירות בדרגה volumeUp / volumeDown \= שינוי עוצמה בדרגה lastPositions \= תפריט חזרה למיקום קודם end / exit \= יציאה מהנגן | | seconds | | כמות שניות ל-secondsForward/secondsBack (ברירת מחדל 10\) | | minutes | | כמות דקות ל-minutesForward/minutesBack (ברירת מחדל 10\) | | position | | מיקום מוחלט בשניות עבור action=position (למשל 95.5) | | **דוגמה \- השמעת הודעה ואז קפיצה למיקום:** \[ { "type": "simpleMessage", "files": \[ { "text": "מדלג לפרק הבא" } \] }, { "type": "playerControl", "action": "position", "position": 300 } \] | | | | **דוגמה \- שמירת סימניה בשרת שלכם והמשך האזנה מאותו מיקום:** \[ { "type": "simpleMessage", "files": \[ { "text": "הסימניה נשמרה" } \] }, { "type": "playerControl", "action": "resume" } \] | | | | **כללים:** 1\. ללא playerControl בתשובה \- הנגן פועל לפי הגדרת "בסיום פעולת ה-API" של המקש (resume/restart/next/exit). 2\. אם התשובה העבירה את השיחה לשלוחה אחרת (goTo / extensionChange / switchSystem) \- ההשמעה לא תחודש. 3\. playerControl מבוצע אחרי שכל שאר הפעולות באותה תשובה הסתיימו (קודם ההודעה, אחר-כך הדילוג), **ומסיים את שיחת ה-API** \- ערכי קלט שנאספו באותה תשובה לא יישלחו חזרה; לאיסוף קלט יש להחזיר קודם את המודול לבד, ובקריאה החוזרת להחזיר playerControl. 4\. מחוץ להקשר של מקש-נגן, playerControl לא עושה דבר. | | | | | | | | | | | | **ניתוב שיחה בסיסי** | | | | type | simpleRouting | סוג המודול | | name | דוגמה: "myParameter" | שם הערך שישלח חזרה עם סטטוס ביצוע השיחה | | dialPhone | | מספר טלפון לחיוג **(חובה מספר טלפון ישראלי נייד או נייח)** | | displayNumber | | מספר שיופיע על הצג **(אם ריק יופיע המספר של המאזין)** | | addDigits | | אם לא מוגדר זיהוי יוצא, ניתן להגדיר ספרות שיצורפו למספרו של הלקוח (לדוגמה, ניתן להגדיר ספרות 123456, ומספר טלפון 0501234567 יופיע 0501234567123456\) | | routingMusic | no/yes | אם מוגדר no לא יושמע מוזיקה בהמתנה אלא צליל החיוג הרגיל | | ringSec | | הגבלת משך החיוג \- בשניות | | limit | | הגבלת משך השיחה \- בשניות | | endCall | yes/no | מה קורה כשהצד המחוייג מנתק **לאחר** שהשיחה נענתה. ברירת מחדל yes \= השיחה מסתיימת גם עבור המתקשר. no \= המתקשר נשאר על הקו והזרימה ממשיכה לפעולה הבאה (למשל הודעת סיום, סקר שביעות רצון או ניתוב לנציג אחר). באין מענה / תפוס / שגיאה הזרימה ממשיכה תמיד, ללא קשר לערך זה. **שימו לב:** ניתוק של המתקשר עצמו מסיים את השיחה בכל מקרה | | cancelKey | yes/no | מקש ביטול: אם yes, המתקשר יכול להקיש \* בזמן שהיעד מצלצל. החיוג מבוטל, המתקשר נשאר על הקו והזרימה חוזרת לשרת עם סטטוס CANCEL ועם הפרמטר CANCELKEY\_name=yes (להבדיל מ-CANCEL רגיל שבו המתקשר עצמו ניתק). המקש הוא \* בלבד. הקשת \* אחרי שהיעד ענה מנתקת את היעד ומחזירה את המתקשר לזרימה עם ANSWER (בשילוב endCall=no). ברירת מחדל: ללא מקש ביטול | | campaignBilling | | מזהה קמפיין, לשיוך לקמפיין עבור מעקב אחר חיוב היחידות | | **דוגמה לשימוש במודול:** { "type": "simpleRouting", "name": "dial", "dialPhone": "0501234567", "displayNumber": "", "addDigits": "0005", "routingMusic": "yes", "ringSec": 15, "limit": "", "endCall": "no", "cancelKey": "yes" } | | | | | | | | **ניתוב שיחה IP** | | | | type | ipRouting | סוג המודול | | name | דוגמה: "myParameter" | שם הערך שישלח חזרה עם סטטוס ביצוע השיחה | | dialPhone | | מספר שלוחה לחיוג | | dialIP | | כתובת IP | | displayNumber | | מספר שיופיע על הצג **(אם ריק יופיע המספר של המאזין)** | | routingMusic | no/yes | אם מוגדר no לא יושמע מוזיקה בהמתנה אלא צליל החיוג הרגיל | | ringSec | | הגבלת משך החיוג \- בשניות | | limit | | הגבלת משך השיחה \- בשניות | | endCall | yes/no | זהה ל-simpleRouting \- ברירת מחדל yes מסיימת את השיחה כשהצד המחוייג מנתק, no משאירה את המתקשר על הקו וממשיכה לפעולה הבאה | | cancelKey | yes/no | זהה ל-simpleRouting \- \* בזמן הצלצול מבטל את החיוג ומחזיר את המתקשר לזרימה עם CANCEL ו-CANCELKEY\_name=yes | | **דוגמה לשימוש במודול:** { "type": "ipRouting", "name": "dial", "dialPhone": "105", "dialIP": "123.456.789.000", "displayNumber": "", "routingMusic": "yes", "ringSec": 15, "limit": "", "endCall": "no" } | | | | | | | | **ניתוב לתור / Router** | | | | ניתוב השיחה ל-Router/תור מוגדר מראש לפי מזהה. ה-Router אחראי על חלוקת השיחה לנציגים, סדר התור ומוזיקת ההמתנה כפי שהוגדר בממשק הניהול. | | | | type | queueRouting | סוג המודול | | routerId | | מזהה ה-Router/תור אליו לנתב | | sysNum | | מספר מערכת \- רלוונטי רק במערכות מכירה (Sales) | | **דוגמה לשימוש במודול:** { "type": "queueRouting", "routerId": "42" } | | | | | | | | **מעבר לשלוחה אחרת** | | | | בחירת היעד באחד מארבעה פרמטרים (לפי סדר עדיפות) \- לפי נתיב או לפי מזהה (ID). type יכול להיות "goTo" או "extensionChange" (זהה). | | | | type | goTo | סוג המודול | | goTo | | נתיב השלוחה (path) | | extensionPathChange | | נתיב השלוחה (path) \- זהה ל-goTo, עדיפות גבוהה יותר | | extensionIdChange | | מזהה השלוחה המדויק (ID), ללא תרגום נתיב | | extensionChange | | מזהה השלוחה המדויק (ID) \- ברירת המחדל אם לא נשלח אחר | | **דוגמה לשימוש במודול:** { "type": "goTo", "goTo": "1/3" } | | | | | | | | **מעבר למערכת אחרת** | | | | מעביר את השיחה למערכת (חשבון מרכזיה) אחרת לגמרי. המערכת המקורית נשמרת ב"מחסנית מעבר" כדי לאפשר חזרה אליה עם switchReturn. תנאים: הזוג מקור→יעד מאושר בטבלת ivr\_system\_switch\_allowed; targetNum שונה מהמערכת הנוכחית וקיים; עומק מעבר מרבי 5. אם תנאי לא מתקיים \- המעבר לא מתבצע. | | | | type | switchSystem | סוג המודול | | targetNum | | מספר המערכת (החשבון) שאליה לעבור | | targetPath | | נתיב השלוחה במערכת היעד שבה להתחיל (אופציונלי) | | **דוגמה לשימוש במודול:** { "type": "switchSystem", "targetNum": "2005", "targetPath": "1/3" } | | | | | | | | **חזרה ממערכת (switchReturn)** | | | | מחזיר את השיחה למערכת המקורית שממנה הגיעה דרך switchSystem (שולף את המסגרת האחרונה ממחסנית המעבר). אם המחסנית ריקה \- ההתנהגות נקבעת לפי noSourceAction. | | | | type | switchReturn | סוג המודול | | returnPath | | נתיב לחזרה במערכת המקור (אופציונלי) | | noSourceAction | hangup/goToPath | מה לעשות כשאין מערכת מקור במחסנית: hangup (ברירת מחדל) או goToPath | | goToPath | | נתיב לקפיצה כש-noSourceAction \= goToPath | | **דוגמה לשימוש במודול:** { "type": "switchReturn", "noSourceAction": "hangup" } | | | | | | | | **ניתוק השיחה** | | | | type | hangup | סוג המודול | | **דוגמה לשימוש במודול:** { "type": "hangup" } | | | | **החלפת לינק** | | | | type | changeUrl | סוג המודול (גם "changeLink") | | url | | הלינק החדש שאליו המרכזיה תפנה בהמשך. אם הלינק כולל פרמטרים הם הופכים לפרמטרים הקבועים של הכתובת. אם לא צוין \- נשארים על אותו לינק | | clearRequest | no/yes | האם לנקות את ערכי ה-REQUEST שנצברו. ברירת מחדל: yes (ניקוי). הפרמטרים הקבועים (addParams) תמיד נשמרים | | **דוגמה לשימוש במודול:** { "type": "changeUrl", "url": "https://my.server/api?env=prod", "clearRequest": "yes" } אחרי החלפת הלינק המרכזיה פונה מיד ללינק החדש לפנייה נוספת. | | | | **ערכים כלליים לניהול ה-REQUEST (לא type \- ניתן בהגדרות השלוחה או בתוך כל תגובה)** | | | | addParams | | ערכים קבועים (מפתח=ערך) שמצורפים לכל פנייה לשרת. שימוש נפוץ: דגלים קבועים לשמירת מיקום בשיחה. נשלחים בכל callback, שורדים ניקוי REQUEST (כולל clearRequest), ואינם נמחקים בין הפניות. שליחה חוזרת של אותו מפתח מעדכנת את הערך. פורמטים: { "pos": "step3" } או \[{ "key": "pos", "value": "step3" }\] | | removeParams | | מערך שמות מפתחות שיוסרו מה-REQUEST המצטבר מכאן והלאה. חל רק על הערכים שבשליטתכם \- פרמטרי המערכת (PBX...) ופרמטרי הכתובת המקוריים תמיד נשמרים. פורמט: \["otp", "tmp"\] | | **דוגמה \- קביעת דגל מיקום בלי להחליף לינק:** { "type": "changeUrl", "clearRequest": "no", "addParams": { "pos": "menu\_main" }, "removeParams": \["otp"\] } | | | | paramsMode | chain/last | אופן צבירת הערכים שנקלטו בין הפניות. chain (ברירת מחדל) \= צובר את כל הערכים שנקלטו לאורך השיחה. last \= שומר רק את ערכי המשתמש מהתגובה הקודמת. נקבע בהגדרות השלוחה. | | | | | | **שיטת שליחה \- GET (ברירת מחדל) / POST** | | | | ברירת מחדל: **GET** \- כל הפרמטרים (מערכת \+ קלט מצטבר) יושבים במחרוזת ה-URL אחרי ה-? מופרדים ב-&, כולל ערכים שחוזרים על עצמם. **צורה זו אינה משתנה.** ניתן לבחור **POST**, ואז אותם פרמטרים בדיוק (כולל כפילויות והסדר) עוברים לגוף הבקשה (application/x-www-form-urlencoded); הכתובת שהגדרתם עם ה-query שלה נשארת ב-URL. קִראו מ-$\_POST או $\_REQUEST. | | | | method | POST | בהגדרת השלוחה \- כל השיחה תישלח ב-POST מההתחלה (חלופה: post=true). | | post (בהגדרת השלוחה) | true | כמו method=POST \- כל השיחה ב-POST. | | post (בתוך תגובה, נקודתית לערך) | true | מדליק POST מהקריאה החוזרת ואילך, ונשאר עד סוף השיחה (דביק). שימוש נפוץ: getDTMF של אשראי, יחד עם maskLog. | | | | | | **החלפת הודעות מערכת (systemMessages)** | | | | דריסת הודעות מערכת (קודי S...) לאורך השיחה \- למשל הודעות מודול האשראי. ניתן לשלוח כ-type עצמאי, או לצרף לכל מודול (מוחל לפני שהמודול רץ). כל ערך הוא מערך-קבצים רגיל (name/text/SF/number/digits...). ערך ריק מחזיר את הקוד לברירת המחדל שבמסד. | | | | type | systemMessages | סוג המודול (בשליחה עצמאית) | | systemMessages | | מפה { "S3008": \[...files...\] } או רשימה \[{ "sm": "S3008", "files": \[...\] }\] | | **דוגמה \- דריסת הודעת מערכת:** { "type": "systemMessages", "systemMessages": { "S3008": \[ { "text": "אנא הזן את מספר הכרטיס" } \] } } | | | | | | | | **תמלול הקלטה לדיבור** | | | | עלות התמלול 0.25 יחידות לכל 10 שניות קובץ | | | | type | record | סוג המודול | | name | דוגמה: "myParameter" | שם הערך שישלח חזרה עם אישור ההקלטה | | max | | מקסימום אורך ההקלטה \- בשניות עד 10 שניות | | min | | מינימום אורך ההקלטה \- בשניות | | fileName | | שם הקובץ כפי שישמר במערכת | | saveFolder | | מזהה שלוחה לשמירת ההקלטה \- עבור שמירה לתקיה שאינה השלוחה הנוכחית **(יש להזין ID של שלוחה)** | | hangupSave | yes/no | מה קורה כשהמתקשר מנתק **באמצע** ההקלטה. yes \= ההקלטה נשמרת רגיל בכל אורך, בדיוק כמו הקלטה שאושרה. ברירת מחדל no \= ההקלטה נשמרת לסל המחזור, ורק אם ארכה 4 שניות ומעלה \- קצרה מזה לא נשמרת כלל | | campaignBilling | | מזהה קמפיין, לשיוך לקמפיין עבור מעקב נח אחר חיוב היחידות | | files | | אובייקט קבצים להשמעה \- ראה להלן | | **דוגמה לשימוש במודול:** { "type": "stt", "name": "myRecord", "max": 6, "min": 2, "fileName": "record\_XXX", "files": \[ { "fileId": "2222", "extensionId": "" } \] } | | | | **צורת התגובה: המערכת תחזיר בשם הפרמטר שקבעתם את שם הקובץ ומידע נוסף יתווסף עם שם מוביל מופרד עם מקף תחתון כדלהלן** לURL יתווסף ערכים כדלהלן: {שם הפרמטר}=תמלול ההקלטה {PATH\_שם הפרמטר}=נתיב מלא של הקובץ {DIGIT\_שם הפרמטר}=מקש בו אושר ההודעה {SIZE\_שם הפרמטר}=משקל הקובץ ב MB {DURATION\_שם הפרמטר}=משך אורך שמע הקובץ בשניות {FILE\_שם הפרמטר}=שם הקובץ {FILEID\_שם הפרמטר}=מזהה הקובץ במערכת | | | | **משיכת קובץ השמע לשרת שלכם:** ה-FILEID הוא המפתח להורדה או להשמעה בדפדפן: ivrFilesApi.php?action=fileDownload\&audio={FILEID}\&apiKey=... \- הורדה כקובץ. הוספת play=1 מחזירה השמעה ישירה המתאימה לתגית \. הקובץ מוגש תמיד כ-MP3. | | | | **כשהמתקשר מנתק באמצע ההקלטה:** ההקלטה נשמרת ואותה חבילת פרמטרים בדיוק נשלחת אליכם, כולל FILEID \- כך שניתן למשוך את האודיו בדיוק כמו בהקלטה שאושרה. ההבדל היחיד: DIGIT יחזור ריק, כי לא הוקש מקש אישור. מומלץ להוסיף "hangupSave": "yes" \- בלעדיו ההקלטה נכנסת לסל המחזור, והקלטות קצרות מ-4 שניות לא נשמרות כלל. | | | | | | | | **סליקת אשראי** | | | | מבצע סליקת כרטיס אשראי מול הסולק (Nedarim Plus) באמצע התזרים. אוסף מהמתקשר את פרטי הכרטיס, שולח לסולק, ומחזיר סטטוס + מספר אישור. מספר כרטיס מלא / CVV / ת"ז אינם נשמרים. | | | | type | creditCard | סוג המודול | | name | דוגמה: "pay" | שם לוגי \- תחתיו יוחזרו הסטטוס ומספר האישור | | sum | | סכום לחיוב (0 \= יבקש מהמתקשר להזין סכום) | | sumChangeable | yes/no | yes \= משמיע את הסכום ומבקש אישור | | cvv | yes/no | yes \= יבקש CVV (ברירת מחדל yes) | | tz | yes/no | yes \= יבקש תעודת זהות (ברירת מחדל yes) | | payments | | מקסימום תשלומים (1 \= לא ישאל) | | paymentsMode | regular/keva/ask/kevaMonthly | אופן פריסת התשלומים: regular \= חיוב רגיל (תפיסת מסגרת); keva \= הוראת קבע ללא תפיסת מסגרת; ask \= המתקשר בוחר בשיחה (1 \= רגיל, 2 \= הוראת קבע ללא תפיסת מסגרת); kevaMonthly \= **הקמת הוראת קבע לפי סכום חודשי קבוע** \- הסכום (sum או מה שהוקש) הוא הסכום החודשי, ללא הגבלת מספר חודשים (עד ביטול), ושאלת התשלומים לא מושמעת. פעיל בעיקר כש-payments\>1 (למעט kevaMonthly) | | kevaMonths | | רק ל-paymentsMode=kevaMonthly: סך מספר החיובים החודשיים. ריק/0 \= ללא הגבלת חודשים | | kevaDay | | רק ל-paymentsMode=kevaMonthly: יום החיוב בחודש (1\-28). ריק \= היום בחודש שבו בוצעה השיחה | | category | | קטגוריה לסולק (טקסט חופשי, נתמך בעברית) | | terminal | | מסוף בסולק | | noSum | yes/no | yes \= משתיק את הכרזת הסכום (רק כש-sumChangeable=no) | | noFailExit | yes/no | yes \= בכשל לא יוצא מהמודול אלא חוזר לבקש פרטי כרטיס שוב \- **אין מקש יציאה\!** | | **צורת התגובה:** לURL יתווסף: {שם הפרמטר}=סטטוס, {CONFIRM\_שם הפרמטר}=מספר האישור | | | | **דוגמה לשימוש במודול:** { "type": "creditCard", "name": "pay", "sum": 100, "payments": 3, "paymentsMode": "ask", "terminal": "" } | | | | | | | | **השמעת קמפיינים (playAllCampaigns)** | | | | משמיע למאזין את הקמפיינים הקוליים שממתינים עבורו. (טווח הימים אחורה נקבע בהגדרות השלוחה.) | | | | type | playAllCampaigns | סוג המודול | | **דוגמה לשימוש במודול:** { "type": "playAllCampaigns" } | | | | | | | | **השמעת הקמפיין האחרון (lastCampaign)** | | | | משמיע למאזין את הקמפיין האחרון שנשלח. ניתן לבחור לפי מה לאתר, ואף לדרוס את הטלפון/המחוייג המשמשים לחיפוש (למשל לפי מספר שנאסף בשיחה). | | | | type | lastCampaign | סוג המודול | | playBy | phone / did / templete | לפי מה לאתר: phone \= טלפון מקבל ההודעה (ברירת מחדל); did \= המספר המחוייג (הקמפיין האחרון על אותו מספר); templete \= תבנית ברירת המחדל | | phone | מספר טלפון | טלפון מקבל ההודעה לאיתור (ברירת מחדל: המחייג של השיחה) | | did | מספר | המספר המחוייג לאיתור (ברירת מחדל: המחוייג של השיחה) | | campaignId | מזהה קמפיין | השמעת קמפיין ספציפי לפי מזהה \- גובר על playBy | | **דוגמה:** { "type": "lastCampaign", "playBy": "phone", "phone": "0501234567" } | | | **אובייקט קבצי שמע:** | | פרמטר | הסבר | | :---: | ----- | ----- | | באובייקט קבצי השמע ניתן להגדיר את תוכן ההשמעה | | | | אפשרויות ההשמעה הם: | | | | **קובץ שמע במערכת קיימים שני אפשרויות 1\. ID של קובץ 2\. שם קובץ** | fileId | fileName | fileId=מזהה-ID של הקובץ, fileName=שם הקובץ (ללא הסיומת) | | | extensionId extensionPath | אם הקובץ הינו **משלוחה אחרת** יש לרשום את מזהה השלוחה | | **טקסט** | text | הטקסט להשמעה | | **קול ההקראה (TTS)** | voice | רלוונטי רק עם `text`. ברירת המחדל היא קול גוגל סטנדרטי (`he-IL-Standard-D`) ללא עלות נוספת. ניתן להעביר ערך מתוך רשימת קולות Gemini AI (16 גבריים + 14 נשיים) — **בתוספת תשלום**. רשימה מלאה ראה להלן. | | **מספר** | number | המספר להשמעה (לדוג' 123 יושמע כ: מאה עשרים ושלוש) | | **ספרות** | digits | הספרות להשמעה (לדוג' 123 יושמע כ: אחת שתים שלוש) | | **לינק לקובץ \- לינק** (לשימוש יש לפנות לשירות לקוחות) | fileLink | יש לרשום לינק לקובץ לתשומת לב\! המערכת שומרת את הקובץ בקאש למשך כמה ימים, אם התוכן השתנה, יש לשלוח fileName שונה כדי שהמערכת תטען את הקובץ החדש | | **לינק לקובץ \- שם פנימי** | fileName | במקרה של שימוש בלינק לקובץ חובה לרשום שם הקובץ לשימוש פנימי | | **פעיל רק עבור מודול simpleMenu** | activatedKeys | מקשים פעילים לקובץ זה, יש לרשום ברצף את כל המקשים ערך ריק / לא קיים פירושו כל המקשים מותרים (כמו להגדיר \- 1234567890\*\#) ניתן לרשום NONE כדי להשבית לחלוטין הקשות בקובץ זה ניתן לרשום SKIP כדי להגדיר שהקשה יעבור להשמעה הבאה ניתן להשתמש בכל המקשים 1234567890\*\# | ### בחירת קול הקראה (TTS) — `voice` הפרמטר `voice` תקף רק לפריטים מסוג `text`. עבור `fileId` / `fileName` / `fileLink` / `number` / `digits` הוא יתעלם. | מצב | איך משתמשים | עלות | | --- | --- | --- | | **ברירת מחדל — Google Cloud TTS** | להשמיט את `voice` (או להעביר `"voice": "he-IL-Standard-D"`) | כלול בשירות — **ללא עלות נוספת** | | **קולות Gemini AI** | להעביר `"voice": ""` מתוך הטבלה למטה | **בתוספת תשלום** — נגבה לפי שימוש | **דוגמה:** ```json { "text": "שלום וברוך הבא", "voice": "Charon" } ``` #### רשימת ערכי `voice` חוקיים **ברירת מחדל — Google Cloud TTS (ללא עלות):** | `voice` | תיאור | | --- | --- | | `he-IL-Standard-D` | קול גוגל סטנדרטי בעברית (פעיל אם לא הועבר `voice`) | **Gemini AI — קולות גבריים (16) — בתשלום:** | `voice` | אופי | | --- | --- | | `Charon` | מידעי | | `Puck` | שמח | | `Fenrir` | נמרץ | | `Orus` | תקיף | | `Enceladus` | רך | | `Iapetus` | צלול | | `Umbriel` | רגוע | | `Algieba` | חלק | | `Algenib` | מחוספס | | `Rasalgethi` | מידעי | | `Alnilam` | תקיף | | `Schedar` | מאוזן | | `Achird` | ידידותי | | `Zubenelgenubi` | יומיומי | | `Sadachbia` | חי | | `Sadaltager` | יודע דבר | **Gemini AI — קולות נשיים (14) — בתשלום:** | `voice` | אופי | | --- | --- | | `Kore` | תקיפה | | `Zephyr` | מאירה | | `Leda` | צעירה | | `Aoede` | קלילה | | `Callirrhoe` | רגועה | | `Autonoe` | מאירה | | `Despina` | חלקה | | `Erinome` | צלולה | | `Laomedeia` | שמחה | | `Achernar` | רכה | | `Gacrux` | בוגרת | | `Pulcherrima` | ישירה | | `Vindemiatrix` | עדינה | | `Sulafat` | חמימה |