מודול API - תקשור עם מחשבים וממשקי נתונים חיצוניים

[ימות המשיח]

ב"ה

מודול API

הסבר קצר על המודול

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

מודול זה יתכן ויהיה בעתיד בתשלום
עם זאת כרגע המודול חינמי עד להודעה אחרת בפורום

---

וכעת להגדרות המודול

---

• הגדרות כלליות

---

• שליחת נתונים לשרת

---

• תשובת שרת

---

• read

---

• לוגים

---

קישורים לתוספים שניתנים להגדרה בכל מודול

רשימת כל ההגדרות שניתנות להטמעה בכל מודול

הגדרות זיהוי בכניסה לשלוחה

הסבר על הודעת ברוכים הבאים (הודעה ראשונה בשלוחה)

הרשאות כניסה לשלוחה

---

לשאלות ותמיכה - פורום מפתחים API

[eliyahu]

הגדרות כלליות

---

הגדרת סוג שלוחה

type=api

---

כתובת URL לשליחת הפניות

api_link=https://example.com/YemotApi

כמובן שאחרי ה= יש לרשום את ה-URL של השרת שלכם

במידה ולא מוגדר URL המערכת תשמיע M1609 "לא מוגדר לינק" והמשתמש ייצא מהשלוחה

---

שיטת שליחה

ברירת מחדל המערכת שולחת את הפרטים בHTTP GET
במידת הצורך ניתן להגדיר שהפרטים יישלחו בHTTP POST
ההגדרה היא

api_url_post=yes

---

תיקיה שממנה יושמעו הקבצים

ברירת מחדל כל הקבצים המושמעים למשתמש נמצאים בשלוחה הנוכחית
ניתן להגדיר מיקום שונה לקבצים
ההגדרה היא

api_dir=/5/6

בדוגמה, הקבצים שיופעלו הם הקבצים שבתיקייה 5/6 (מלבד הודעות המערכת)
הערה חשובה: שימו לב שכתובת תיקייה חייבת להתחיל בסלש ( / ) ולהסתיים ללא סלש.

---

שליחה בניתוק שיחה

לאחר שהמשתמש ניתק את השיחה (מכל שלוחה שהיא במערכת) המערכת שולחת לשרת את כל הנתונים שנאספו עד עכשיו בשלוחה, בתוספת הפרמטרים הבאים

• hangup=yes - פרמטר שמציין שהמשתמש ניתק את השיחה
• ApiHangupExtension=שלוחה פרמטר שמציין את השלוחה בה המשתמש ניתק את השיחה (לדוגמה אם המשתמש ניתק בשלוחה 3 אז יופיע בערך ApiHangupExtension=/3)

כברירת מחדל, שליחת הנתונים היא לכתובת שהוגדרה בשלוחה.
ניתן להגדיר שבניתוק ישלח ללינק אחר
ההגדרה היא

api_hangup_link=https://example.com/YemotApi/hangup

כדי לבטל את השליחה בניתוק שיחה יש להגדיר

api_hangup_send=no

---

מעבר בסיום

הערה: ההגדרות הבאות רלוונטיות רק במקרים שאין התייחסות בתגובת השרת לאן להעביר את המשתמש

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

api_end_goto=/5/8

בדוגמה, בסיום המשתמש יעבור לשלוחה 5/8 שתחת התיקייה הראשית

[eliyahu]

שליחת נתונים לשרת

---

את סוגי הנתונים שנשלחים לשרת ניתן לחלק ל-3 חלקים

1. פרמטרים וערכים קבועים שנשלחים לשרת
2. פרמטרים עם ערכים של פרטי השיחה
3. הנתונים שהתקבלו מהמשתמש

שימו לב! כל הנתונים הנשלחים לשרת הינם רשות, כך שאין חובה להגדיר את כל סוגי הנתונים לשליחה.
למידע נוסף ראה בהרחבה להלן

---

פרמטרים קבועים שנשלחים לשרת

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

(הערה: לא ניתן לצרף פרמטרים הנשלחים כברירת מחדל (ראה להלן "פרמטרים עם פרטי השיחה"))

לדוגמה אם ברצונכם שבכל פנייה לשרת המערכת תצרף את הפרמטרים foo=111 bar=222 יש להגדיר בהגדרות השלוחה

api_add_0=foo=111
api_add_1=bar=222

במקרה כזה הבקשה ב-GET תראה כך

https://example.com/YemotApi?foo=111&bar=222

כמובן שניתן לצרף פרמטרים נוספים (api_add_X=), כשבמקום X יש לרשום את מספר הפרמטר.
שימו לב שחשוב לשמור על רצף סידורי החל מהספרה 0.

---

פרמטרים עם פרטי השיחה

כברירת מחדל בכל פנייה הנשלחת לשרת המערכת מצרפת פרמטרים עם ערכים של פרטי השיחה הנוכחית
הפרמטרים הנשלחים הם

• ApiCallId=מזהה ייחודי לאורך השיחה
• ApiPhone=מספר הטלפון של המשתמש
• ApiDID= מספר טלפון הראשי של המערכת שלכם
• ApiRealDID=המספר אליו חייג המשתמש.
  במידה ויש כמה מספרים למערכת שלכם, והלקוח צלצל למספר משנה, הערך הזה יהיה שונה מהערך הקודם
• ApiExtension=שם התיקייה/שלוחה בה נמצא המשתמש
• ApiEnterID=במידה ובוצעה התחברות לפי זיהוי אישי, יצורף ערך זה המכיל את סוג ההתחברות וה-ID של המשתמש (מידע נוסף כאן)
• ApiEnterIDName= שם משויך לזיהוי האישי (כפי שמוסבר בערך של login_add_val_name=yes כאן)
  אם אין שם, הערך לא יצורף.
• ApiTime= זמן בשניות מ1970, Epoch, i.e., since 1970-01-01 00:00:00 UTC.

כדי לבטל את שליחת הפרמטרים הנ"ל או את חלקם יש להגדיר (בהתאמה)

api_call_id_send=no
api_phone_send=no
api_did_send=no
api_extension_send=no
api_enter_id_send=no
api_enter_id_name_send=no
api_time_send=no

---

במערכות בהם יש תמיכה ב'מספר שהפנה את השיחה' ניתן להוסיף הגדרה ולקבל גם אותו ההגדרה היא

api_add_directed_phone=yes

במקרה כזה יצורף גם הערך ReferredFrom עם מספר הטלפון שהפנה את השיחה
פרטים נוספים כאןhttps://f2.freeivr.co.il/topic/3077

---

קבלת נתונים מהמשתמש

הערה: ההגדרות המופיעות כאן הן עבור קבלת נתונים מהמשתמש לפני הפנייה לשרת. עבור קבלת נתונים מהמשתמש לאחר תשובת השרת ראה בהמשך השרשור הגדרות עבור read

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

לצורך כך יש לפעול לפי השלבים הבאים

---

שלב א

יש להעלות קובץ שמע לשלוחה עם השאלה שברצונכם להשמיע
סוג הקובץ יכול להיות בפורמט wav ogg עבור קבצי שמע או קובץ tts עבור הקראת טקסט (text to speech)

(הגדרות גלובליות עבור מנוע הקראת טקסט)

שמות הקבצים צריכים להיות ממוספרים במספר סידורי רציף החל מ-000.
סדר השמעת השאלות הוא מהקובץ הקטן לגדול (000 001 002 וכן הלאה).

---

שלב ב

יש להגדיר בהגדרות השלוחה את סוג השאלה (הקשה, הקלטה) והגדרות נוספות (שם הערך שיצורף ועוד)
ההגדרה עבור כל קובץ צריכה להתחיל כך

api_000=

בדוגמה, הגדרות עבור קובץ 000.
בהמשך השורה יש לציין את הערכים להגדרה כאשר בין ערך לערך יש להפריד עם פסיק ,
במידה וברצונכם להשאיר את ברירת המחדל יש להשאיר את הערך ריק (כלומר ,,)

הגדרות לדוגמה (ראה להלן בהרחבה)

api_000=ID,yes,5,4,50,Number,yes,no,*/,
api_001=ZIP,yes,8,4,7,Number,yes,yes,*/
api_002=AAA,yes,1,1,7,Number,yes,yes,*/,*#123456
api_003=BBB,yes,2,2,7,Number,yes,yes,*/,11.12.13.14,3,Ok,null
api_004=CCC,yes,voice
api_005=DDD,yes,voice,en-US,no
api_006=EEE,yes,voice,en-US,,30
api_007=ZAW,yes,record,/1/2,file_name,no,yes,yes
api_008=FFF,,voice,,,,record,6,9

---

הסבר על הערכים

---

הערך הראשון

בערך זה יש להגדיר את שם הפרמטר שיצורף לנתון שהתקבל
בדוגמה לעיל ניתן לראות ששם הפרמטר שצורף לנתון שהתקבל בקובץ 000 הוא ID ושם הפרמטר שצורף לנתון שהתקבל בקובץ 001 הוא ZIP

---

הערך השני

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

---

הערך השלישי

בערך זה ניתן לקבוע את סוג הנתון שיילקח מהמשתמש
האפשרויות הן

• הקשה
• הקלטה לשמירה במערכת
• הקלטה שתתמולל לטקסט שיישלח לשרת

כברירת מחדל סוג הנתון מוגדר להקשה
כדי להגדיר את סוג הנתון להקלטה שתישמר במערכת יש לכתוב record (כמו בדוגמה 007 למעלה)
כדי להגדיר את סוג הנתון להקלטה שתתומלל לטקסט שיישלח לשרת יש לכתוב voice (כמו בדוגמאות 004-006 למעלה)

---

שימו לב! הערכים הבאים הניתנים להגדרה (הערך הרביעי והלאה) משתנים בהתאם לסוג הנתון שהוגדר בערך השלישי. ולכן בהגדרות שיובאו להלן תהיה אבחנה בין סוגי הנתונים

---

הגדרות עבור הקשות

---

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

---

הערך הרביעי (הקשה)
בערך זה ניתן לקבוע את כמות הספרות המינימלית שהמשתמש יוכל להקיש
ברירת המחדל היא 1. כדי להגדיר כמות שונה יש לרשום את המספר הרצוי
(בדוגמה 000 למעלה ניתן לראות שהמינימום הוא 4)
במידה והמשתמש לא הקיש את כמות הספרות הנדרשת המערכת תשמיע M1035 "לא הקשתם את מינימום הספרות הנדרשות" והמשתמש יעבור להקשה מחדש של הנתון.

---

הערך החמישי (הקשה)
בערך זה ניתן להגדיר את אורך הזמן שהמערכת תמתין להקשת המשתמש
ברירת המחדל היא 7 שניות. ניתן להגדיר זמן המתנה שונה.
(בדוגמה 000 למעלה ניתן לראות שזמן ההמתנה שהוגדר הוא 50 שניות)
(ראה בנוסף ערכים 11 ו-12 להלן)

---

הערך השישי (הקשה)
בערך זה ניתן להגדיר באיזה צורה להשמיע למשתמש את מה שהוקש
מצ"ב טבלה

ההגדרה	פירוט
NO	לא ישמיע את מה שהוקש כלל
Number	משמיע את מה שהוקש בצורת מספר כלומר 22 יהיה "עשרים ושתים"
Digits	משמיע את מה שהוקש בצורת ספרות כלומר 22 המערכת תשמיע "שתים שתים"
Price	משמיע את מה שהוקש בצורת מחיר. לדוגמה: במידה והמשתמש הקיש 53 המערכת תשמיע "חמישים ושלוש שקלים". דוגמא נוספת: במידה והמשתמש הקיש הקיש 53 כוכבית 23, המערכת תשמיע "חמישים ושלוש שקלים ועשרים ושלוש אגורות". כמו כן בסטרינג שיישלח לשרת יופיע 53.23 (כלומר המערכת מחליפה את מקש הכוכבית בנקודה). הודעות המערכת הם:M1907 "שקלים" M1908 "ו.." M1909 "אגורות"
Time	משמיע את מה שהוקש בצורת שעה. כלומר 2359 המערכת תשמיע "עשרים ושלוש חמישים ותשע" (יש צורך להגדיר מינימום ומקסימום 4 ספרות)
Date	משמיע את ההקשה בצורת תאריך. כלומר 10122019 המערכת תשמיע "עשר דצמבר אלפיים ותשע עשרה" (יש צורך להגדיר מינימום ומקסימום 8 ספרות)
HebrewDate	משמיע את מה שהוקש בצורת תאריך עברי. כלומר 23125779 המערכת תשמיע "כ"ט אלול תשע"ט" (יש צורך להגדיר מינימום ומקסימום 8 ספרות)
TeudatZehut	ייתן להקיש תעודת זהות תקינה בלבד. המערכת תשמיע את ההקשה בצורת ספרות (יש צורך להגדיר מינימום 8 ספרות ומקסימום 9 ספרות)
Phone	ייתן להקיש רק מספר טלפון ישראלי תקין. המערכת תשמיע את ההקשה בצורת ספרות (יש צורך להגדיר מינימום 9 ספרות ומקסימום 10 ספרות). ראה עוד בערך החמש עשרה והשש עשרה
Alpha	בצורת אותיות, במקרה של הקשה טלפונית של ספרות זה ישמע כמו הקשת ספרות, במידה ויש אותיות כמו abc אז ישמעו את האותיות אחת אחרי השניה
HebrewKeyboard	המערכת תעביר את המשתמש להקלדה במקלדת עברית ובסיום ההקלדה תשמיע את מה שהוקלד במילים או באותיות. למידע אודות אפשרויות ההקשה במקלדת לחץ כאן (ראה בנוסף הערך ה14 להלן)
EnglishKeyboard	המערכת תעביר את המשתמש להקלדה במקלדת אנגלית ובסיום ההקלדה תשמיע את מה שהוקלד במילים או באותיות. למידע אודות אפשרויות ההקשה במקלדת לחץ כאן (ראה בנוסף הערך ה14 להלן)
EmailKeyboard	המערכת תעביר את המשתמש להקלדה במקלדת אנגלית מותאמת למייל (ללא סימן שאלה וסימן קריאה, וכן בהקשת שטורדל עזרה בהשלמת הספק) בסיום ההקלדה תשמיע את מה שהוקלד במילים או באותיות. למידע אודות אפשרויות ההקשה במקלדת לחץ כאן (ראה בנוסף הערך ה14 להלן)
DigitsKeyboard	המערכת תעביר את המשתמש להקלדה במקלדת ספרות כאשר המערכת תשמיע כל הקשה בצורה מיידית בהתאם למקשים שהוקשו. למידע אודות אפשרויות ההקשה במקלדת לחץ כאן. הערה חשובה במצב זה אין הגבלה של מינימום או מקסימום, והערכים של ההגבלה לא פעילים, מעלת מקלדת ספרות זה השמעת כל ספרה מיידית ללקוח. (ראה בנוסף הערך ה14 להלן)
File	משמיע למשתמש קובץ שמע בהתאם למה שהוקש. ראה להלן
TTS	משמיע למשתמש טקסט בהקראה ממוחשבת בהתאם למה שהוקש ראה להלן

File

לדוגמה - אם המשתמש הקיש 1 ישמע "מלפפון" ואם הקיש 2 ישמע "עגבנייה"
כדי שהמערכת תדע איזה קובץ להשמיע, יש לפתוח בתוך השלוחה תיקייה כשם המשתנה המופיע בערך הראשון (לדוגמה אם המשתנה הואZIP יש לפתוח תיקייה בשם ZIP) ובתוך התיקייה להכניס את קבצי השמע שרוצים שישמיע. (לדוגמה, למשתמש שהקיש 0 המערכת תשמיע את קובץ 000, למשתמש שהקיש 256 המערכת תשמיע את קובץ 256)

במידה ואין קובץ להשמעה המערכת תשמיע את מה שהוקש בצורת ספרות (Digits)
ניתן להגדיר שאם אין קובץ תואם להקשה אז שהמערכת תשמיע M1224 "בחירה לא חוקית" והמשתמש יעבור להקשה מחודשת של הנתון.
לצורך כך יש להגדיר בערך העשירי from_folder

TTS

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

111=מלפפון
112=עגבניות
113=גמבה

כלומר, מי שהקיש 111 ישמע "מלפפון" ומי שהקיש 112 ישמע "עגבניות".
במידה ואין טקסט מוגדר להשמעה המערכת תשמיע את מה שהוקש בצורת ספרות (Digits)
שימו לב, תיתכן אפשרות שאם קובץ השאלה (000 וכו') יהיה קובץ TTS, המערכת לא תקריא את הכתוב בקובץ TTS

---

הערך השביעי (הקשה)
ברירת מחדל המשתמש יכול להקיש על מקש *
כדי לחסום את מקש כוכבית יש להגדיר בערך זה yes
במקרה כזה במידה והמשתמש הקיש כוכבית המערכת תשמיע M1368 "לא ניתן להקיש מקש כוכבית" והמשתמש יעבור להקשה מחודשת של הנתון

---

הערך השמיני (הקשה)
האם הכמות של ההקשה יכולה להיות אפס
ברירת מחדל כמות יכולה להיות אפס. באם רוצים לחסום את זה (לדוגמה בכמות שקלים לתרומה שלא יהיה ניתן לתרום אפס) יש להגדיר yes בשביל לחסום את מקש אפס.
במקרה כזה במידה והכמות שהמשתמש הקיש עומדת על 0 המערכת תשמיע M1625 "הכמות לא יכולה להיות אפס" והמשתמש יעבור להקשה מחודשת של הנתון

---

הערך התשיעי (הקשה)
החלפת מקש בכל סימן אחר
לדוגמה במידה ואתם רוצים שישלח כתובת ספריה כאשר המפריד בין התיקיות זה /
בטלפון לא ניתן להקיש סלש
אבל ניתן לבקש מהלקוח להקיש כוכבית בין תיקייה לתיקייה
ולסמן להחליף את הכוכבית בסלש

ערך זה יכול להכיל 2 סימנים
הסימן הראשון את איזה ערך להחליף
הסימן השני זה מה לשים במקום מה שהוחלף

בדוגמה למעלה (000) מופיע
*/
כלומר להחליף את מקש כוכבית בסלש

---

הערך העשירי (הקשה)

בערך העשירי ניתן להגדיר איזה מקשים המשתמש יוכל להקיש
באם המשתמש יקיש מקש שלא מוגדר אז המערכת תודיע
M1224 "בחירה לא חוקית"
ברירת מחדל המשתמש יכול להקיש על כל המקשים ולכן אם הערך ריק - אז ניתן להקיש הכל

אם מדובר על הקשה של מינימום ומקסימום ספרה אחת (ערכים שלוש וארבע) אז ניתן לרשום את כל הספרות המורשות ברצף
שימו לב שבדוגמה של קובץ 002 מופיע מינימום ומקסימום ספרה אחת ומוגדר שניתן להקיש *#123456 כלומר את כל הספרות למעט 789 שאם יקיש אותם אז המערכת תודיע שהבחירה לא חוקית

אם מדובר על הקשה שמעל ספרה אחת, אז ניתן להפריד בין הערכים המותרים עם נקודה.
שימו לב שבדוגמא של קובץ 003 המינימום והמקסימום הם 2 ספרות,
ומוגדר שהמשתמש יכול לבחור רק 11 או 12 או 13 או 14 (11.12.13.14)

בדוגמאות למעלה בקבצים 000 ו-001 הערך ריק
בקובץ 002 מופיע *#123456
בקובץ 003 מופיע 11.12.13.14

---

הערך האחד עשר (הקשה)
ברירת מחדל במידה והמשתמש לא הקיש כלום ועבר הזמן שהוגדר להקשה (בערך החמישי) אז הנתון שהמערכת קולטת הוא ריק.
כמות הפעמים שהמערכת משמיעה את השאלה לפני שהיא מגדירה את הנתון כ"ריק" הוא פעם אחת
בערך זה ניתן להגדיר כמות פעמים שונה.
בדוגמה למעלה בקובץ 003 מוגדר שכמות הפעמים שהמערכת תשמיע את השאלה לפני שהיא מגדירה את הנתון כ"ריק" היא 3 פעמים.

---

הערך השנים עשר (הקשה)
ברירת מחדל, במידה והנתון שהתקבל הוא "ריק" (ראה ערך 11) המערכת משמיעה M1002 "לא הוקשה בחירה" והמשתמש עובר להקשה מחודשת של הנתון.
ניתן להגדיר שאם הנתון הוא ריק המערכת תתקדם הלאה. ההגדרה היא Ok.

---

הערך השלושה עשר (הקשה)
במידה והגדרתם בערך ה-12 שניתן להכניס נתון ריק
ברירת מחדל מה שנשלח לשרת תחת הערך של השאלה הוא None. בערך זה ניתן להגדיר טקסט שונה.
(בדוגמה למעלה בקובץ 003, מה שנשלח לשרת זה null)

---

הערך הארבעה עשר (הקשה)
במידה והגדרתם בערך ה-6 מצב מקלדת (עברית / אנגלית / מקלדת מייל /מקלדת ספרות)
ברירת מחדל המשתמש יכול בתפריט סיום או ביטול (במקש כוכבית) לשנות את המקלדת למקלדת מסוג שונה.
אם ברצונכם שהמשתמש לא יוכל לשנות את השפה שהגדרתם יש להגדיר InsertLettersTypeChangeNo.
במקרה כזה במידה והמשתמש מנסה לשנות שפה המערכת תשמיע M4186 "שינוי שפת הקלדה חסום בכתיבה זו"

---

הערך החמישה עשר (הקשה)
בקשת אישור על ההקשה
כברירת מחדל, לאחר כל הקשה המערכת מבקשת מהמשתמש אישור על ההקשה M1353 "לאישור הקישו אחת, להקשה מחודשת הקישו שתיים"
בערך זה ניתן להגדיר שהמערכת לא תבקש אישור על ההקשה אלא מיד תמשיך עם המשתמש כאילו הוא אישר את ההקשה.
ההגדרה היא no

---

כללי (הקשה)

השמעת קובץ בהתאם לנתון שהתקבל
ניתן להגדיר שבמידה והתקבל נתון מסוים המערכת תשמיע למשתמש קובץ מסוים ובסיום ההשמעה המשתמש יעבור להקשה מחודשת של הנתון
הגדרה לדוגמה

api_002_key_2_say=100

בדוגמה, במידה ובקובץ 002 הנתון שהתקבל הוא 2 אז המערכת תשמיע את קובץ 100.wav שנמצא בשלוחה
חשוב! הקובץ חייב להיות בפורמט wav (ולא tts) ובנוסף בעת שמיעת הקובץ לא ניתן להקיש על אף מקש

---

הגדרות עבור הקלטות - record

---

הערך הרביעי (הקלטה)
בערך זה ניתן להגדיר היכן תישמר ההקלטה במערכת
ברירת מחדל זה נשמר בתיקייה שמוגדרת ב-api_dir
ניתן להגדיר מיקום שונה
לדוגמה
/8 (סלש שמונה)
במקרה כזה ההקלטה תישמר בשלוחה 8

הערה: חובה לשים / בהתחלה. אסור לשים / בסוף

---

הערך החמישי (הקלטה)
בערך זה ניתן להגדיר את שם הקובץ שיישמר
כברירת מחדל שם הקובץ ממוספר בצורה אוטומטית כמספר הגבוה ביותר בשלוחה
למשל, אם הקובץ הכי גבוה בשלוחה היה 100 אז הקובץ החדש יהיה 101
במידה ורוצים להגדיר שם שונה לקובץ ניתן להגדיר בערך הזה את שם הקובץ הרצוי
בדוגמה 007 למעלה שם הקובץ יהיה file_name.wav
(ראה בנוסף "הערך השמיני" להלן)

---

הערך השישי (הקלטה)
סיום הקלטה
כברירת מחדל בסיום ההקלטה בהקשה על # המשתמש שומע תפריט M3345 "לשמיעת ההודעה הקישו אחת לאישור הקישו שתיים או סולמית להקלטה מחדש הקישו שלוש להמשך הקלטה הקישו ארבע"
ניתן להגדיר שבהקשה על # ההקלטה תאושר מידית (ללא תפריט) ההגדרה היא no

---

הערך השביעי (הקלטה)
שמירה בניתוק שיחה
כברירת מחדל, במידה ומשתמש ניתק את השיחה במהלך ההקלטה, ההקלטה לא נשמרת בשלוחה הרצויה.
כדי לשמור את ההקלטה יש להגדיר yes

---

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

---

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

---

הערך העשירי (הקלטה)
בערך זה ניתן להגדיר את האורך המקסימלי של ההקלטה (בשניות)
ברירת המחדל היא ללא הגבלה. ניתן להגדיר כמות שניות שונה.

---

כללי (הקלטה)

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

api_record_beep=no

שמירת הקלטות
כל ההקלטות (גם ההקלטות שלא אושרו) נשמרות בסל המחזור בתיקיית ApiRecord

---

הגדרות עבור זיהוי דיבור - voice

---

• הגדרות גלובליות עבור מנוע זיהוי דיבור

---

הערך הרביעי (דיבור)
בערך זה ניתן להגדיר באיזה שפה המערכת תזהה את הדיבור של המשתמש
ברירת המחדל היא עברית (או מה שהוגדר בערך lang בשלוחה)
בערך זה ניתן להגדיר שפה שונה. לרשימת השפות המלאות

---

הערך החמישי (דיבור)
ברירת המחדל היא שהמשתמש יכול לדבר או להקיש
במידה והמשתמש דיבר - המערכת מתמללת את הדיבור לטקסט
במידה והמשתמש הקיש - המערכת קולטת את ההקשות ושולחת את זה לשרת בתוספת Digits
לדוגמה, אם משתמש הקיש 1234 אז מה שיישלח לשרת תחת הערך של השאלה זה Digits-1234
בערך זה ניתן לחסום את ההקשות של המשתמש
ההגדרה היא no
(ראה עוד ערכים 6 ו-7 להלן)

---

הערך השישי (דיבור)
בערך זה ניתן להגדיר את כמות הספרות המקסימלית שמשתמש יכול להקיש
ברירת המחדל היא ללא הגבלה (ניתן לראות בדוגמה 006 שיש הגבלה ל-30 ספרות)

---

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

---

הערך השמיני (דיבור)
במידה והגדרתם בערך השביעי שהמערכת תפעיל את מנוע זיהוי דיבור של הקלטות, תוכלו להגדיר כאן זמן מקסימלי של שקט לסיום ההקלטה. (בדוגמה בקובץ 008 מוגדר 6 שניות)

---

הערך התשיעי (דיבור)
במידה והגדרתם בערך השביעי שהמערכת תפעיל את מנוע זיהוי דיבור של הקלטות, תוכלו להגדיר כאן את הזמן המקסימלי להקלטה (בדוגמה בקובץ 008 מוגדר מקסימום 9 שניות)

---

כללי (דיבור)

עזרה בהבנת הדיבור
ניתן "לעזור" למערכת לנסות להבין את דיבור המשתמש
לצורך כך יש ליצור קובץ ini ששמו כשם קובץ השאלה
לדוגמה, עבור שאלה 000 יש ליצור קובץ בשם 000.ini
בקובץ עצמו יש לרשום את מה שהמשתמש ידבר
(לדוגמה, אם המשתמש אמור לומר "ירושלים" אז יש לרשום בקובץ "ירושלים")
יש לרשום כל דיבור ודיבור בשורה חדשה

לתשומת ליבכם: לפני השליחה לשרת הקבצים של המערכת הם 000.wav או 000.tts ואח"כ 001.wav או 001.tts וכו' ולכן הקבצים הנלווים לעזרה גם יהיו בשמות 000.ini ואח"כ 001.ini

לאחר השליחה במידה ועניתם read אז הקובץ שהמערכת מחפש זה כשם הפרמטר שהוגדר כלומר אם עניתם שישמור את התשובה של הלקוח בפרמטר בשם AAA אז הקובץ לעזרה באותה השלוחה צריך להיות בשם AAA.ini

מה לעשות לאחר המרת הדיבור
אם מעוניינים שלא יושמע ללקוח את ההקראה של הטקסט שהתקבל לצורך שיקוף יש להגדיר

api_say_tts=no

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

api_voice_ask_ok=yes

שמירת הקלטה
אם רוצים שהקובץ של ההקלטה יישאר אצלכם במערכת יש להגדיר

api_save_file=yes

הקובץ נשמר זמנית בסל המחזור בתוך תיקיה ApiVoice

---

כללי

---

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

---

ניתן להחליף בשליחת ערכים כל רווח ב"+" (יש שרתים שרווח עושה בעיות)
יש להגדיר:

api_add_replace_space=yes

---

במידה ויש טקסט שהתקבל בעברית, ולצורך שליחה רציפה של המילים כחלק משורת הכתובת
אנו ממירים את הטקסט ל URIENCODE (בדרך כלל המערכות web שלכם כבר ימירו את זה אוטומטית לעברית תקנית)

[eliyahu]

תשובת שרת

---

לאחר שליחת הבקשה לשרת, המערכת ממתינה לתשובת השרת

מוזיקה בהמתנה בזמן ההמתנה לתגובה מהשרת

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

api_wait_answer_music_on_hold=yes

ברירת מחדל, משמיע את המוזיקה בהמתנה המוגדרת במערכת, כמו ניתוב וכו, אם רוצים להגדיר מוזיקה בהמתנה מיוחדת לשלוחת הapi יש להגדיר:

api_wait_answer_music_on_hold_different=שם המוזיקה בהמתנה שלכם

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

api_wait_answer_music_on_hold_continue_all_sends=yes

---

מענה מהשרת

במידה ואין מענה או שהמענה שהתקבל לא תקין המערכת תשמיע M1607 "אין מענה משרת API" והמשתמש ייצא מהשלוחה

שימו לב! את תשובת השרת יש לשלוח בטקסט פשוט לפי ההוראות שיובאו להלן (ללא תגי html או ב-JSON וכדומה) - במידה וחלק מהטקסט יהיה לא תקין יושמע אין מענה משרת API

---

את סוגי התשובות שניתן לענות מהשרת ניתן לחלק ל-2

1. השרת מחזיר תשובה פשוטה (כדוגמת "OK" "ERROR" וכדומה), המערכת בודקת אם יש הגדרות במערכת שתואמות לתשובה שהתקבלה ופועלת בהתאם.
   באפשרות זו את כל ההגדרות יש להגדיר במערכת עצמה
2. השרת מחזיר בתשובה את ההגדרות למערכת מה לבצע עם השיחה של המשתמש
   באפשרות זו את כל ההגדרות יש להחזיר מהשרת

את האבחנה של סוג התשובה המערכת מבצעת לבד.

במידה ובחרתם באפשרות הראשונה המערכת מבצעת את השלבים הבאים:

בשלב הראשון המערכת בודקת אם יש קובץ שמע בשלוחה שהשם שלו תואם לתשובה שהתקבלה מהשרת (למשל, השרת החזיר תשובה OK ויש קובץ בשלוחה בשם OK.wav)
במידה והקובץ קיים המערכת משמיעה אותו

ניתן להגדיר שהמערכת תקריא את תשובת השרת כמות שהיא במנוע הקראת טקסט
ההגדרה היא

say_api_answer=yes

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

בשלב השני (לאחר השמעת הקובץ, או אם לא קיים קובץ) המערכת בודקת אם יש התייחסות בהגדרות השלוחה לתשובה שהתקבלה
למשל, אם התשובה שהשרת החזיר היא OK אז ההגדרה שצריכה להיות בשלוחה היא

api_answer_OK=פעולות לביצוע

דוגמה נוספת, במידה והתשובה שהשרת החזיר היא Incorrect-ID אז ההגדרה שצריכה להית בשלוחה היא

api_answer_Incorrect-ID=פעולות לביצוע

---

פעולות לביצוע

---

הפעולות הניתנות לביצוע הן

• העברת המשתמש לשלוחה אחרת - go_to_folder
• העברת המשתמש לשלוחת השמעת קבצים והשמעת קובץ ספציפי מנקודת עצירה מסוימת - go_to_folder_and_play
• מעבר לסליקת אשראי - credit_card
• ניתוב שיחה למערכת אחרת בימות המשיח - routing_yemot
• ניתוב שיחה למספר ישראלי - routing
• השמעת מוזיקה למשתמש - music_on_hold
• השמעת הודעות ונתונים למשתמש בהתאמה אישית - id_list_message
• מקום לרשום הערות בשבילכם, המערכת לא תתיחס למה שכתבתם - noop
• קבלת נתונים נוספים מהמשתמש ושליחתם לשרת - read

דוגמה להגדרות במערכת

api_answer_${response}=go_to_folder=ערכים להגדרה
api_answer_${response}=go_to_folder_and_play=ערכים להגדרה
api_answer_${response}=credit_card=ערכים להגדרה
api_answer_${response}=routing_yemot=ערכים להגדרה
api_answer_${response}=routing=ערכים להגדרה
api_answer_${response}=music_on_hold=ערכים להגדרה
api_answer_${response}=id_list_message=ערכים להגדרה
api_answer_${response}=noop=ערכים להגדרה
api_answer_${response}=read=ערכים להגדרה

דוגמה לתגובה מהשרת המכילה הגדרות

go_to_folder=ערכים להגדרה
go_to_folder_and_play=ערכים להגדרה
credit_card=ערכים להגדרה
routing_yemot=ערכים להגדרה
routing=ערכים להגדרה
music_on_hold=ערכים להגדרה
id_list_message=ערכים להגדרה
noop=הערות שהמערכת לא מתיחס אליהם בכלל
read=ערכים להגדרה

---

ערכים להגדרה

---

העברת המשתמש לשלוחה אחרת - go_to_folder

הערך היחיד הניתן להגדרה הוא - השלוחה אליה יעבור המשתמש
לדוגמה

go_to_folder=3
go_to_folder=/3

בדוגמה הראשונה המשתמש יעבור לשלוחה 3 שתחת השלוחה הנוכחית, בדוגמה השניה המשתמש יעבור לשלוחה 3 שתחת השלוחה הראשית

---

העברת המשתמש לשלוחת השמעת קבצים והשמעת קובץ ספציפי מנקודת עצירה מסוימת - go_to_folder_and_play

הערכים הניתנים להגדרה (השמעת קובץ מנקודת עצירה)

• השלוחה אליה המשתמש יועבר.
  לדוגמה /1/5 למעבר לשלוחה /1/5
• שם הקובץ להשמעה.
  ניתן להגדיר ב-2 אפשרויות.
  האפשרות הראשונה היא לציין רק את שם הקובץ (לדוגמה 005) ואז בכזה מקרה המערכת תשמיע את הקובץ מהשלוחה אליה המשתמש מועבר.
  האפשרות השניה היא לציין נתיב מלא של הקובץ להשמעה. (לדוגמה /1/4/006) ואז בכזה מקרה המערכת תשמיע את הקובץ מהנתיב שצוין
• נקודת עצירה בקובץ - באלפיות שניה (לדוגמה 1001)

הגדרות לדוגמה

go_to_folder_and_play=/1/5,005,1001
go_to_folder_and_play=/1/5,1/4/006,1001

---

מעבר לסליקת אשראי - credit_card

מומלץ לעבור על ההגדרות המופיעות בשרשור שלמודול credit_card

---

דוגמה (ראה בהרחבה להלן)

credit_card=pelecard,100,999,3,2,DebitPaymntsType

---

הערכים הניתנים להגדרה (סליקת אשראי)

שימו לב! ניתן להגדיר את הערכים גם בקובץ הגדרות השלוחה כפי שמופיע בשרשור של מודול סליקת אשראי.
האפשרות שמובאת להלן מיועדת למקרים בהם תרצו שהמערכת תתנהג בצורה שונה אצל כל משתמש (סכום לתשלום, כמות תשלומים וכדומה)

---

הערך הראשון (סליקת אשראי)
credit_card_type
סוג סליקה

בערך זה יש לציין את שם החברה לסליקה (לדוגמה tranzila עבור טרנזילה או credit_guard עבור קרדיט גארד וכן הלאה)

---

הערך השני (סליקת אשראי)
billing_sum
סכום לחיוב

ברירת מחדל - המשתמש בוחר את הסכום לחיוב
ניתן להגדיר סכום קבוע לתשלום (בדוגמה למעלה מופיע סכום לחיוב ע"ס 100)

---

הערך השלישי (סליקת אשראי)
credit_card_register_number
מספר חנות/פרויקט

בערך זה יש לרשום את מספר החנות/פרויקט (ישנם חברות שערך זה הינו חובה)
בדוגמה למעלה מופיע שמספר החנות הוא 999

---

הערך הרביעי (סליקת אשראי)
credit_card_max_tashloumim
כמות תשלומים

בערך זה יש להגדיר את כמות התשלומים הרצויה
ברירת המחדל היא שהמשתמש יכול לבחור את כמות התשלומים (עד 36 תשלומים)
ניתן להגדיר כאן כמות תשלומים שונה (בדוגמה למעלה מופיע 3 תשלומים)

---

הערך החמישי (סליקת אשראי)
credit_card_currency
סוג מטבע

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

---

הערך השישי (סליקת אשראי)
credit_card_pelecard_type
סוג סליקה פלאקארד

ערך זה מיועד רק לסולקים דרך חברת פלאקארד,
במידה ומוגדר יותר מתשלום אחד חובה להגדיר באיזה סוג רוצים לקבל תשלומים או קרדיט
האפשרויות הם:
DebitRegularType - תשלום אחד
DebitCreditType - תשלום בקרדיט
DebitPaymntsType - תשלום בתשלומים רגילים

---

הערך השביעי (סליקת אשראי)
credit_card_user_name
שם משתמש בחברת הסליקה

---

הערך השמיני (סליקת אשראי)
credit_card_terminal_number
מספר טרמינל

---

הערך התשיעי (סליקת אשראי)
credit_card_password
סיסמה בחברת הסליקה

---

הערך העשירי (סליקת אשראי)
האם לשדר בחזרה את התשובה המלאה שמגיעה מחברת הסליקה
ברירת מחדל: בכל חברות הסליקה נשלח לאחר הסליקה בתשובה CreditCard_CODE כלומר מה סטטוס העיסקה
ברירת מחדל בסליקת פלאקארד: לאחר הסליקה נשלח התשובה בתוספת CreditCard_All עם הערכים החשובים

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

לאחר הסליקה בהצלחה
ישלח אליכם שוב הAPI עם כל הפרטים שהיו לפני כן
עם התוספת של המחרוזות הבאה

&CreditCard_CODE=קוד התשובה

וכן את התוספת הבאה בהתאם להגדרות בערך העשירי

&CreditCard_All=הערכים החשובים מהתשובה המלאה

הערכים החשובים מהתשובה המלאה

קארדקום cardcom
1)סטטוס אישור
2) מספר אישור
3) סכום העיסקה
4) ארבע ספרות אחרונות של הכרטיס המחוייב
הערכים יגיעו עם נקודה בין ערך לערך

טרנזילה tranzila

1. טוקן Token
2. מספר אישור ConfirmationCode
3. 4 ספרות אחרונות ccno
4. פג תוקף של הכרטיס expdate

ריווחית - icredit
משודרים 5 ערכים בהפרדה של # בין ערך לערך

1. סטטוס עיסקה
2. CustomerTransactionId
   3)Token
   4)ReceiptLink
   5)מספר אישור עיסקה של ריווחית

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

0004580123412341234.1.1217.00000500.1.01.1.0000000.00000000.00000000.00

• מספר כרטיס
• מספר חברה סולקת 1 - ישראכרט 2 - ויזה 3 - דיינרס 4 - אמקס 6 - לאומי קארד
• תוקף
• סכום באגורות
• קוד חברת אשראי
• סוג עיסקה
• סוג מטבע
• מספר אישור
• סכום תשלום ראשון
• סכום קבוע
• מס' תשלומים קבועים (שימו לב שמדובר על יתרת התשלומים אחרי התשלום הראשון, ולכן אם מדובר על תשלום אחד תקבלו תשובה של 00, ואם הגדרתם 5 תשלומים אז תקבלו תשובה של 04)

כמובן שהשרת שלכם יוכל לענות בכל אחד מהתשובות האפשרויות וכך תוכלו להודיע למשתמש שהעסקה בוצעה בהצלחה וכו'

---

הערך האחד עשר (סליקת אשראי)
credit_card_enter_phone
שידור מספר טלפון

הערך הניתן להגדרה הוא EnterPhone
הסבר:
ברירת מחדל בנדרים פלוס - מספר הטלפון שנשלח בערך Phone הינו מספר הטלפון ממנו המשתמש התקשר
מכיוון שבנדרים פלוס ישנם חשבונות טלפון רבים, לכן הגדרנו שיהיה ניתן לתת תפריט למשתמש שיבחר איזה טלפון לשדר
במקרה שהמשתמש בוחר את הזיהוי הטלפוני אז המערכת תשדר בנפרד את הטלפון שממנו המשתמש חייג,
הערך ישודר בתוך הערך Avour ושם יופיע

OriginalPhone-0771234567

במידה והפעלתם את ההגדרה המערכת תשאל:
M1589 "לשידור מספר הטלפון ממנו התקשרתם הקישו 1 וסולמית
לשידור מספר טלפון אחר הקישו את מספר הטלפון וסולמית לסיום"

הערך הזה בינתיים פעיל רק בנדרים פלוס, במידת הצורך בקשו משרות הלקוחות שנוסיף שאלה זו בחברות סליקה נוספות

---

הערך השנים עשר (סליקת אשראי)
credit_card_name_stt
הקלטת שם ותמלול

במידה ותכתבו בערך השנים עשר את המילה
NameStt
גורם לכך שהמערכת תשדר
credit_card_name_stt=yes
שמשמעותו להקליט את השם ולשלוח אותו לחברת הסליקה בתור שם בעל הכרטיס
(עיין בהרחבה במודל סליקה)

---

הערך השלושה עשר (סליקת אשראי)
credit_card_name_stt_record_no_ask
דילוג על תפריט אישור הקלטה של השם

במידה ותכתבו בערך השלשה עשר את המילה
NoAsk
גורם לכל שהמערכת תשדר
credit_card_name_stt_record_no_ask=yes
שמשמעותו שבמידה ויש תוצאה של השם שנקלט, המערכת לא תבקש אישור על השם מהמשתמש אלא מיד תתקדם הלאה כאילו המשתמש שמע ואישר

---

הערך הארבעה עשר (סליקת אשראי)
credit_card_create_token
יצירת טוקן

במידה ותכתבו בערך הארבע עשר את המילה
CreateToken
גורם לכל שהמערכת תשדר
credit_card_create_token=yes
שמשמעותו שלאחר סליקה בהצלחה המערכת תבקש מחברת האשראי לייצר טוקן
במידה ונוצר טוקן הוא יצטרף לערכים שחוזרים אליכם בAPI
הערה 16/01/2020: נכון להיום ניתן לבקש לייצר טוקן ב Tranzila,
חברת cardcom מייצרת טוקן גם ללא בקשה
כל שאר החברות עדיין לא פותח נושא הטוקן

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

---

הערך החמישה עשר (סליקת אשראי)

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

CreditCard_CODE=GoBack&CreditCard_All=GoBack

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

---

ניתוב שיחה למערכת אחרת בימות המשיח - routing_yemot

הערך היחיד הניתן להגדרה הוא המספר לניתוב
לדוגמה

routing_yemot=0773137770

במקרה כזה המערכת תנתב את השיחה למספר 0773137770

---

ניתוב שיחה למספר ישראלי - routing

מומלץ לעבור על ההגדרות המופיעות בשרשור של מודול routing

---

הערכים הניתנים להגדרה (ניתוב שיחה)

הערכים המלאים שניתן לשדר

routing=routing_to_phone,routing_start,routing_tor,routing_multiple,routing_multiple_numbers,routing_your_id,routing_record,send_sms_befor_routing,routing_end_time,routing_end_goto,music_on_hold,routing_answer_play,routing_answer_tfr,routing_answer_tfr_hangup_goto,routing_email_address,routing_email_name

הסבר על כל ערך ומה אפשר לשדר בו ניתן להסתכל במודול routing עצמו

---

הערך הראשון (ניתוב שיחה)
routing_to_phone
רשימת מספרים לחיוג

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

שימו לב שהמערכת ממספרת את המספרים לחיוג לפי הסדר שעניתם בתשובה
לדוגמה אם עניתם

routing=0581234567.0533137770

אז המערכת ממספרת את המספרים לחיוג כך

routing1=0581234567
routing2=0533137770

(רלוונטי לערכים הבאים)

---

הערך השני (ניתוב שיחה)
routing_start
מספר בודד לחיוג

לדוגמה

routing=0581234567.0501234567.0533137770,3

המערכת תחייג רק למספר 0533137770

---

הערך השלישי (ניתוב שיחה)
routing_tor

לא פעיל (יש להשאיר ערך זה ריק)

---

הערך הרביעי (ניתוב שיחה)
routing_multiple

על מנת שהמערכת תחייג למספרים שברשימה בבת אחת והשיחה תנותב למי שענה ראשון לשיחה יש להגדיר בערך זה yes

---

הערך החמישי (ניתוב שיחה)
routing_multiple_numbers
מספרים לחיוג

במידה והגדרתם בערך הרביעי yes יש להגדיר בערך זה את הערכים של המספרים לחיוג כאשר בין ערך לערך יש להפריד עם נקודה
לדוגמה

routing=0501234567.0521234567.0541234567,,,yes,1.2

במקרה כזה המערכת תחייג למספר הראשון והשני (0501234567 0521234567)

---

הערך השישי (ניתוב שיחה)
routing_your_id
זיהוי שיחה

בערך זה יש להגדיר את זיהוי השיחה כפי שתופיע על הצג אצל מי שמקבל את השיחה
האפשרויות להגדרה כאן הן כמו המופיע במודול routing

---

הערך השביעי (ניתוב שיחה)
routing_record

האם להקליט את השיחה

---

הערך השמיני
send_sms_befor_routing

לא פעיל (יש להשאיר ערך זה ריק)

---

הערך התשיעי (ניתוב שיחה)
routing_end_time
הגבלת זמן המתנה (בשניות)

---

הערך העשירי (ניתוב שיחה)
routing_end_goto
מעבר בסיום

---

הערך האחד עשר (ניתוב שיחה)
music_on_hold
מוזיקה בהמתנה להשמעה

---

הערך השנים עשר (ניתוב שיחה)
routing_answer_play
הודעה בצד העונה לפני התחלת השיחה

---

הערך השלושה עשר (ניתוב שיחה)
routing_answer_tfr
תפריט האם לקבל את השיחה או לדחותה

---

הערך הארבעה עשר (ניתוב שיחה)
routing_answer_tfr_hangup_goto

במידה והגדרתם בערך ה-13 yes. בערך זה ניתן להגדיר מה לעשות עם המשתמש במידה והנציג דחה את השיחה
ברירת המחדל היא שהמשתמש חוזר לשלוחה אחת למה
בערך זה ניתן להגדיר שלוחה אחרת להעברה

---

הערך החמישה עשר (ניתוב שיחה)
routing_email_address
מייל לשליחת הדוחות וההקלטות

---

הערך השישה עשר (ניתוב שיחה)
routing_email_name
השם שיופיע במייל

---

מוזיקה בהמתנה - music_on_hold

מומלץ לעבור על ההגדרות המופיעות בשרשור שלמוזיקה בהמתנה

הערכים הניתנים להגדרה

• המוזיקה להשמעה - חובה
• זמן (בשניות) לסיום המוזיקה - רשות

בין הערכים הניתנים להגדרה יש להפריד עם פסיק ( , )
לדוגמה

music_on_hold=המוזיקה שלכם,שניות

שימו לב! בכל מצב המשתמש יכול להקיש על * ולסיים את ההשמעה.

---

השמעת הודעות ונתונים למשתמש בהתאמה אישית - id_list_message

באפשרות זו ניתן להשמיע למשתמש הודעה אחת, או מספר הודעות ברצף.
תחילה יש להגדיר

id_list_message=

אחרי ה= יש לציין את "סוג ההודעה" (ראה להלן בטבלה)
אחרי סוג ההודעה יש להפריד עם קו מפריד ( - )
לאחר הקו המפריד יש לרשום את ההודעה להשמעה.
להשמעת רצף הודעות יש להפריד בין הודעה להודעה עם נקודה ( . )
ראה דוגמאות להלן

סוגי ההשמעות הניתנות להגדרה:

סוג	ערך להגדרה	הסבר
File	f	השמעת קובץ מתוך המערכת או מהמאגר הגלובלי
Digits	d	השמעת ספרות (לדוגמה 111 המערכת תשמיע "אחת אחת אחת")
Number	n	השמעת מספר (לדוגמה 111 המערכת תשמיע "מאה ואחת עשרה")
Alpha	a	השמעת אותיות (לדוגמה abc המערכת תשמיע "איי בי סי")
Text	t	הקראת טקסט
Speech	s	הקראת טקסט מתוך קובץ במערכת
zmanim	z	השמעה שעה לפי משתנה רצוי
system message	m	הודעת מערכת
go_to_folder	g	מעבר לשלוחה אחרת (לא ניתן לשרשר הודעות נוספות לאחר פקודה זו)
noop	noop	כלום - מיועד להערות לדוגמא להסביר מה המשמעות של ההודעת מערכת שתשמיעו לאחר מכן, שימו לב לא להשתמש ב"."
date	date	השמעת תאריך לועזי21/12/2022
dateH	dateH	השמעת תאריך עברי 21/12/2022 - כ"ז כיסלו תשפ"ג

---

File
בערך זה יש לציין הקובץ להשמעה
האפשרויות הן

• השמעת קובץ מתוך השלוחה הנוכחית
• השמעת קובץ מתיקייה אחרת במערכת
• השמעת קובץ מתוך המאגר הגלובלי
• השמעת קובץ מתוך השלוחה הנוכחית, ואם לא קיים - השמעה מתוך המאגר הכללי

השמעת קובץ מתוך השלוחה הנוכחית
לדוגמה

f-error

בדוגמה, המערכת תשמיע את הקובץ error.wav שנמצא בשלוחה הנוכחית.

השמעת קובץ מתיקייה אחרת במערכת
כדי להשמיע קובץ מתיקייה אחת במערכת, יש לציין את נתיב הקובץ המלא
לדוגמה

f-/8/error

בדוגמה, המערכת תשמיע את הקובץ error.wav שנמצא בשלוחה 8.

השמעת קובץ מתוך מאגר גלובלי
השירות כרוך בתשלום
אפשרות זו מיועדת לבעלי מערכות שונות המעוניינים להשמיע הודעה זהה בכל המערכות
ניתן להקים ספריה במאגר הגלובלי בה יהיו ההודעות להשמעה
להקת המאגר יש לפנות למייל special@yemot.co.il עם הנושא "הודעות להוספה למאגר גלובלי במודול API". בצירוף ההקלטות והשמות שלהם כפי שיישמרו במאגר ושההקלטות יהיו מומרות לאיכות של המערכת.
שימו לב, המאגר הוא ציבורי לכל הלקוחות.

לאחר שההקלטות צורפו למאגר הכללי יש לציין את הנתיב להשמעה כך

f-YM_LOCAL/library/file

בדוגמה, המערכת תשמיע את קובץ file שנמצא במאגר הגלובלי בספריית library.

השמעת קובץ מתוך התיקייה הנוכחית, ואם לא קיים - השמעה מהמאגר הכללי
יש להגדיר בהגדרות השלוחה

global_folder_check=yes
global_folder_share=/library

(כמובן שבמקום library יש לציין את שם הספרייה הרצויה)

בקובץ להשמעה יש לציין את שם הקובץ ללא קידומת
לדוגמה

f-file

בדוגמה, המערכת תשמיע את קובץ file.wav שנמצא בשלוחה הנוכחית, ואם הקובץ לא קיים המערכת תשמיע את הקובץ file.wav שנמצא במאגר הגלובלי בספרייה library

---

Digits
בערך זה יש לציין את הספרות להשמעה
לדוגמה

d-123

המערכת תשמיע "אחת שתיים שלוש"

---

Number
בערך זה יש לציין את המספר להשמעה
לדוגמה

n-123

המערכת תשמיע "מאה עשרים ושלוש"

---

Alpha
בערך זה יש לציין את האותיות להשמעה
לדוגמה

a-abc

המערכת תשמיע "איי בי סי"

---

Text
בערך זה יש לרשום את הטקסט להקראה
לדוגמה

t-שלום עולם

המערכת תשמיע "שלום עולם"
חשוב! לא להכניס בטקסט את התווים נקודה ( . ) וקו מפריד ( - ).

---

Speech
בערך זה יש לציין את שם הקובץ להקראה
לדוגמה

s-123

המערכת תקריא את קובץ 123.tts שנמצא בשלוחה הנוכחית

s-/8/123

המערכת תקריא את קובץ 123.tts שנמצא בשלוחה 8

---

zmanim
השמעת שעה לפי משתנה רצוי (למשל, לפי שקיעה או זריחה)
בערך זה יש לרשום את הזמן הרצוי ניתן לקבוע את הזמן לפי 4 משתנים שונים.
ההפרדה בין המשתנים השונים היא באמצעות פסיק ( , )
לדוגמה

z-var1,var2,var3,var4

• במשתנה הראשון יש לרשום את סוג הזמן הרצוי. למידע אודות סוגי הזמן הקיימים במערכת לחצו כאן.
• במשתנה השני יש לרשום את אזור הזמן הרצוי. למידע אודות אזורי הזמן הקיימים במערכת לחצו כאן.
• במשתנה השלישי ניתן לבחור האם להפחית מהזמן שצוין או להוסיף על הזמן.
  כדי להוסיף זמן יש לרשום +
  כדי להפחית זמן יש לרשום -
  כדי לא לשנות את הזמן יש להשאיר ריק.
• במידה ובחרתם במשתנה השלישי להפחית או להוסיף זמן, יש לציין במשתנה הרביעי את כמות הזמן הרצויה כדלהלן:
  תחילה יש לציין את פונקציית הזמן. האפשרויות הן
  Y - שנה
  M - חודש
  D - יום
  H - שעה
  m - דקה
  S - שניה
  s - אלפית שניה
  לאחר מכן יש לרשום במספר את הכמות הרצויה.
  למשל, עבור 20 דקות יש להגדיר m20 עבור 3 שעות יש לרשום H3. עבור יום אחד יש לרשום D1.

---

system message
בערך זה יש לרשום את מספר ההודעה להשמעה
לדוגמה

m-1001

ישמיע את ההודעה M1001

---

go_to_folder

בעיקרון הגדרה זו קיימת כבר כאפשרות בפני עצמה

בערך זה יש לרשום את השלוחה להעברה
לדוגמה

g-1

המשתמש יעבור לשלוחה 1 שמתחת לשלוחה הנוכחית

g-/1

המשתמש יעבור לשלוחה 1 שתחת השלוחה הראשית

---

שליחת webhook במקרה של שגיאה בהשמעת קובץ
כרגע פעיל רק באפשרות של File (f)
ניתן להגדיר שבמידה והשרת שלכם החזיר בתגובה השמעת הודעה וההשמעה נכשלה (קובץ לא קיים) המערכת תשלח webhook אליכם עם פרטי השגיאה
לצורך כך יש להגדיר בהגדרות השלוחה את הURL אליו יישלח הhook

api_send_webhook_error_link=https://exmple.com/error.aspx

כמובן שבמקום https://exmple.com/error.aspx יש להכניס את כתובת השרת שלכם

לפנייה יצורפו הפרטים הרגילים (ApiCallId ApiDID וכדומה) והפרטים שנאספו עד עכשיו בתוספת הפרטים הבאים

{
"Action":"id list message type 'f'",   /// פעולה של השמעת נתונים והודעות אישיות מסוג קובץ
"FilePath":"/000",   /// נתיב קובץ 000 (כמובן שזה משתנה בהתאם לנתיב)
"Status":"Error",   /// סטטוס נכשל
"Message":"file audio not found"   /// הודעת שגיאה: הקובץ לא קיים
}

---

שרשור פעולות

בפעולות מסוג music_on_hold id_list_message ניתן לשרשר פעולה נוספת (מעבר לסליקת אשראי וכדומה)

כדי לשרשר פעולות יש לפעול לפי ההוראות הבאות

במידה ואת הפעולות לביצוע הגדרתם במערכת (למשל api_answer_OK=) אז יש לשרשר את הפעולות כך (דוגמה)

api_answer_OK=id_list_message=t-הנכם מועברים למערכת אחרת
api_answer_OK_1=routing_yemot=0773137770

בדוגמה, במידה והשרת ענה OK המערכת תשמיע למשתמש "הנכם מועברים למערכת אחרת" ולאחר מכן המשתמש ינותב למספר 077-3137770

כלומר, כל פעולה לביצוע נרשמת בשורה חדשה בתוספת מספר
שימו לב שחשוב לשמור על סדר רציף החל מהספרה 1.

במידה ואת הפעולות לביצוע אתם עונים מהשרת שלכם, אז יש לשרשר את הפעולות כך (דוגמה)

id_list_message=t-הנכם מועברים למערכת אחרת&routing_yemot=0773137770

[eliyahu]

read - קבלת נתונים נוספים מהמשתמש ושליחתם לשרת

---

הסבר

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

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

---

הגדרות עבור תשובת שרת

ההגדרות עבור פעולה מסוג read מחולקות ל-2 חלקים

• בחלק הראשון יש להגדיר את ההודעה שתושמע למשתמש
  (לדוגמה - "אנא הקישו את 4 הספרות האחרונות של אמצעי התשלום")

• בחלק השני יש להגדיר את סוג הנתון שנלקח מהמשתמש (הקשה, הקלטה ועוד)

---

בין הערכים של החלק הראשון והחלק השני יש להפריד עם =
לדוגמה
read=חלק ראשון=חלק שני

---

חלק ראשון - ההודעה שתושמע למשתמש

הערכים להגדרה באפשרות זו זהים לערכים הניתנים להגדרה בפעולה מסוג id_list_message

דוגמאות

read=f-YM_LOCAL/library/file.f-Methods_of_Payment=חלק שני
read=t-אנא הקליטו את שמכם המלא בקול ברור, לסיום הקישו סולמית=חלק שני
read=s-abc=חלק שני
read=s-abc.dateH-01/01/2023=חלק שני
read=date-01/01/2023=חלק שני

• בדוגמה הראשונה, המערכת תשמיע למשתמש קובץ מהמאגר הגלובלי (ספריית library קובץ file) ולאחר מכן תשמיע למשתמש קובץ נוסף מתוך השלוחה (Methods_of_Payment.wav)
• בדוגמה השנייה, המערכת תשמיע למשתמש "אנא הקליטו את שמכם המלא בקול ברור, לסיום הקישו סולמית"
• בדוגמה השלישית, המערכת תקריא למשתמש את מה שכתוב בקובץ abc.tts שנמצא בשלוחה
• בדוגמה הרביעית, המערכת תקריא למשתמש את מה שכתוב בקובץ abc.tts שנמצא בשלוחה, ולאחר מכן המערכת תשמיע את התאריך העברי של יום 01/01/2023
• בדוגמה החמישית, המערכת תשמיע את התאריך הלועזי של יום 01/01/2023

---

חלק שני - הנתון שיילקח מהמשתמש

הערכים להגדרה באפשרות זו זהים לערכים הניתנים להגדרה עבור "קבלת נתונים מהמשתמש" (ראה לעיל "שליחת נתונים לשרת")

דוגמאות

read=f-YM_LOCAL/library/file.f-Methods_of_Payment=MOP,,4,4,Digits,yes
read=t-אנא הקליטו את שמכם המלא בקול ברור, לסיום הקישו סולמית=NAME,,voice
read=s-abc=Recordings,,record

בדוגמה הראשונה, הנתון שיילקח מהמשתמש הוא הקשות
בדוגמה השנייה, הנתון שיילקח מהמשתמש הוא דיבור
בדוגמה השלישית, הנתון שיילקח מהמשתמש הוא הקלטה

---

כללי

הנתונים הנשלחים לשרת

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

---

read_answer

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

read_answer_DFGH_1234=פעולה לביצוע

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

---

שרשור פעולות

בפעולה מסוג read לא ניתן לשרשר פעולות לביצוע.
לאחר ביצוע פעולה אחת המערכת שולחת מיד את הנתון לשרת ולא מבצעת את הפעולה השניה

לדוגמה

read=f-000=foo,yes,8,4,7,Number,yes,no,*/&read=f-001=bar,yes,8,4,7,Number,yes,no,*/&

המערכת תקבל ותשלח רק את הפרמטר foo ולא את הפרמטר bar

---

[eliyahu]

לוגים

---

שמירת לוגים

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

• רמה אחת - ביטול השמירה עבור כלל הפעולות בשלוחה
• רמה שניה - ביטול השמירה עבור פעולה ספציפית
   

על מנת לבטל את השמירה עבור כלל הפעולות בשלוחה יש להגדיר (בהגדרות השלוחה)

api_log=no

על מנת לבטל את הפעולה עבור פעולה ספציפית יש להגדיר בתגובת השרת בתחילת התשובה api_log_no& ולאחר מכן לרשום את התשובה הרצויה
לדוגמה

api_log_no&go_to_folder=/5/8

---

מיקום שמירת הלוג

כל השליחות והתשובות נמצאות בקובץ LogApi.ymgr שתחת תיקית Log שבתיקיה הראשית
בשביל לא ליצור קונפליקט במערכת, הוחלפו כמה תווים בקובץ
ApiSend - החלפנו את = בסימן ^ וכן את & בסימן *
ApiAnswer - החלפנו את , בסימן ^ וכן את & בסימן *

---

לחזרה לתחילת השרשור