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

eliyahu

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

eliyahu

ביצוע פעולות בקמפיין בזמן אמת

הפקודה היא CampaignAction

תיאור
שירות זה מאפשר לבצע פעולות ניהול בזמן אמת על קמפיין פעיל.
המערכת תומכת בשני סוגי פעולות:

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

חלק א' – פעולות כלליות בקמפיין

פרמטרים בבקשה

פרמטר	חובה	תיאור
`token`	כן	טוקן
`campaignId`	כן	מזהה הקמפיין, כפי שהוחזר מ־`RunCampaign`.
`action`	כן	הפעולה שיש לבצע (ראו טבלה להלן).
`value`	תלוי	ערך נלווה לפעולה (למשל `0`, `1` או מספר ערוצים).

פעולות כלליות נתמכות (`action`)

ערך (`action`)	תיאור	ערך `value` נדרש
`stop`	עצירת הקמפיין באופן מיידי.	לא נדרש
`setPaused`	הפעלת/ביטול מצב מושהה – `1` להשהיה, `0` לביטול.	`0` או `1`
`setMaxActiveChannels`	שינוי כמות מקסימלית של שיחות פעילות בו־זמנית במהלך הקמפיין.	מספר
`setMaxBridgedChannels`	שינוי כמות מקסימלית של שיחות מנותבות בו־זמנית במהלך הקמפיין.	מספר

מבנה תגובה

{
  "responseStatus": "OK",
  "campaign": { ... },         /// סטטוס מעודכן של הקמפיין (ראו פירוט בהמשך)
  "action": "setPaused",       /// הפעולה שבוצעה
  "value": "1"                 /// הערך שנשלח לביצוע הפעולה
}

חלק ב' – פעולות על מספרים ספציפיים

פרמטרים בבקשה

פרמטר	חובה	תיאור
`token`	כן	טוקן
`campaignId`	כן	מזהה הקמפיין
`action`	כן	אחת מהפעולות: `add`, `block`, `hangup`.
`value`	כן	רשימת מספרים לביצוע הפעולה – בפורמט `:` או JSON (ראו להלן).

פעולות נתמכות במספרים (`action`)

ערך (`action`)	תיאור פעולה
`add`	הוספת מספרים לרשימת החיוג של הקמפיין (גם תוך כדי ריצה).
`block`	חסימת מספרים – לא יבוצעו אליהם חיוגים נוספים.
`hangup`	ניתוק מיידי של שיחות פעילות למספרים שצוינו.

פורמט `value` – רשימת מספרים

אפשרות 1: מחרוזת מופרדת ב־`:`

0501234567:0527654321

אפשרות 2: JSON מלא כמו ב־`RunCampaign`

{
  "0501234567": "הודעה מותאמת אישית",
  "0527654321": {
    "name": "חיים",
    "moreinfo": "מזכרת בתיה",
    "text": "שלום! זו הודעת תזכורת"
  }
}

מבנה תגובה

{
  "responseStatus": "OK",
  "campaign": { ... },         /// סטטוס מעודכן של הקמפיין
  "action": "add",             /// הפעולה שבוצעה
  "value": null,               /// ערך שנשלח (אם רלוונטי)
  "data": [
    {
      "phone": "0501234567",
      "action": "add"          /// הפעולה שבוצעה בפועל על המספר (ראה טבלה בהמשך)
    },
    {
      "phone": "0527654321",
      "action": "blocked"
    }
  ],
  "yemotAPIVersion": 6
}

אפשרויות ערך ב־`data[].action`

ערך (`action`)	תיאור הפעולה שבוצעה בפועל על המספר
`add`	המספר נוסף לקמפיין
`addblocked`	המספר נוסף אך מיד סומן כחסום
`block`	המספר נחסם ולא יחוייג שוב בקמפיין
`unblock`	בוטלה החסימה מהמספר
`hangup`	השיחה למספר זה נותקה (אם הייתה פעילה)
`failed`	המספר סומן כ"שיחה נכשלה" ולא יחוייג שוב

`campaign` – אובייקט סטטוס הקמפיין

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

כולל נתונים כגון:

campaignId, campaignStatus, templateId, callerId
ספירות של pendingEntries, activeEntries, doneEntries, failedEntries, redialEntries ועוד
הגדרות כמו maxActiveChannels, vmDetect, paused
עלות מצטברת (currentPrice)
זמן ריצה כולל (runTime)

eliyahu

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

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

פרמטר	אפשרויות	תיאור/הערות/פירוט
token		טוקן
templateId		מספר מזהה של הקמפיין
time		הגדרת זמן הפעלה באחד מהצורות הבאות (תאריך לועזי בלבד)
אופציה 1	yyyy-MM-dd-HH:mm:ss	שנה -חודש - יום-שעה:דקה:שניה
אופציה 2	yyyy-MM-dd-HH:mm	שנה -חודש - יום-שעה:דקה
אופציה 3	yyyy-MM-dd HH:mm:ss	שנה -חודש - יום שעה:דקה:שניה(בין היום לשעה רווח במקום `-`)
אופציה 4	yyyy-MM-dd	שנה -חודש-יום
אופציה 5	HH:mm:ss	שעה:דקה:שניה
אופציה 6	HH:mm	שעה:דקה

eliyahu

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

הפקודה היא - GetScheduledCampaigns

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

פרמטר	תיאור/הערות
token	טוקן
type	סוג הקמפיינים להחזרה. האפשרויות הם `PENDING` קמפיינים המיועדים לביצוע. `SUCCESSFUL` קמפיינים שבוצעו בהצלחה. `FAILED` קמפיינים שנכשלו.
order	סדר המיון. האפשרויות הם: `asc` (ברירת מחדל) - סדר עולה. `desc`- סדר יורד
from	אופציונלי - maximum number of records to include
limit	אופציונלי - מקסימום של קמפיינים להחזרה

eliyahu

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

eliyahu

הצגת תוכן שלוחה (תיקייה)

הפקודה היא GetIVR2Dir

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

פרמטר	תיאור	הערות
token	טוקן	חובה
path	נתיב תיקייה	חובה. לדוגמה: `/` עבור שלוחה ראשית. `1` עבור שלוחה 1 `ext/1` עבור שלוחה `ext/1`
filesFrom	הצג קבצים מ	רשות. `0` יציג מהקובץ הראשון `1` יציג מהקובץ השני וכן הלאה. ברירת מחדל מציג מהקובץ הראשון.
filesLimit	הצג קבצים עד	רשות. לדוגמה, `5` יציג את הקובץ החמישי (כולל). ברירת מחדל מציג עד הקובץ האחרון
orderBy	מיין קבצים לפי	ראה להלן "ערכים אפשריים לפרמטר orderBy"
orderDir	סדר קבצים	`asc` - סדר עולה. `desc` - סדר יורד.

ערכים אפשריים לפרמטר orderBy

ערך	תיאור
name	שם קובץ (ברירת מחדל)
date	תאריך יצירה
mtime	תאריך שינוי אחרון
customerdid	מספר מערכת
uploader	מעלה הקובץ
size	גודל
source	מקור

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

מאפיין	סוג	הסבר
extIni	object	אובייקט הכולל את הגדרות השלוחה
thisPath	string	נתיב תיקייה נוכחית
parentPath	string	נתיב תיקיית אב
dirs	Array	מערך הכולל את התיקיות והשלוחות שבתיקייה הנוכחית
files	Array	מערך הכולל את הקבצים שבתיקייה הנוכחית (מלבד קבצי ini ו-html שנמצאים במערך נפרד)
ini	Array	מערך הכולל את קבצי ההגדרות (ini) שבשלוחה
messages	Array	מערך הכולל את הודעות המערכת הקשורות לשלוחה
html	Array	מערך הכולל את קבצי הדוחות (html) שבשלוחה
msgDescriptions	object	אובייקט הכולל את התיאור של כל הודעות המערכת בשלוחה (למשל `M0000=הודעת ברוכים הבאים`)

מאפיינים משותפים לאובייקטים במערכים "dirs" "files" "ini" "messages" "html"

מאפיין	סוג	הסבר
exists	boolean	האם התיקייה/קובץ קיימים
name	string	שם התיקייה/קובץ
uniqueId	string	מזהה ייחודי לתיקייה/קובץ
what	string	נתיב תיקייה/קובץ
fileType	string	סוג תיקייה/קובץ

מאפיינים משותפים לאובייקטים במערכים "files" "ini" "messages" "html"

מאפיין	סוג	הסבר
size	int	גודל קובץ (בבתים)
mtime	string	תאריך שינוי אחרון

מאפיינים משותפים לאובייקטים במערכים "files" "messages"
הערה: המאפיינים הבאים הינם עבור קבצי שמע בלבד

מאפיין	סוג	הסבר
duration		אורך (בדקות)
durationStr	string	אורך בפורמט mm:ss
customerDid	string	מספר מערכת בה נוצר הקובץ
meta	string	אובייקט המכיל מידע נוסף על הקובץ
date	string	זמן יצירת קובץ dd/mm/yyyy hh:mm
source	string	מקור הקובץ
phone	string	טלפון יוצר הקובץ
ip	string	כתובת IP של מעלה הקובץ

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

מאפיין	סוג	הסבר
extType	string	סוג שלוחה
extTitle	string	תיאור שלוחה

eliyahu

קבלת מידע על קובץ בודד

הפקודה היא - GetFile

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

פרמטר	תיאור	סוג
token	טוקן	string
what	נתיב במערכת	string (דוגמה למטה)

דוגמה לנתיב

what=ivr2:2/000.wav    /// מידע על קובץ 000 בשלוחה 2

תגובה (במידה והקובץ קיים)
דומה למאפיינים של קובץ כפי שמופיע בGetIVR2Dir

במידה וקובץ לא קיים יחזור שגיאה

{
  "responseStatus": "ERROR",
  "message": "file does not exist",
  "messageCode": null,
  "yemotAPIVersion": 6
}

במידה ונתיב לא חוקי יחזור

{
  "responseStatus": "EXCEPTION",
  "exceptionClass": "IllegalArgumentException",
  "exceptionMessage": "bad descriptor format. don't know what is xyz",
  "nestedException": null,
  "yemotAPIVersion": 6
}

eliyahu

ניהול תיקיות וקבצים

הפקודה היא FileAction

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

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

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

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

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

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

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

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

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

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

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

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

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

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

eliyahu

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

הפקודה היא - GetTextFile

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

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

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

מאפיין	סוג	ערך
contents	string	התוכן הכתוב בקובץ
file	array	מערך אובייקטים (ראה להלן)

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

מאפיין	סוג	ערך
exists	boolean	האם הפעולה בוצעה (במידה וכן, יופיע הערך `true`. במידה ולא, יופיע הערך `false`)
name	string	שם הקובץ
uniqueId	string	מזהה תנועה ייחודי
fileType	string	סוג קובץ (למשל: `INI`)
size	int	גודל קובץ
mtime	string	תאריך ושעה שהקובץ השתנה (פורמט: dd/MM/yyyy HH:mm)
what	string	נתיב מלא

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
action=set:Clanguage=XX	מסמן את השפה החדשה בערוץ כולו יש להחליף את XX בשפה המבוקשת - כל קודי השפה שיש כמו במערכת עצמה	השינוי יכנס לתוקף במעבר שלוחה הבא של המאזין.

דוגמה

CallAction?token=xxxxxxxx&ids=fgdhfszfzvxbdgsxf&action=set:Clanguage=en

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

מאפיין	סוג	הסבר
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	יותר מידי שליחת שיחות במערכת ללא אימות בטווח קצר.

הסבר חשוב בנוגע לשגיאה 4: על מנת למנוע ניצול לרעה שליחת שיחות אימות מוגבלות, כל שליחה של שיחת אימות נספרת, וכל אימות מוצלח מוריד ספירה.
זה אומר, שאם תבצעו אימות מוצלח ושיחה אחד בלבד זה לא יחשב בתור שיחה, אבל אם תשלחו 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	טוקן לא עבר אימות דו שלבי.

שמואל

הפעלת צינתוק

הפקודה היא - RunTzintuk

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

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

פרמטר	תיאור	סוג
token	טוקן
callerId	זיהוי יוצא, בחירת מחדל זיהוי ראשי של המערכת, ניתן לכתוב זיהוי ספיישל או מספר משנה. ניתן להשתמש עם זיהוי רנדומלי על ידי ציון `RAND`, זיהוי רנדומלי יבואר מתחת לטבלא	int
TzintukTimeOut	זמן צינתוק. בחירת מחדל 9 שניות. מקסימום זמן צינתוק 16 שניות	Float
phones	מספרים לחיוג. יבוארו האפשרויות למטה.

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

צורות אפשרויות להגשת רשימת המספרים לחיוג:
כאשר הפניה היא בGET או בPOST שהוא לא jsos (Content-Type: application/json) יש 3 אפשריות:

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

{
    "phones": [
        "0510000",
        "0510001",
        "0510002",
        "0510003"
    ]
}

או כמערך עם אובייקטים לצורך ציון זיהוי יוצא ספציפי לכל מספר:

{
    "phones": [
        {
            "phone": "0511111",
            "callerId": "077313"
        },
        {
            "phone": "05111333",
            "callerId": "07731344"
        }
    ]
}

או על אותו הדרך עם קבוצות:

"phones": [
        {
            "phones": [
                "0511111",
                "051111221"
            ],
            "callerId": "077313"
        },
        {
            "phones": [
                "0511111999"
            ],
            "callerId": "077414"
        }
    ]

ואז ניתן להוציא צינתוק לרשימת מספרים עם ״זיהוי שיחה מתחלף״.

שליחת צינתוקים לכמה רשימות צינתוקים חינמיים יחד:

השירות מוגבל ל50 רשימות בקריאה.

בעת שליחת צינתוק לרשימת צינתוקים חינמיים ניתן להפעיל קמפיין אחד לכמה רשימות יחד.
מספרים הנמצאים בכמה מהרשימות יקבלו צינתוק אחד בלבד.
על מנת לציין כמה רשימות ניתן או לחלק את הרשימות על ידי , אחרי ציון tzl:. למשל, כדי לשלוח לרשימה 100 ולרשימה 200 ו 300 יש לציין: tzl:100,200,300.
במידה ששמות הרשימות מכילות את התו , זה ייצור בעיות, ולכן אפשר גם לציין את זה כמערך, זאת במידה שהשליחה היא בPOST - json באופן שבphones מציינים רק tzl: ואת הרשימות בפרמטר tzintukLists. כמו בדוגמא הבאה:

{
    "phones": "tzl:",
    "tzintukLists": [
        "100",
        "200",
        "בית ספר, כיתה ג",
        "משרד, מזכירות"
    ]
}

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

מאפיין	סוג	הסבר	דוגמא
responseStatus	sting	סטטוס הפעולה	`OK`
verifyCode	sting	4 ספרות אחרונות של הזיהוי היוצא לצורכי אימות. יהיה מלא רק במידה שהשיחה מזיהוי רנדומלי.	`9835`
callerId	sting	זיהוי השיחה היוצא	`0773137770`
callsCount	int	כמות שיחות יוצאות	`3`
bilingPerCall	int	תשלום לכל שיחה	`0.1`
biling	int	כמות תשלום כולל	`0.3`
errors	array	מערך של מספרי טלפון שלא נשלח אילהם השיחה כולל הסיבה.	מתחת לטבלא

דוגמא לפירוט שגיאות במערך "errors":

{
05832XXXXX: "blocked", // חסום
0773137770: "double", // מספר כפול
*8080: "notValid" // מספר לא תקין
}

שמואל

ניהול רשימות צינתוקים במודול צינתוקים חינמיים

הפקודה היא - TzintukimListManagement

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

פרמטר	תיאור	סוג
token	טוקן	string
action	פעולה לביצוע, ערך חובה. יוסברו הפעולות מטה	string
TzintukimList	מספר הרשימה. לא חובה כאשר מבקשים לקבל את רשימת הצינתוקים	string

פעולה: getlists

מחזיר את כל רשימות הצינתוקים בתוך מערך "lists"

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

מאפיין	סוג	הסבר	דוגמא
responseStatus	string	סטטוס הפעולה	`OK`
lists	array	מערך של הרשימות, ראה טבלא למטה

כל אובייקט במערך lists מכיל 2 ערכים:

מאפיין	סוג	הסבר	דוגמא
listName	string	שם הרשימה	120
subscribers	int	כמות רשומים	7

פעולה: getlistEnteres.
חובה לצרף ערך TzintukimList

מחזיר את רשימת המספרים המנויים לרשימה

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

מאפיין	סוג	הסבר	דוגמא
responseStatus	string	סטטוס הפעולה	`OK`
listName	string	שם הרשימה	1844
countSubscribers	int	כמות הרשומים	7
enteres	array	מערך של המספרים ושמות שלהם.

השמות נטענים מקובץ 'PhonesName.ini' מהשלוחה הראשית, תבנית הקובץ צריכה להכיל "טלפון=שם"

כל אובייקט במערך enteres מכיל:

מאפיין	סוג	הסבר	דוגמא
phone	string	מספר הטלפון הרשום
name	string	השם של מספר הטלפון הרשום כפי שנטען מקובץ PhonesName.ini

פעולה: getLogList
חובה לצרף ערך TzintukimList

מחזיר את לוג הפעולות שבוצעו על הרשימה

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

מאפיין	סוג	הסבר	דוגמא
responseStatus	string	סטטוס הפעולה	`OK`
events	array	מערך של האירועים, ראה טבלה

כל אובייקט במערך events מכיל:

מאפיין	סוג	הסבר	דוגמא
Folder	string	שלוחה במערכת	1/2
CustomerDID	string	מספר המערכת	0773137770
Phone	string	מבצע הפעולה	0533137770
Date	string	תאריך	19/01/2021
Time	string	שעת ביצוע	00:39:10
TypeOperation	string	סוג הפעולה	מצורף למטה הסוגים
PhoneAction	string	פעולה על טלפון	(הערך יהיה מלא במידה שמדובר בפעולה על טלפון מסויים ברשימה)

הסוגים האפשריים בTypeOperation:

AddToListTzintuk // הוספה לרשימה
RunTzintuk // הפעלת צינתוק
RemovingToListTzintuk // הסרה מהרשימה
AdminRemovingToListTzintuk // מנהל הסיר מספר מהרשימה
ResetToListTzintuk // הרשימה אופסה

פעולה: resetList
חובה לצרף ערך TzintukimList

מאפס רשימת צינתוקים

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

מאפיין	סוג	הסבר	דוגמא
responseStatus	string	סטטוס הפעולה	`OK`
list	string	הרשימה שאופסה

באם תיהיה שגיאה יחזיר שגיאה

שמואל

שליחת פקס

הפקודה היא - SendFax

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

פרמטר	תיאור	סוג
token	טוקן	string
pdfFile	קובץ לשליחה. יבואר 2 אפשרויות	string
phone	לאן לשלוח	string
callerId	זיהוי שיחה יוצאת. בחירת מחדל הזיהוי של המערכת הראשי	string
deliveryUrl	כתובת לקבלת דוח מסירה	string

pdfFile
ניתן לציין נתיב של קובץ מתוך המערכת, למשל: ivr2://FaxTest.pdf וישלח את קובץ "FaxTest.pdf" שתחת השלוחה הראשית. אפשר גם לציין את זה: /FaxTest.pdf, רק חשוב ה/ בהתחלה.

בנוסף, ניתן להעלות קובץ ספציפי, לצורך כך יש לציין בערך UPLOAD
ואז יש להעלות את הקובץ בערך "fileToUpload, כמובן בעת שימוש באפשרות זו הפניה חייבת להיות בPOST מסוג multipart/form-data

deliveryUrl יש לציין URL מלא לקבלת דוח מסירה. למשל: http://127.0.0.6:18358/FaxDel, הפניות ישלחו בPOST בלבד ויכילו את הערכים הבאים:

לכל הפניות יצורף ערך CampaignId שתוכלו להשוות אותו עם ערך CampaignId שמתקבל בהצלחה.
לכל הפניות יצורף ערך Delivery המכיל את סטטוס המסירה.

במידה שDelivery הוא NoAnswer יצורף ערך DIALSTATUS המכיל את התשובה של החיוג ללקוח.
במידה שDelivery הוא End יצורף ערך status המכיל את התשובה מצד מנוע הפקס. תשובה של מסירה מוצלחת תיהיה SUCCESS בערך status.
במידה שDelivery הוא Answer זה אומר שהשיחה נענת, מציין שהעברת הפקס התחילה.

על כל שליחה של פקס יש חיוב של 0.1 יחידות על עצם השליחה ובנוסף חיוב יחסי לפי הזמן של השיחה הפעילה - בחישוב של יחידה לדקה. אם זמן השליחה לקח 3 דקות תחוייבו בנוסף 3 יחידות, בנוסף, לא ניתן להפעיל שיחת פקס אם אין ספייר במערכת של יותר מ5 יחידות מהחיוב על השיחה עצמה.

מענה בעת הצלחה:

מאפיין	סוג	הסבר	דוגמא
responseStatus	string	סטטוס הפעולה	`OK`
callerId	string	זיהוי השיחה היוצאת	0773137770
CampaignId	string	מזהה הקמפיין	WSOC-LC-2021-08-28-21-40-49-083
deliveryUrl	string	מציין את הכתובת למסירה באם צויינה	http://127.0.0.6:18358/FaxDel
fileNameSend	string	שם הקובץ שנשלח	ivr2://FaxTest.pdf
callsCount	int	כמות שיחות יוצאות	1
bilingPerCall	float	חיוב לכל שיחה	0.1
biling	float	כמות חיוב בפועל	0.1

בעת שגיאה תפורט השגיאה והבעיה.

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

ביצוע פעולות בקמפיין בזמן אמת

חלק א' – פעולות כלליות בקמפיין

פרמטרים בבקשה

פעולות כלליות נתמכות (action)

מבנה תגובה

חלק ב' – פעולות על מספרים ספציפיים

פרמטרים בבקשה

פעולות נתמכות במספרים (action)

פורמט value – רשימת מספרים

אפשרות 1: מחרוזת מופרדת ב־:

אפשרות 2: JSON מלא כמו ב־RunCampaign

מבנה תגובה

אפשרויות ערך ב־data[].action

campaign – אובייקט סטטוס הקמפיין

קבלת מידע על קובץ בודד

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

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

הוספה של ערך:

הסרה של ערך:

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

השתקת הערוץ:

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

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

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

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

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

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

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

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

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

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

הערה חשובה:

הפעלת צינתוק

השירות מוגבל ל50 רשימות בקריאה.

ניהול רשימות צינתוקים במודול צינתוקים חינמיים

שליחת פקס

פעולות כלליות נתמכות (`action`)

פעולות נתמכות במספרים (`action`)

פורמט `value` – רשימת מספרים

אפשרות 1: מחרוזת מופרדת ב־`:`

אפשרות 2: JSON מלא כמו ב־`RunCampaign`

אפשרויות ערך ב־`data[].action`

`campaign` – אובייקט סטטוס הקמפיין