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

eliyahu

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

הפקודה היא - TransferUnits

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

פרמטר	תיאור/הערות
token	טוקן
destination	מספר מערכת להעברה
amount	כמות יחידות להעברה

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

מאפיין	סוג	ערך
destination	string	מערכת היעד אליה בוצעה ההעברה
amount	double	הסכום שהועבר
newBalance	double	יתרת היחידות במערכת המקור לאחר ביצוע ההעברה

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

messageCode	message	הסבר
111	Bad destination	יעד להעברה לא חוקי: המערכת אינה קיימת או שאינה מורשית לקבל יחידות ממערכת זו
112	Bad amount	סכום היחידות להעברה אינו חוקי
113	Not enough balance	יתרת היחידות שבמערכת אינה מאפשרת את ביצוע ההעברה

eliyahu

קבלת רשימת שיחות הפעילות במערכת

הפקודה היא - GetIncomingCalls

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

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

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

מאפיין	סוג	הסבר
calls	array	מערך אובייקטים (ראה "תבנית אובייקט שיחה" להלן)
callsCount	int	מספר כולל של שיחות במערכת

תבנית אובייקט שיחה

מאפיין	ערך
did	מספר מחוייג
callerIdNum	מספר מחייג (כולל ערכים של `ID` `val_name` במידה וקיים במערכת)
duration	משך זמן שיחה - בשניות
transferFrom	האם השיחה הועברה ממערכת אחרת. במידה וכן יופיע הערך `מועבר` במידה ולא יפיע הערך `null`
id	מזהה ייחודי לאורך השיחה
path	מספר שלוחה (כולל תיאור שלוחה ומספר קובץ במידה וקיים)

eliyahu

העלאת קובץ

הפקודה היא - UploadFile

מתודת פניה

יש לפנות ב-HTTP POST בפורמט multipart/form-data. (פרמטרים כמו token path וכדומה ניתן לצרף בגוף הפנייה או במחרוזת השאילתה כמו בבקשת GET)

שימו לב! ניתן לעלות קובץ בודד בכל פנייה.
חשוב לשים לב שיש מגבלה על גודל הקובץ שאפשר לעלות בבקשה אחת (נכון לתאריך 28/09/2022 המגבלה היא 50MB) ולכן אם הקובץ שלכם שוקל יותר מזה, צריך לפצל את הקובץ ולהעלות אותו בחלקים נפרדים וכפי שיובא להלן.

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

פרמטר	תיאור	הערות
token	טוקן	חובה
path	נתיב להעלאה	חובה. עבור העלאת קבצים לתיקיות במערכת יש לציין בהתחלה `ivr2:` ולאחר מכן את הנתיב המלא. למשל לקובץ 000.wav בתיקייה 5 הנתיב יהיה `ivr2:5/000.wav`. שימו לב שבהעלאה רגילה חובה לציין את שם הקובץ הרצוי, בהעלאה עם מספור אוטומטי (ראה להלן) יש לציין את התיקייה בלבד
convertAudio	המרת הקובץ	בוליאני (1/0). ברירת המחדל היא ללא המרה. אם convertAudio = 1, הקובץ שהועלה יומר אוטומטית לפורמט wav המתאים לטלפוניה. קובץ המקור יכול להיות בכל אחד מפורמטי האודיו הפופולריים (MP3, OGG, WMA וכו '). הערה: פרמטר הנתיב חייב להיות בשם של קובץ היעד לאחר ההמרה (כך שהוא חייב להיות עם סיומת .wav)
autoNumbering	מספור אוטומטי לקבצי שמע	בוליאני (true/false). באפשרות זו יש לציין בפרמטר path את נתיב התיקייה בלבד. למשל לתיקייה 5 יש לציין את הנתיב כך `path=ivr2:5/`. במקרה כזה, הקובץ יעלה לתיקייה 5 ויקבל את המספור הגבוה ביותר (int) עם סיומת wav.
tts	הצהרה על קובץ tts	בוליאני (1/0). נצרך במקרה של מספור אוטומטי לקבצי tts כדי שהמערכת לא תתן לקובץ את הסיומת wav אלא tts

פיצול קובץ לחלקים נפרדים והעלאה לשרת

שלב א' - העלאת הקבצים

פרמטר	תיאור	דוגמה
qquuid	ID יש ליצור באופן רנדומלי לפני הבקשה הראשונה	2017390a-60cf-44ea-822f-27017c13de69
qqpartindex	אינדקס העלאה	1
qqpartbyteoffset	עד כה עלה ללא הבקשה הנוכחית בבתים	4000000
qqchunksize	גודל הבקשה הנוכחית בבתים	4000000
qqtotalparts	סה"כ חלקים לביצוע (מתחיל ב0 כולל הבקשה האחרונה של החיבור)	8
qqtotalfilesize	גודל כולל של הקובץ בבתים	29863882
qqfilename	השם המקורי של הקובץ	בוקר טוב.mp3
qqfile	מקטע של הקובץ שאותו אנחנו מעלים בבקשה הנוכחית	(קובץ)
uploader	מחלקה שמבצעת את העלאה	yemot-admin

שלב ב' - סיום העלאה ובקשת חיבור לקבצים
בסיום העלאה יש לפנות אל - UploadFile?done
הפרמטרים שיש לצרף לבקשה

פרמטר	תיאור	דוגמה
token	טוקן	כנ"ל
path	נתיב	כנ"ל
convertAudio	המרת אודיו	כנ"ל
autoNumbering	מספור אוטומטי	כנ"ל
tts	קובץ tts	כנ"ל
qquuid	ID של מזהה הפעולה	2017390a-60cf-44ea-822f-27017c13de69
qqfilename	שם מקורי	בוקר טוב.mp3
qqtotalfilesize	גודל כולל	29863882
qqtotalparts	סך הכל חלקים	8

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

מאפיין	סוג	הסבר
path	string	נתיב הקובץ שהועלה, כפי שהועבר על ידי פרמטר הנתיב
size	long	גודל הקובץ שהועלה בבייטים

אם convertAudio = 1, יוחזרו בתגובה מאפיינים נוספים :

מאפיין	סוג	הסבר
convertedSize	long	גודל קובץ ה- WAV שהומר בבייטים
duration	double	משך האודיו בשניות

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

messageCode	message	הסבר
105	System error	שגיאה כללית במהלך הטיפול בהעלאה
107	File upload expected	לא נמצאה קובץ להעלאה בבקשה
108	Only single upload per request is supported	הועלה יותר מקובץ אחד בבקשה אחת
109	path is required	דרוש נתיב
110	path is invalid	הנתיב אינו חוקי

על מנת לבדוק העלאות HTTP ניתן להשתמש בטופס פשוט זה:
https://www.call2all.co.il/ym/api_upload_test.php

eliyahu

הורדת קובץ

הפקודה היא - DownloadFile

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

פרמטר	תיאור	הערות
token	טוקן
path	שם הקובץ להורדה	בהמשך יפורט איך לציין את הנתיב של כל קובץ

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

במידה והקובץ קיים - התגובה תכיל את את תוכן הקובץ המבוקש.
במידה והקובץ לא קיים או שהתרחשה שגיאה - התגובה תהיה HTTP 404 Not Found.

הערה: שימו לב שהתגובה לבקשה זו אינה JSON (בשונה משאר הבקשות)

eliyahu

קבלת מצב כל תבניות הקמפיינים

הפקודה היא - GetTemplates

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

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

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

מאפיין	סוג	הסבר
templates	array	מערך אובייקטים (ראה "אובייקט מזהה תבנית" להלן)

אובייקט מזהה תבנית:

מאפיין	סוג	ערך	הערות
templateId	int	מזהה התבנית	שימו לב לא מדובר במספר הסידורי כמו שמופיע באתר
description	string	תיאור התבנית	במידה ולא מוגדר יתקבל הערך `null`
callerId	string	זיהוי שיחה יוצאת
entriesCount	int	כמות המספרים שברשימת התפוצה	פעילים וחסומים
blockedEntriesCount	int	כמות המספרים החסומים
incomingPolicy	enum	מדיניות שיחות נכנסות. ישנם 4 מצבים `OPEN` `BLACKLIST` `WHITELIST` `BLOCKED`	רלוונטי לקמפיין ברירת המחדל בלבד
customerDefault	boolean	האם מדובר בקמפיין ברירת המחדל	במידה וכן, יופיע הערך `true` (-נכון). במידה ולא, יופיע הערך `false` (-שקר )
maxActiveChannels	int	הגבלת קווים מחייגים	מספר מקסימלי של שיחות פעילות בו זמנית בקמפיין
maxBridgedChannels	int	הגבלת קווים מנותבים	מספר מקסימלי של שיחות מנותבות בו זמנית למספר המוגדר בערך `bridgeTo`. אם מספר הקווים המנותבים מגיע למספר המוגדר כאן, החיוגים בקמפיין ייעצרו עד שמספר הקווים המנותבים ירד. ערך 0 בשדה זה פירושו שאין הגבלת מספר קוים מנותבים
originateTimeout	double	זמן חיוג מקסימלי - בשניות	זמן מקסימלי מתחילת החיוג למספר עד למענה השיחה. שיחה שלא נענתה עד זמן זה תירשם בדו"ח כשיחה שנכשלה מסיבת "אין מענה". במידה ומוגדר במערכת מדיניות חיוגים חוזרים באין מענה, המערכת תנסה לחייג שוב למספר שלא נענה בהתאם להגדרה הרלוונטית
vmDetect	boolean	האם האפשרות של זיהוי תא קולי מופעלת	במידה וכן, יופיע הערך `true`. במידה ולא, יופיע הערך `false`
filterEnabled	boolean	האם האפשרות של קמפיין ממספרים אישיים מופעלת	במידה וכן, יופיע הערך `true`. במידה ולא, יופיע הערך `false`
maxDialAttempts	int	ניסיונות חיוג	מספר מקסימלי של נסיונות חיוג שיבוצעו לאותו מספר בהתאם למדיניות חיוגים חוזרים המוגדרת לקמפיין
redialWait	int	המתנה בין נסיונות חיוג - בשניות	זמן המתנה מינימלי בשניות בין נסיונות חיוג לאותו מספר
redialPolicy	enum	מדיניות חיוגים חוזרים. ישנם 3 מצבים - `NONE` `CONGESTIONS` `FAILED`	`NONE` - ללא חיוג חוזר. `CONGESTIONS` - במידה ולא זמין. `FAILED` במידה ואין מענה
yemotContext	enum	סוג הקמפיין. ישנם 6 מצבים - `SIMPLE` `REPEAT` `MESSAGE` `VOICEMAIL` `BRIDGE` `OTHER`	`SIMPLE` - השמעת הודעה בלבד. `REPEAT` - השמעה חוזרת של ההודעה בהקשה על 1 ואישור קבלת ההודעה בהקשה על 7. `MESSAGE` - שליחת הודעה בדוא"ל בהקשה על 1. `VOICEMAIL` - השארת הודעה בתא קולי בהקשה על 1 שימו לב! באופן זמני התא הקולי בוטל. `BRIDGE` - ניתוב שיחה למענה אנושי. `OTHER` - הגדרה מיוחדת
bridgeTo	string	מספר הטלפון לניתוב	במידה והקמפיין מוגדר כניתוב שיחה למענה אנושי
playPrivateMsg	boolean	האם האפשרות של מצב הודעה פרטית מופעלת	במידה וכן, יופיע הערך `true`. במידה ולא, יופיע הערך `false`
messageExists	boolean	האם קיימת הודעת קמפיין	במידה וכן, יופיע הערך `true`. במידה ולא, יופיע הערך `false`
messageDuration	double	אורך הודעת הקמפיין - בשניות
unitsPerMessage	double	עלות משוערת ביחידות עבור כל הודעה שמשוגרת
moreinfoExists	boolean	האם קיימת הודעה לפני ניתוב (הודעה המושמעת אחרי שמקבל השיחה לחץ 1)	במידה וכן, יופיע הערך `true`. במידה ולא, יופיע הערך `false`
moreinfoDuration	double	אורך הודעת הניתוב - בשניות
removeRequest	enum	אפשרויות הסרה. קיימים 2 מצבים - `SILENT` `WITH_MESSAGE`	`SILENT` - הסרה בלחיצה על 9 ללא הודעה. `WITH_MESSAGE` - הסרה בלחיצה על 9 + הודעה סטנדרטית

eliyahu

עדכון תבנית קמפיין

הערה: רק ההגדרות שסופקו יעודכנו, ההגדרות שהושמטו לא ישתנו.

הפקודה היא UpdateTemplate

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

פרמטר	סוג	תיאור	הערות
token	string	טוקן	פרמטר חובה
templateId	int	מזהה תבנית	פרמטר חובה
description	string	תיאור התבנית
callerId	string	זיהוי שיחה יוצאת
incomingPolicy	enum (string)	מדיניות שיחות נכנסות - רלוונטי לקמפיין ברירת המחדל בלבד. ישנם 4 מצבים `OPEN` `BLACKLIST` `WHITELIST` `BLOCKED`	`OPEN` - כל אחד יכול להתקשר. `BLACKLIST` - מספרים שחסומים ברשימת התפוצה לא יוכלו לחייג. `WHITELIST` - רק מספרים שפעילים ברשימת התפוצה יוכלו לחייג. `BLOCKED` - אף אחד לא יוכל לחייג
customerDefault	boolean (1/0)	האם להגדיר כקמפיין ברירת המחדל	אם כן, יש להגדיר `1`. אם לא, יש להגדיר קמפיין אחר
maxActiveChannels	int	הגבלת קווים מחייגים	כאן ניתן להגדיר את המספר המקסימלי של שיחות פעילות בו זמנית בקמפיין
maxBridgedChannels	int	הגבלת קווים מנותבים	כאן ניתן להגדיר את המספר המקסימלי של שיחות מנותבות בו זמנית למספר המוגדר בערך `bridgeTo`. אם מספר הקווים המנותבים מגיע למספר המוגדר כאן, החיוגים בקמפיין ייעצרו עד שמספר הקווים המנותבים ירד. ערך 0 בשדה זה פירושו שאין הגבלת מספר קוים מנותבים
originateTimeout	double	זמן חיוג מקסימלי - בשניות	זמן מקסימלי מתחילת החיוג למספר עד למענה השיחה. שיחה שלא נענתה עד זמן זה תירשם בדו"ח כשיחה שנכשלה מסיבת "אין מענה"
vmDetect	boolean (1/0)	האם להפעיל את האפשרות של זיהוי תא קולי	במידה וכן, יש להגדיר `1`. במידה ולא, יש להגדיר `0`
filterEnabled	boolean (1/0)	האם להפעיל את האפשרות של קמפיין ממספרים אישיים	במידה וכן, יש להגדיר `1`. במידה ולא, יש להגדיר `0`
maxDialAttempts	int	ניסיונות חיוג	מספר מקסימלי של נסיונות חיוג שיבוצעו לאותו מספר בהתאם למדיניות חיוגים חוזרים המוגדרת לקמפיין
redialWait	double	המתנה בין נסיונות חיוג - בשניות	זמן המתנה מינימלי בשניות בין נסיונות חיוג לאותו מספר
redialPolicy	enum (string)	מדיניות חיוגים חוזרים. ישנם 3 מצבים - `NONE` `CONGESTIONS` `FAILED`	`NONE` - ללא חיוג חוזר. `CONGESTIONS` - חיוג חוזר במידה ולא זמין. `FAILED` חיוג חוזר במידה ואין מענה
yemotContext	enum (string)	סוג הקמפיין. ישנם 5 מצבים - `SIMPLE` `REPEAT` `MESSAGE` `VOICEMAIL` `BRIDGE`	`SIMPLE` - השמעת הודעה בלבד. `REPEAT` - השמעה חוזרת של ההודעה בהקשה על 1 ואישור קבלת ההודעה בהקשה על 7. `MESSAGE` - שליחת הודעה בדוא"ל בהקשה על 1. `VOICEMAIL` - השארת הודעה בתא קולי בהקשה על 1 שימו לב! באופן זמני התא הקולי בוטל. `BRIDGE` - ניתוב שיחה למענה אנושי
bridgeTo	string	מספר הטלפון לניתוב	במידה והקמפיין מוגדר כניתוב שיחה למענה אנושי
playPrivateMsg	boolean (1/0)	האם להפעיל את האפשרות של מצב הודעה פרטית	במידה וכן, יש להגדיר `1`. במידה ולא, יש להגדיר `0`
removeRequest	enum (string)	אפשרויות הסרה. קיימים 2 מצבים - `SILENT` `WITH_MESSAGE`	`SILENT` - הסרה בלחיצה על 9 ללא הודעה. `WITH_MESSAGE` - הסרה בלחיצה על 9 + הודעה סטנדרטית

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

מאפיין	סוג	הסבר
templates	array	נתוני התבנית המעודכנים - זהה לתיאור התבנית בפקודה `GetTemplates`

eliyahu

העלאת והורדת קבצי שמע לקמפיין

ראה ערך העלאת קובץ כיצד יש להעלות קבצים.
ראה ערך הורדת קובץ כיצד יש להוריד קבצים.

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

הודעת קמפיין קולי

${templateId}.wav

הודעת קמפיין sms

${templateId}.tts

הודעה לפני ניתוב

${templateId}-MoreInfo.wav

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

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

${templateId}-First.wav

הודעה פרטית שמושמעת לטלפון ספציפי

PrivateMsg/${phone}.wav

הודעה ברירת מחדל שמושמעת במידה ואין הודעה ספציפית עבור הטלפון

PrivateMsg/Default.wav

eliyahu

ניהול קבצי קמפיין

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

כדי לנהל את קבצי הקמפיין יש לציין את הנתיבים הבאים בפרמטרים what ו-target

הודעת קמפיין קולי

tpl:${templateId}

הודעת קמפיין sms

tpl:${templateId}:tts

הודעה לפני ניתוב

tpl:${templateId}:MoreInfo

eliyahu

יצירת תבנית קמפיין חדשה

הערה: ההגדרות של הקמפיין החדש יועתקו מקמפיין ברירת המחדל

הפקודה היא - CreateTemplate

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

פרמטר	תיאור
token	טוקן
description	שם הקמפיין

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

מאפיין	סוג	ערך
templateId	int	מזהה התבנית החדשה שנוצרה

eliyahu

מחיקת תבנית קמפיין

הפקודה היא - DeleteTemplate

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

פרמטר	תיאור
token	טוקן
templateId	מזהה תבנית

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

eliyahu

הצגת המספרים שברשימת התפוצה

הפקודה היא - GetTemplateEntries

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

פרמטר	תיאור
token	טוקן
templateId	מזהה תבנית

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

מאפיין	סוג	הסבר
templateId	int	מזהה תבנית
entries	array	מערך אובייקטים (ראה "תבנית אובייקט מספר" להלן)

תבנית אובייקט מספר

מאפיין	סוג	ערך	הערות
rowid	int	מזהה ייחודי של המספר ברשימת התפוצה
index		מיקום המספר ברשימת התפוצה
phone	string	מספר טלפון
blocked	boolean	האם המספר מוגדר כחסום	במידה וכן, יופיע הערך `true`. במידה ולא, יופיע הערך `false`
name	string	שם משוייך	במידה ולא מוגדר, יתקבל הערך `null`
moreinfo	string	מידע נוסף	במידה ולא מוגדר, יתקבל הערך `null`

eliyahu

עדכון מספר בודד ברשימת תפוצה

הפקודה היא - UpdateTemplateEntry

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

פרמטר	תיאור	הערות
token	טוקן	פרמטר חובה
templateId	מזהה תבנית	פרמטר חובה
rowid	מזהה ייחודי של המספר ברשימת התפוצה	אם הפרמטר מושמט והמספר לא קיים, תיווצר שורה חדשה
phone	מספר טלפון	אם המספר קיים ברשימת התפוצה והפרמטר `rowid` הושמט, המספר יעודכן מחדש והערכים `name` ו-`moreinfo` שהיו קיימים יימחקו
name	שם
moreinfo	מידע נוסף
blocked	האם לעדכן כחסום	במידה וכן, יש להגדיר `1`. במידה ולא, יש להגדיר `0`

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

eliyahu

עדכון סטטוס או מחיקה של מספרים מרשימת התפוצה

הפקודה היא - UpdateTemplateEntries

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

פרמטר	תיאור	הערות
token	טוקן	פרמטר חובה
templateId	מזהה תבנית	פרמטר חובה
rowids	מזהה ייחודי של המספרים ברשימת התפוצה	יש להפריד בין המספרים עם מקף `-`
action	איזה פעולה לעשות	ישנם 3 אפשרויות. `block` - חסימה. `unblock` - ביטול חסימה. `delete` - מחיקה

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

eliyahu

מחיקת כל המספרים מרשימת התפוצה

הפקודה היא - ClearTemplateEntries

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

פרמטר	תיאור
token	טוקן
templateId	מזהה תבנית

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

eliyahu

העלאת קובץ טקסט והפיכתו לרשימת טלפונים לתבנית קמפיין
הפקודה היא - UploadPhoneList
הפרמטרים הנדרשים:

פרמטר	תיאור	הערות
token	טוקן	חובה
templateId	מזהה תבנית	חובה
data	קובץ רשימת הטלפונים כמחרוזת	חובה
nameColumns	מספר העמודות של 'שם'. כל עמודות הטקסט האחרות עוברות ל'מידע נוסף '	ברירת מחדל 1
defaultPrefix	קידומת מספר ברירת מחדל למספרים בני 7 ספרות.הערכים המותרים הם: 02,03,04,08,09,077,072,073.	רשות
delimiter	תו המפריד בין עמודות (עבור עמודות המופרדים ב טאב כיתבו "TAB"	ברירת מחדל ","
updateType	מגדיר את סוג העדכון: UPDATE = עדכן רשומות קיימות והוסף חדשות, NEW = הסר את כל הרשומות הקיימות והוסף חדש, REMOVE = הסר רשומות	ברירת מחדל UPDATE
blocked	1 = יקבע את סטטוס הרשומות שהועלה ל'חסום '.	ברירת מחדל 0 כלומר לא מגדיר כחסום

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

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

מאפיין	סוג	הסבר
message	string	"ok" - פירושו שההעלאה עובדה כהלכה
templateId	int	מזהה התבנית שעודכן
totalParsed	int	המספר הכולל של מספרים שהתקבלו
rejectedRecords	Array	מערך המתאר את הרשומות שנדחו (ראה להלן פירוט)
totalInserted	int	המספר הכולל של מספרים שהוכנסו בהצלחה
totalUpdated	int	המספר הכולל של המספרים שעודכנו
totalRemoved	int	המספר הכולל של המספרים שהוסרו

אם מספרים מסוימים נדחו משום מה, rejectedRecords יכיל מערך של אובייקטים בפורמט הבא:

מאפיין	סוג	הסבר
phone	string	מספר הטלפון
name	string	עמודת שם
moreinfo	string	עמודת מידע נוסף
blocked	bool	סטטוס חסום
errorState	enum	`DUPLICATE` = המספר כפול, `INVALID` = המספר לא חוקי (אסור בקמפיינים)
originalRowNumber	int	מספר השורה בו זוהתה השגיאה

eliyahu

הפעלת קמפיין

מאפשר להפעיל קמפיין על בסיס תבנית קיימת במערכת

הפקודה היא RunCampaign

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

פרמטר	תיאור	הערות
token	טוקן	חובה
templateId	מזהה תבנית כפי שהתקבל בקריאות `GetTemplates` `CreateTemplate`	רשות; אם לא צוין, המערכת תשתמש בתבנית ברירת המחדל
callerId	זיהוי יוצא, מתקבל בקריאת `GetApprovedCallerIDs`	רשות; אם לא צוין, המערכת תשתמש בזיהוי שמוגדר בתבנית
phones	טלפונים לחיוג	רשות; ראה להלן פורמט מספרים לשליחה; אם לא צוין, המערכת תשתמש במספרים שנמצאים בתבנית.
ttsMode	השמעת הודעות אישיות בהקראה ממוחשבת - TTS	ראה הסבר להלן
withSMS	קמפיין משולב sms	ראה הסבר להלן

פורמט מספרים לשליחה

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

phones=0772222770:0773137770

בדוגמה, המערכת תחייג למספרים 0772222770 0773137770.

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

{
	"0773137770":{
		"name":"שם",
		"moreinfo":"מידע נוסף",
		"blocked":true
	},
	"0772222770":{
		"name":"ימות המשיח",
		"text":"עתיד התקשורת כבר כאן"
	}
}

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

שדה name משמש עבור השם.
שדה moreinfo משמש עבור מידע נוסף.
שדה text משמש עבור טקסט להודעה אישית (sms או tts; ראה להלן).
שדה blocked מציין אם המספר חסום או לא (true=חסום, false=פעיל; ברירת מחדל היא פעיל).

השמעת הודעות אישיות בהקראה ממוחשבת - TTS

ניתן להגדיר שהקמפיין יכיל הודעה אישית אשר תושמע לנמען בהקראה ממוחשבת (TTS - Text To Speech).
לצורך כך יש לשלוח את הפרמטר ttsMode=1, במקרה כזה, המערכת תשמיע תחילה את הודעת הקמפיין הכללית ולאחר מכן את הטקסט האישי.
שימו לב! במידה והקמפיין נשלח למספרי הטלפון שבתבנית (קרי, לא שלחתם פרמטר phones) אזי הטקסט להשמעה יהיה מה שמופיע על המספר בשדה moreinfo.
במידה והקמפיין נשלח למספרי טלפון ספציפיים (שציינתם בפרמטר phones) אזי הטקסט להשמעה יהיה מה שמופיע בשדה text וכמו שצוין למעלה.

קמפיין משולב sms

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

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

מאפיינים עיקריים

מאפיין	משמעות	סוג	דוגמה
templateId	מזהה תבנית עליה מתבסס הקמפיין	int	1117319
campaignId	מזהה הקמפיין (משמש עבור מעקב אחר הקמפיין ועוד)	string	0772222770-1117319-2025-01-21-15-11-18-347-API
entriesCount	סך הכל ערכים (מספרים) ברשימה	int	333
pending	סך הכל מספרים לחיוג	int	300
blocked	סך הכל מספרים חסומים	int	33
estimatedPrice	עלות משוערת ביחידות	double	333.0
customerUnits	כמות יחידות במערכת	double	10000.12121212
smsCount	כמות sms	double	0.0
smsPrice	עלות sms	double	0.0

שגיאות אפשריות

קוד הודעה	הודעה	הסבר
100	תבנית לא חוקית	ערך `templateId` אינו חוקי (התבנית אינה קיימת במערכת).
101	הקמפיין לא מוגדר כראוי	הקמפיין לא הוגדר נכון (רשימת הטלפונים ריקה, אין הודעה תקינה וכו').
102	אין טלפונים תקינים	כל המספרים שסופקו בפרמטר `phones` אינם תקינים.
103	יחידות לא מספיקות	יתרת היחידות במערכת אינה מספיקה עבור הקמפיין הנדרש.
104	`isKodesh` is true	ניסיון להפעיל קמפיין בשבת או ביום טוב.
105	שגיאה כללית	אירעה שגיאת מערכת והקמפיין לא יכול להתחיל.
120	CallerId אינו מורשה	המספר המבוקש ב-`callerId` אינו מורשה לשימוש עבור הלקוח.

eliyahu

קבלת מצב קמפיין

מאפשר לבדוק את הסטטוס הנוכחי של קמפיין כפי שהתקבל בקריאת RunCampaign

הפקודה היא GetCampaignStatus

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

פרמטר	חובה/אופציונלי	תיאור
`token`	חובה	טוקן
`campaignId`	חובה	מזהה הקמפיין, כפי שהתקבל בקריאת `RunCampaign`
`entries`	אופציונלי	הצגת רשומות בקמפיין (מספרי טלפון) ראו להלן "הצגת רשומות בקמפיין". במידה ולא צוין, ברירת המחדל היא שלא מציג את מצב הרשומות בקמפיין אלא רק את המצב הכללי של הקמפיין.
`range`	אופציונלי	טווח ערכים להצגה (מקסימום/מינימום) ראו להלן "הגדרת טווח להצגה"

הצגת רשומות בקמפיין

סוגי הערכים האפשריים בפרמטר entries

ערך	הסבר
all	הכל
pending	בהמתנה לחיוג
blocked	חסומים
done	בוצע
accepted	אישרו מסירה
failed	נכשלו
no_answer	אין מענה
busy	תפוס
amd	מענה תא קולי
ringing	בחיוג
up	בשיחה
bridged	מנותבים
remove_request	בקשה להסרה
redial	ממתינים לחיוג חוזר
canceled	בוטל
error	שגיאה כללית

הגדרת טווח להצגה

בפרמטר range יש להגדיר את טווח הרשומות להצגה.
הפורמט הוא [min]:[max].
לדוגמה 1:100 עבור 100 הרשומות הראשונות, או : עבור כל הרשומות.
ברירת מחדל מחזיר 10,000 ערכים ראשונים.

פרמטרים בתשובה במצב הצלחה

מבנה התגובה

{
    "responseStatus": "OK",
    "campaign": {
        "campaignId": "0772222770-1117319-2025-01-22-10-07-54-414-API",
        "campaignStatus": "RUNNING",
        "templateId": 1117319,
        "who": "0.0.0.0",
        "callerId": "0772222770",
        "blockedEntries": 0,
        "pendingEntries": 0,
        "activeEntries": 1,
        "bridgedEntries": 0,
        "redialEntries": 0,
        "doneEntries": 0,
        "failedEntries": 0,
        "totalEntries": 1,
        "totalDialed": 3,
        "totalSuccessful": 1,
        "totalBridged": 0,
        "totalFailed": 2,
        "totalIncoming": 0,
        "totalIncomingBridged": 0,
        "maxActiveChannels": 100,
        "maxBridgedChannels": 0,
        "maxDialAttempts": 3,
        "redialWait": 10.0,
        "redialPolicy": "FAILED",
        "vmDetect": false,
        "filterEnabled": false,
        "playPrivateMsg": false,
        "runTime": 150.306,
        "currentPrice": 1.0,
        "paused": false,
        "entries": [
            {
                "phone": "0773137770",
                "name": null,
                "moreinfo": "זוהי הודעת בדיקה",
                "entryStatus": "up",
                "duration": 3680,
                "bridgedDuration": null,
                "bridged": false,
                "startTime": "2025-01-22 10:10:14",
                "currentPrice": 1.0,
                "redials": [
                    {
                        "entryStatus": "no_answer",
                        "duration": null,
                        "bridgedDuration": null,
                        "bridged": false,
                        "startTime": "2025-01-22 10:07:54"
                    },
                    {
                        "entryStatus": "no_answer",
                        "duration": null,
                        "bridgedDuration": null,
                        "bridged": false,
                        "startTime": "2025-01-22 10:09:04"
                    }
                ]
            }
        ]
    },
    "yemotAPIVersion": 6
}

מבנה תגובת הקמפיין

מאפיין	סוג	תיאור
`campaignId`	מחרוזת	מזהה הקמפיין.
`campaignStatus`	enum	סטטוס הקמפיין: אחד מ-`STOPPED`, `RUNNING`, `PAUSED`, `STOPPING` `FINISHED`.
`templateId`	מספר	מזהה התבנית שעל בסיסה פועל הקמפיין.
`who`	מחרוזת	כתובת IP או מספר הטלפון שהפעיל את הקמפיין.
`callerId`	מחרוזת	מספר טלפון היוצא עבור הקמפיין.
`blockedEntries`	מספר	מספר הרשומות החסומות.
`pendingEntries`	מספר	מספר הרשומות הממתינות.
`activeEntries`	מספר	מספר הרשומות הפעילות כעת.
`bridgedEntries`	מספר	מספר הרשומות שחוברו בהצלחה.
`redialEntries`	מספר	מספר הרשומות המחכות לחיוג חוזר.
`doneEntries`	מספר	מספר הרשומות שהושלמו בהצלחה.
`failedEntries`	מספר	מספר הרשומות שנכשלו.
`totalEntries`	מספר	סך כל הרשומות בקמפיין.
`totalDialed`	מספר	סך כל החיוגים (כולל חיוגים חוזרים).
`totalSuccessful`	מספר	סך השיחות המוצלחות.
`totalBridged`	מספר	סך כל השיחות שחוברו.
`totalFailed`	מספר	סך כל השיחות שנכשלו.
`totalIncoming`	מספר	סך השיחות הנכנסות במהלך הקמפיין.
`totalIncomingBridged`	מספר	סך השיחות הנכנסות שחוברו.
`maxActiveChannels`	מספר	המספר המרבי של שיחות פעילות מותרות בקמפיין.
`maxBridgedChannels`	מספר	המספר המרבי של שיחות מחוברות מותרות בקמפיין.
`maxDialAttempts`	מספר	מספר הניסיונות המרבי לחיוג חוזר.
`redialWait`	מספר	זמן ההמתנה המינימלי בין ניסיונות חיוג חוזר (בשניות).
`redialPolicy`	enum	מדיניות החיוג החוזר: `NONE`, `CONGESTIONS`, או `FAILED`.
`vmDetect`	בוליאני	האם זיהוי תא קולי מופעל.
`playPrivateMsg`	בוליאני	האם מצב הודעה פרטית מופעל.
`runTime`	מספר	זמן הריצה הכולל של הקמפיין (בשניות).
`currentPrice`	מספר	המחיר הנוכחי שנגבה עבור הקמפיין (ביחידות).
`paused`	בוליאני	האם הקמפיין במצב מושהה.

שגיאות אפשריות

קוד הודעה	הודעה	הסבר
106	קמפיין לא נמצא	`campaignId` לא נמצא עבור המשתמש.

הערות

כאשר נכלל פרמטר entries, התגובה תכיל את שדה entries עם מידע מפורט על הרשומות (ראו מבנה JSON בתיאור המפורט).

   "entries": [
     {
       "phone": string,
       "name": string|null,
       "moreinfo": string|null,
       "entryStatus": entry_status_enum,
       "duration": time_ms|null,
       "bridgedDuration": time_ms|null,
       "bridged": true|false,
       "startTime": sql_time|null,
       "redials": [
         {
           "entryStatus": entry_status_enum,
           "duration": null,
           "bridgedDuration": null,
           "bridged": true|false,
           "startTime": sql_time|null
     },
     {
       "phone": "0501234567",                       // מספר הטלפון של הנמען
       "name": "Yosef",                             // שם (אם קיים)
       "moreinfo": "Jerusalem",                          // מידע נוסף (אם קיים)
       "entryStatus": "bridged",                    // סטטוס נוכחי של הרשומה (למשל: bridged, done, no_answer)
       "duration": 5200,                            // משך השיחה הכולל במילישניות
       "bridgedDuration": 4100,                     // משך זמן ניתוב שיחה
       "bridged": true,                             // האם השיחה מנותבת
       "startTime": "2025-05-25 10:32:00",          // מתי התחילה השיחה (זמן החיוג)
       "redials": [                                 // ניסיונות חוזרים (אם היו)
         {
           "entryStatus": "busy",                // סטטוס ניסיון חוזר זה
           "duration": null,                        // משך שיחה בניסיון זה (null כי לא נענתה)
           "bridgedDuration": null,                 // משך זמן ניתוב שיחה
           "bridged": false,                        // האם בוצע ניתוב שיחה
           "startTime": "2025-05-25 10:29:00"       // זמן תחילת ניסיון החיוג הזה
         },
         {
           "entryStatus": "no_answer",              // ניסיון חוזר נוסף - לא נענה
           "duration": null,                       // 
           "bridgedDuration": 0,                    // 
           "bridged": false,                        //
           "startTime": "2025-05-25 10:30:30"       //
         }
       ]
     },
     {
       "phone": "0521234567",                       // מספר טלפון נוסף
       "name": null,                                // לא סופק שם
       "moreinfo": null,               // לא סופק
       "entryStatus": "done",                       // הסתיים בהצלחה
       "duration": 8000,                            // משך שיחה
       "bridgedDuration": 0,                        // 
       "bridged": false,                            // 
       "startTime": "2025-05-25 10:35:00",          // מתי בוצעה השיחה
       "redials": []                                // לא היו ניסיונות חוזרים
     }
   ]

eliyahu

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

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)

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

העלאת קובץ

מתודת פניה

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

פיצול קובץ לחלקים נפרדים והעלאה לשרת

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

הפעלת קמפיין

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

פורמט מספרים לשליחה

השמעת הודעות אישיות בהקראה ממוחשבת - TTS

קמפיין משולב sms

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

שגיאות אפשריות

קבלת מצב קמפיין

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

הצגת רשומות בקמפיין

הגדרת טווח להצגה

פרמטרים בתשובה במצב הצלחה

מבנה התגובה

מבנה תגובת הקמפיין

שגיאות אפשריות

הערות

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

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

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

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

מבנה תגובה

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

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

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

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

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

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

מבנה תגובה

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

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

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

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

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

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

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

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

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