API - גישת מפתחים למערכות
-
קבלת רשימת שיחות הפעילות במערכת
הפקודה היא -
GetIncomingCalls
הפרמטרים הנדרשים:
פרמטר תיאור/הערות token טוקן מאפייני תגובת השרת:
מאפיין סוג הסבר calls array מערך אובייקטים (ראה "תבנית אובייקט שיחה" להלן) callsCount int מספר כולל של שיחות במערכת תבנית אובייקט שיחה
מאפיין ערך did מספר מחוייג callerIdNum מספר מחייג (כולל ערכים של ID
val_name
במידה וקיים במערכת)duration משך זמן שיחה - בשניות transferFrom האם השיחה הועברה ממערכת אחרת. במידה וכן יופיע הערך מועבר
במידה ולא יפיע הערךnull
id מזהה ייחודי לאורך השיחה path מספר שלוחה (כולל תיאור שלוחה ומספר קובץ במידה וקיים) -
העלאת קובץ
הפקודה היא -
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 -
הורדת קובץ
הפקודה היא -
DownloadFile
הפרמטרים הנדרשים:
פרמטר תיאור הערות token טוקן path שם הקובץ להורדה בהמשך יפורט איך לציין את הנתיב של כל קובץ מאפייני תגובת השרת:
במידה והקובץ קיים - התגובה תכיל את את תוכן הקובץ המבוקש.
במידה והקובץ לא קיים או שהתרחשה שגיאה - התגובה תהיה HTTP 404 Not Found.הערה: שימו לב שהתגובה לבקשה זו אינה JSON (בשונה משאר הבקשות)
-
קבלת מצב כל תבניות הקמפיינים
הפקודה היא -
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 + הודעה סטנדרטית -
עדכון תבנית קמפיין
הערה: רק ההגדרות שסופקו יעודכנו, ההגדרות שהושמטו לא ישתנו.
הפקודה היא
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
-
העלאת והורדת קבצי שמע לקמפיין
ראה ערך העלאת קובץ כיצד יש להעלות קבצים.
ראה ערך הורדת קובץ כיצד יש להוריד קבצים.כדי להעלות ולהוריד קבצי שמע יש לציין את הנתיבים הבאים:
הודעת קמפיין קולי
${templateId}.wav
הודעת קמפיין sms
${templateId}.tts
הודעה לפני ניתוב
${templateId}-MoreInfo.wav
כאשר האפשרות של מצב הודעה פרטית מופעלת, ישנם קבצים נוספים המשמשים להפעלת הקמפיין:
ההודעה שמושמעת לכולם לפני ההודעה הפרטית
${templateId}-First.wav
הודעה פרטית שמושמעת לטלפון ספציפי
PrivateMsg/${phone}.wav
הודעה ברירת מחדל שמושמעת במידה ואין הודעה ספציפית עבור הטלפון
PrivateMsg/Default.wav
-
ניהול קבצי קמפיין
ראה ערכים ניהול קבצים, הצגת תוכן קובץ טקסט, העלאת טקסט לקובץ למידע אודות הפרמטרים הדרושים.
כדי לנהל את קבצי הקמפיין יש לציין את הנתיבים הבאים בפרמטרים
what
ו-target
הודעת קמפיין קולי
tpl:${templateId}
הודעת קמפיין sms
tpl:${templateId}:tts
הודעה לפני ניתוב
tpl:${templateId}:MoreInfo
-
יצירת תבנית קמפיין חדשה
הערה: ההגדרות של הקמפיין החדש יועתקו מקמפיין ברירת המחדל
הפקודה היא -
CreateTemplate
הפרמטרים הנדרשים
פרמטר תיאור token טוקן description שם הקמפיין מאפייני תגובת השרת
מאפיין סוג ערך templateId int מזהה התבנית החדשה שנוצרה -
מחיקת תבנית קמפיין
הפקודה היא -
DeleteTemplate
הפרמטרים הנדרשים
פרמטר תיאור token טוקן templateId מזהה תבנית אין מאפיינים מיוחדים בתגובת השרת
-
הצגת המספרים שברשימת התפוצה
הפקודה היא -
GetTemplateEntries
הפרמטרים הנדרשים
פרמטר תיאור token טוקן templateId מזהה תבנית מאפייני תגובת השרת
מאפיין סוג הסבר templateId int מזהה תבנית entries array מערך אובייקטים (ראה "תבנית אובייקט מספר" להלן) תבנית אובייקט מספר
מאפיין סוג ערך הערות rowid int מזהה ייחודי של המספר ברשימת התפוצה index מיקום המספר ברשימת התפוצה phone string מספר טלפון blocked boolean האם המספר מוגדר כחסום במידה וכן, יופיע הערך true
. במידה ולא, יופיע הערךfalse
name string שם משוייך במידה ולא מוגדר, יתקבל הערך null
moreinfo string מידע נוסף במידה ולא מוגדר, יתקבל הערך null
-
עדכון מספר בודד ברשימת תפוצה
הפקודה היא -
UpdateTemplateEntry
הפרמטרים הנדרשים
פרמטר תיאור הערות token טוקן פרמטר חובה templateId מזהה תבנית פרמטר חובה rowid מזהה ייחודי של המספר ברשימת התפוצה אם הפרמטר מושמט והמספר לא קיים, תיווצר שורה חדשה phone מספר טלפון אם המספר קיים ברשימת התפוצה והפרמטר rowid
הושמט, המספר יעודכן מחדש והערכיםname
ו-moreinfo
שהיו קיימים יימחקוname שם moreinfo מידע נוסף blocked האם לעדכן כחסום במידה וכן, יש להגדיר 1
. במידה ולא, יש להגדיר0
אין מאפיינים מיוחדים בתגובת השרת
-
עדכון סטטוס או מחיקה של מספרים מרשימת התפוצה
הפקודה היא -
UpdateTemplateEntries
הפרמטרים הנדרשים
פרמטר תיאור הערות token טוקן פרמטר חובה templateId מזהה תבנית פרמטר חובה rowids מזהה ייחודי של המספרים ברשימת התפוצה יש להפריד בין המספרים עם מקף -
action איזה פעולה לעשות ישנם 3 אפשרויות. block
- חסימה.unblock
- ביטול חסימה.delete
- מחיקהאין מאפיינים מיוחדים בתגובת השרת
-
מחיקת כל המספרים מרשימת התפוצה
הפקודה היא -
ClearTemplateEntries
הפרמטרים הנדרשים
פרמטר תיאור token טוקן templateId מזהה תבנית אין מאפיינים מיוחדים בתגובת השרת
-
העלאת קובץ טקסט והפיכתו לרשימת טלפונים לתבנית קמפיין
הפקודה היא -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 מספר השורה בו זוהתה השגיאה -
הפעלת קמפיין
מאפשר להפעיל קמפיין על בסיס תבנית קיימת במערכת
הפקודה היא
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
אינו מורשה לשימוש עבור הלקוח. - שדה
-
קבלת מצב קמפיין
מאפשר לבדוק את הסטטוס הנוכחי של קמפיין כפי שהתקבל בקריאת
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": [] // לא היו ניסיונות חוזרים } ]
- כאשר נכלל פרמטר
-
הורדת דו"ח קמפיין-DownloadCampaignReport
-
קבלת קמפיינים פעילים-GetActiveCampaigns
-
ביצוע פעולות בקמפיין בזמן אמת
הפקודה היא
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
)
-
יצירת קמפיין מתוזמן
הפקודה היא -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 שעה:דקה