API - גישת מפתחים למערכות

[eliyahu]

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

[eliyahu]

מצב הקמפיין-GetCampaignStatus

[eliyahu]

הורדת דו"ח קמפיין-DownloadCampaignReport

[eliyahu]

קבלת קמפיינים פעילים-GetActiveCampaigns

[eliyahu]

ביצוע פעולות בקמפיינים פעילים-CampaignAction

[eliyahu]

יצירת קמפיין מתוזמן-ScheduleCampaign

[eliyahu]

קבלת קמפיינים מתוזמנים-GetScheduledCampaigns

[eliyahu]

מחיקת קמפיין מתוזמן-DeleteScheduledCampaign

[eliyahu]

קבלת מידע מלא על השלוחה-GetIVR2Dir

[eliyahu]

קבלת רשימת קבצים שבשלוחה-GetIvrTree

[eliyahu]

ניהול קבצים

הפקודה היא FileAction

הפרמטרים הנדרשים

פרמטר	תיאור	הערה
token	טוקן
action	סוג הפעולה לביצוע	ראה להלן
what	נתיב	ראה להלן
target	יעד	ראה להלן

בפרמטר action האפשרויות הקיימות הן:

1. copy - העתקה
2. move - העברה (לשינוי שם של שלוחה או קובץ יש להשתמש בהעברה)
3. delete - מחיקה

בפרמטר what האפשרויות הקיימות הן:

1. ניהול קובץ בודד או שלוחה בודדת.
2. ניהול קבצים מרובים כאשר בפרמטר what יש לציין כל קובץ או שלוחה בנפרד. לדוגמה:

${url}/FileAction?token=${token}&action=${action}&what0=ivr2:1&what1=ivr:2/ext.ini

בדוגמה: ניהול שלוחה 1 וניהול קובץ ext.ini שבשלוחה 2.

בפעולה מסוג העברה או העתקה חובה לציין פרמטר target. האפשרויות הקיימות הן:

1. בניהול קבצים מרובים או שלוחות מרובות יש לציין את נתיב היעד הרצוי. לדוגמה, במידה והיעד הוא שלוחה 1 יש לציין את הנתיב כך target=ivr2:1.
   הערה: שימו לב! השם המקורי נשמר. במידה ומדובר בהעברת או העתקת קבצים עם שם בעל מספר סידורי שמות הקבצים ישתנו בהתאם לשמות הקבצים בשלוחת היעד. (לדוגמה, אם בוצעה העתקה של קובץ 001 משלוחה 2 לשלוחה 1 ששם קיים קובץ בשם 050 אז השם של הקובץ שהועתק ישתנה ל-051).
2. בניהול קובץ בודד או שלוחה בודדת ניתן גם לציין נתיב מלא כולל השם הרצוי ביעד.

מאפייני תגובת השרת:

מאפיין	סוג	הסבר	הערה
reports	array	מערך אובייקטים	ראה להלן
success	boolean	האם הפעולה בוצעה	במידה וכן, יופיע הערך true. במידה ולא, יופיע הערך false
action		סוג הפעולה שבוצעה

תבנית אובייקט

מאפיין	ערך
what	נתיב מקור
target	נתיב יעד
success	האם בוצע (זהה לתיאור לעיל)

[eliyahu]

קבלת תוכן קובץ טקסט-GetTextFile

[eliyahu]

העלאת טקסט לקובץ

הערה: במידה והקובץ לא קיים בשלוחה, ייווצר קובץ חדש.

הפקודה היא - UploadTextFile

הפרמטרים הנדרשים:

פרמטר	תיאור	הערות
token	טוקן
what	שם הקובץ והסיומת	יש לציין את הנתיב המלא. לדוגמה ivr2:1/ext.ini
contents	תוכן הקובץ להעלאה	במידה וקיים כבר טקסט בקובץ הוא יימחק

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

[eliyahu]

עדכון הגדרות שלוחה

שימו לב! בשונה מהפקודה UploadTextFile כאן המערכת לא מוחקת את הקיים בקובץ ext.ini והדבר היחיד שמשתנה הוא מה שאתם שולחים לשרת

הערה: במידה והשלוחה לא קיימת במערכת, תיווצר שלוחה חדשה.

הפקודה היא - UpdateExtension

הפרמטרים הנדרשים:

פרמטר	תיאור / הערות
token	טוקן
path	נתיב

בפרמטרים הנוספים תוכלו לצרף ערכים לעדכון בקובץ ext.ini

לדוגמה:

${url}UpdateExtension?token=${token}&path=ivr2:1&type=menu&title=בדיקה&enter_id=yes

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

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

[שמואל]

הכוונת שיחה - העברת מאזין באפשרות הראשונה לשלוחה אחרת או לניתוק

הפקודה היא - CallAction

הפרמטרים הנדרשים:

פרמטר	תיאור	הערות
token	טוקן
ids	מזהה ייחודי של השיחה כפי שהתקבל בקריאה GetIncomingCalls	ניתן לשרשר כמה שיחות לביצוע על ידי כתיבה : בין id לid
action	set:GOasap=XXXX	יש להחליף את "XXX" בלאן להעביר את המאזין, נתיב העברה, או "hangup" לניתוק

מאפייני תגובת השרת:

מאפיין	סוג	הסבר
calls	array	פירוט השיחות שבוצעה בהן פעולה - זהה לתיאור המופיע בפקודה GetIncomingCalls
action		סוג הפעולה שבוצעה
callsCount	int	מספר כולל של שיחות שבוצעה בהן פעולה

[שמואל]

ניהול חדרי ועידה:

---

הפקודה היא - CallAction

בקריאה ל GetIncomingCalls יש מערך של שיחות של חדרי ועידה, כל הפעולות המפורטות כאן צריכות להיות מבוצעות על הid של המאזין של חדר הועידה - ולא על הID הראשי.

טיפה הסבר על מערך של שיחות הוועידה:

דוגמא:

נעבור על החלקים החשובים.

פרמטר	תיאור	הערות
confCalls	מכיל את מספר המערכת הראשי, ואז - ואז את השלוחה של חדר הועידה
mute	האם הערוץ מושתק
hand	האם יש הרמת אצבע
admin	האם מנהל
data['survey']	מכיל את נתוני הצבעה, במהלך החדר המאזין יכול להקיש על כל הספרות בטלפון שלו וזה משוקף מייד.	באם אין הקשה הערך לא יופיע

---

הוספה או הסרה של רכיבים מה path וממערך data.

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

הוספה של ערך:

פרמטר	תיאור	הערות
token	טוקן
ids	מזהה ייחודי של השיחה כפי שהתקבל בקריאה GetIncomingCalls	ניתן לשרשר כמה שיחות לביצוע על ידי כתיבה : בין id לid
path:add:XXX	הוספה של נתון בpath, זה גם יופיע במערך data שהובא לעיל	יש להחליף את XXX בערך, למשל: path:add:survey=7.

הסרה של ערך:

פה ניתן לשלוח רק את ההתחלה של הערך, והוא ירד.

פרמטר	תיאור	הערות
token	טוקן
ids	מזהה ייחודי של השיחה כפי שהתקבל בקריאה GetIncomingCalls	ניתן לשרשר כמה שיחות לביצוע על ידי כתיבה : בין id לid
path:remove:XXX	הסרה של נתון בpath, זה גם ירד במערך data שהובא לעיל	יש להחליף את XXX בתחילת ערך, למשל: path:remove:survey=. זה יגרום למחיקה של ערך survey ממערך הdata בכלל - למשל, כדי לאפס נתוני הצבעה.

יש לשים לב, זה לא משפיע על סוג וצורת החדר, למשל, שליחה של path:add:admin לא תגרום למאזין להיות מנהל של החדר.

---

הוצאה מחדר ועידה.

הפרמטרים הנדרשים:

פרמטר	תיאור	הערות
token	טוקן
ids	מזהה ייחודי של השיחה כפי שהתקבל בקריאה GetIncomingCalls	ניתן לשרשר כמה שיחות לביצוע על ידי כתיבה : בין id לid
action	kick

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

---

השתקת הערוץ:

הפרמטרים הנדרשים:

פרמטר	תיאור	הערות
token	טוקן
ids	מזהה ייחודי של השיחה כפי שהתקבל בקריאה GetIncomingCalls	ניתן לשרשר כמה שיחות לביצוע על ידי כתיבה : בין id לid
action	mute

---

ביטול השתקה של הערוץ:

הפרמטרים הנדרשים:

פרמטר	תיאור	הערות
token	טוקן
ids	מזהה ייחודי של השיחה כפי שהתקבל בקריאה GetIncomingCalls	ניתן לשרשר כמה שיחות לביצוע על ידי כתיבה : בין id לid
action	unmute

---

סימון הורדת יד:

בדומה להורדת אצבע על ידי המאזין בטלפון.

הפרמטרים הנדרשים:

פרמטר	תיאור	הערות
token	טוקן
ids	מזהה ייחודי של השיחה כפי שהתקבל בקריאה GetIncomingCalls	ניתן לשרשר כמה שיחות לביצוע על ידי כתיבה : בין id לid
action	lowerhand

---

סימון הרמת יד:

בדומה להרמת אצבע על ידי המאזין בטלפון.

הפרמטרים הנדרשים:

פרמטר	תיאור	הערות
token	טוקן
ids	מזהה ייחודי של השיחה כפי שהתקבל בקריאה GetIncomingCalls	ניתן לשרשר כמה שיחות לביצוע על ידי כתיבה : בין id לid
action	raisehand

---

כיוון הוצאה מחדר ועידה:

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

הפרמטרים הנדרשים:

פרמטר	תיאור	הערות
token	טוקן
ids	מזהה ייחודי של השיחה כפי שהתקבל בקריאה GetIncomingCalls	ניתן לשרשר כמה שיחות לביצוע על ידי כתיבה : בין id לid
set:ConfbridgeNewGoto=/XX	מסמן לאן להעביר את המאזין בביצוע kick מהאתר	יש לכתוב נתיב להעברה או hangup לניתוק.

---

---

מאפייני תגובת השרת בכל הפעולות:

מאפיין	סוג	הסבר
calls	array	פירוט השיחות שבוצעה בהן פעולה - זהה לתיאור המופיע בפקודה GetIncomingCalls
action		סוג הפעולה שבוצעה
callsCount	int	מספר כולל של שיחות שבוצעה בהן פעולה

[שמואל]

שינוי השפה בערוץ:

גובר על ערך language בשלוחה ובivr.ini.

הפרמטרים הנדרשים:

פרמטר	תיאור	הערות
token	טוקן
ids	מזהה ייחודי של השיחה כפי שהתקבל בקריאה GetIncomingCalls	ניתן לשרשר כמה שיחות לביצוע על ידי כתיבה : בין id לid
set:Clanguage=XX	מסמן את השפה החדשה בערוץ כולו יש להחליף את XX בשפה המבוקשת - כל קודי השפה שיש כמו במערכת עצמה	השינוי יכנס לתוקף במעבר שלוחה הבא של המאזין.

---

---

מאפייני תגובת השרת:

מאפיין	סוג	הסבר
calls	array	פירוט השיחות שבוצעה בהן פעולה - זהה לתיאור המופיע בפקודה GetIncomingCalls
action		סוג הפעולה שבוצעה
callsCount	int	מספר כולל של שיחות שבוצעה בהן פעולה

[שמואל]

קבלת סיכום דקות נכנסות למערכת לפי טווח תאריכים

הפקודה היא - GetIncomingSum

הפרמטרים הנדרשים

פרמטר	תיאור	דוגמא
token	טוקן
from	מאיזה תאריך	YYYY-mm-dd
to	עד איזה תאריך	YYYY-mm-dd

בחירת מחדל - אם לא צויין טווח תאריכים - יביא מתחילת החודש הלועזי

מאפייני תגובת השרת

מאפיין	סוג	הסבר
fromDate	string	מאיזה תאריך מוצגים הנתונים
toDate	string	עד איזה תאריך מוצגים הנתונים
direct	int	דקות בחיוג ישיר למערכת
transferIn	int	דקות ממערכות אחרות
transferOut	int	דקות שיצאו למערכות אחרות

[שמואל]

קבלת לוג סמסים יוצאים

הפקודה היא - GetSmsOutLog

הפרמטרים הנדרשים

פרמטר	תיאור	סוג
token	טוקן
limit	הגבלת תוצאות	int

בחירת מחדל מביא את כל הסמסים.
סדר קבלת הסמסים הם מהחדש לישן

מאפייני תגובת השרת

מאפיין	סוג	הסבר
rows	array	מערך של הסמסים היוצאים

להלן תוכן מערך הסמסים:

מאפיין	סוג	הסבר
CallerId	string	זיהוי יוצא
To	string	יעד
Message	string	תוכן ההודעה
Billing	int	עלות ביחידות
RunBy	string	פרטי מבצע הפעולה
Time	string	זמן השליחה
DeliveryReport	string	דוח מסירה

להלן סוגי סטטוס דוחות מסירה נפוצים לפי תקן SMPP:

#	הסבר
null	לא התקבל מידע על מסירת ההודעה
DELIVRD	נמסר
ESME_ROK	הועבר לשליחה בהצלחה
EXPIRED	פג תוקף מעקב המסירה
ESME_RINVDSTADR	יעד לא נגיש
ESME_RINVMSGLEN	אורך לא חוקי
ESME_RINVCMDLEN	אורך פקודה שגוי
ESME_RMSGQFUL	תור ההודעות מלא
ESME_RINVNUMDESTS	מספר יעדים לא חוקי

[שמואל]

ממשק אירועי אבטחה.

תיעוד API לגישה לאירועי האבטחה של המערכת של המערכת.

ה Web Services היבוארו כאן:

ValidationToken // מידע על הטוקן
DoubleAuth // ביצוע אימות דו שלבי בטוקן
GetLoginLog // קבלת לוג ניסיונות התחברות
GetAllSessions // קבלת סשנים פעילים
KillSession // סגירת סשן ספציפי
KillAllSessions // סגירת כל הסשנים הפעילים

הערה חשובה:

שימוש בטוקן שהוא שם משתמש וסיסמה של המערכת (077777:1234) לא ממולץ לעבודה עם מתודות שדורשים אימות דו שלבי מכיוון שהאימות הדו שלבי זה ברמת טוקן והתחברות בצורה כזו יוצרת טוקן משתנה.

---

מתודה - ValidationToken
קבלת מידע על טוקן.

הפרמטרים הנדרשים

פרמטר	תיאור
token	טוקן

בתגובת השרת במידה שהטוקן תקין יתקבל מערך בשם tokenData המכיל את המידע הבא:

מאפיין	סוג	הסבר	דוגמא
remoteIP	string	כתובת IP של יוצר הטוקן	172.18.0.1
sessionType	string	סוג החיבור	API
createTime	string	זמן יצירה	2021-07-30 14:38:30
lastRequest	string	שימוש אחרון	2021-07-30 14:42:31
doubleAuthStatus	boolean	האם החיבור עבר אימות דו-שלבי	false
validationCalls	int	כמות שיחות אימות שיצאו ולא אומתו (ערך כללי, לא קשור לחיבור הספציפי)	3
token	string	רמז של הטוקן	hwe***5J76TM

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

---

מתודה - DoubleAuth
ביצוע אימות דו שלבי בטוקן.

הפרמטרים הנדרשים

פרמטר	תיאור
token	טוקן
action	פעולה: שליחת שיחת אימות או אימות בפועל.

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

קבלת שיחה:

שולחים פרמטר SendCode בערך action.

תגובה תקינה של השרת:

מאפיין	סוג	הסבר	דוגמא
responseStatus	string	סטטוס הפעולה	OK
message	string	הודעת הצלחה	Call successfully sent
LastNumberToSend	string	4 הספרות האחרונות של המספר שאליו נשלחה השיחה	7770

שגיאות אפשרויות:
סוג השגיאה מופיע ב responseStatus

#	סוג שגיאה	ערך הסברה	תוכן	הסבר
1	EXCEPTION	message	Missing parameters	חסרים פרמטרים, או ש action ריק או שהוא מצפה לערך נוסף
2	EXCEPTION	message	createPhone is Not Valid. verification is disabled	מספר יוצר המערכת לא מעודכן או לא מספר תקין, לא ניתן לבצע אימות
3	ERROR	message	Token has already been verified	כבר בוצע אימות דו שלבי בטוקן זה.
4	ERROR	message	Too many validation Calls. Try for a few more hours	יותר מידי שליחת שיחות במערכת ללא אימות בטווח קצר.

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

ניתן לראות את המונה שיחות של המערכת בפניה ל ValidationToken.
המונה מתאפס כל כ6 שעות.

ביצוע אימות בפועל:

שולחים פרמטר VerifyCode בערך action ואת 4 הספרות של המספר שקיבלתם ממנו את השיחה בערך code.

תגובה תקינה של השרת:

מאפיין	סוג	הסבר	דוגמא
responseStatus	string	סטטוס הפעולה	OK
message	string	הודעת הצלחה	VerifiedOK

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

שגיאות אפשרויות:
סוג השגיאה מופיע ב responseStatus

#	סוג שגיאה	ערך הסברה	תוכן	הסבר
1	ERROR	message	Please SendCode before	לא ניתן לבצע אימות לפני שליחת שיחה. יש לשלוח שיחה קודם.
2	ERROR	message	Authentication failed	הקוד לא תקין.
3	ERROR	message	Missing parameters	חסרים פרמטרים, או ש action ריק או שהוא מצפה לערך נוסף
4	ERROR	message	Token has already been verified	כבר בוצע אימות דו שלבי בטוקן זה.

---

מתודה - GetLoginLog
קבל לוג התחברויות

הפרמטרים הנדרשים

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

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

בתגובת השרת במידה שהטוקן תקין יתקבל array בשם data המכיל את כל התוצאות, כל תוצאה היא גם מערך המכיל את השדות הבאים:

מאפיין	סוג	הסבר	דוגמא
remoteIP	string	כתובת IP	172.18.0.1
sessionType	string	סוג החיבור	REGULAR
actionTimestamp	string	זמן	2021-07-30 14:13:00
username	string	שם המשתמש	0773137770
successful	boolean	האם מדובר בחיבור מוצלח או לא	false

שגיאות אפשרויות:
סוג השגיאה מופיע ב responseStatus

#	סוג שגיאה	ערך הסברה	תוכן	הסבר
1	EXCEPTION	message	Unverified session	טוקן לא עבר אימות דו שלבי.
2	EXCEPTION	message	Unknown username	ערך שם משתמש שגוי.

---

מתודה - GetAllSessions
קבל סשנים פעילים

הפרמטרים הנדרשים

פרמטר	תיאור
token	טוקן שעבר אימות דו שלבי
limit	ניתן להגביל את כמות התוצאות שיתקבלו

בתגובת השרת במידה שהטוקן תקין יתקבל array בשם sessions המכיל את כל החיבורים וערך int בשם sessionsCount המכיל את כמות הסשנים הפעילים.
כל ערך בתוך sessions יכיל:

מאפיין	סוג	הסבר	דוגמא
id	int	מזהה טוקן, לצורך הריגה שלו	16598
token	string	רמז של הטוקן	hwe***5J76TM
active	boolean	האם הטוקן פעיל	true
selectedDID	string	שם משתמש (בחיבור של API זה null	0773137770
remoteIP	string	כתובת IP של יוצר הטוקן	172.18.0.1
sessionType	string	סוג החיבור	API
createTime	string	זמן יצירה	2021-07-30 14:38:30
lastRequest	string	שימוש אחרון	2021-07-30 14:42:31
doubleAuthStatus	boolean	האם החיבור עבר אימות דו-שלבי	false

שגיאות אפשרויות:
סוג השגיאה מופיע ב responseStatus

#	סוג שגיאה	ערך הסברה	תוכן	הסבר
1	EXCEPTION	message	Unverified session	טוקן לא עבר אימות דו שלבי.

---

מתודה - KillSession
סגירת סשן

הפרמטרים הנדרשים

פרמטר	תיאור
token	טוקן שעבר אימות דו שלבי
SessionId	מזהה סשן להריגה

תגובה תקינה של השרת:

מאפיין	סוג	הסבר	דוגמא
responseStatus	string	סטטוס הפעולה	OK
SessionId	string	מזהה הסשן שנסגר	35

שגיאות אפשרויות:
סוג השגיאה מופיע ב responseStatus

#	סוג שגיאה	ערך הסברה	תוכן	הסבר
1	EXCEPTION	message	Unverified session	טוקן לא עבר אימות דו שלבי.
2	EXCEPTION	message	SessionId Can only be a number	ערך מזהה סשן ריק או לא תקין.
3	ERROR	message	SSessionId is broken	מזהה סשן לא פעיל או לא נמצא.

---

מתודה - KillAllSessions
סגירת כל הסשנים הפעילים של המערכת

הפרמטרים הנדרשים

פרמטר	תיאור	סוג
token	טוקן שעבר אימות דו שלבי

תגובה תקינה של השרת:

מאפיין	סוג	הסבר	דוגמא
responseStatus	string	סטטוס הפעולה	OK
KillSessions	string	כמות הסשנים שנסגרו	10

שגיאות אפשרויות:
סוג השגיאה מופיע ב responseStatus

#	סוג שגיאה	ערך הסברה	תוכן	הסבר
1	EXCEPTION	message	Unverified session	טוקן לא עבר אימות דו שלבי.