API - גישת מפתחים למערכות
-
העברת יחידות
העברת יחידות למערכת אחרתהפקודה היא -
TransferUnits
הפרמטרים הנדרשים:
פרמטר תיאור/הערות token טוקן destination מספר מערכת להעברה amount כמות יחידות להעברה מאפייני תגובת השרת במקרה שהעברה בוצעה בהצלחה:
מאפיין סוג ערך destination string מערכת היעד אליה בוצעה ההעברה amount double הסכום שהועבר newBalance double יתרת היחידות במערכת המקור לאחר ביצוע ההעברה במקרה של שגיאה בביצוע ההעברה ההודעות והקודים האפשריים הם כדלקמן:
messageCode message הסבר 111 Bad destination יעד להעברה לא חוקי: המערכת אינה קיימת או שאינה מורשית לקבל יחידות ממערכת זו 112 Bad amount סכום היחידות להעברה אינו חוקי 113 Not enough balance יתרת היחידות שבמערכת אינה מאפשרת את ביצוע ההעברה -
קבלת רשימת שיחות הפעילות במערכת
הפקודה היא -
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
הערה-פקודה זו יוצרת קמפיין המבוסס על אחד מתבניות הקמפיין של הלקוח ואם הכל כראוי הקמפיין מופעל וכחלק מתגובת השרת תקבלוcampaignId
שעם זה תוכלו לעקוב אחרי סטטוס הקמפיין וכן להוציא דוח על הקמפיין ועוד.הפרמטרים הנדרשים
פרמטר תיאור הערות token טוקן חובה templateId מזהה תבנית חובה phones רשימת טלפונים חלופית לשליחת ההודעה, כאשר המספרים מופרדים ב :
רשות callerId זיהוי יוצא רשות -
מצב הקמפיין-GetCampaignStatus
-
הורדת דו"ח קמפיין-DownloadCampaignReport
-
קבלת קמפיינים פעילים-GetActiveCampaigns
-
ביצוע פעולות בקמפיינים פעילים-CampaignAction