API - גישת מפתחים למערכות
-
קבלת תנועות יחידות סמסים
הפקודה היא -
GetCustomerSmsTransactions
הפרמטרים הנדרשים
פרמטר תיאור סוג הערות / דוגמא token טוקן string מביא 2000 תנועות אחרונות
מאפיין סוג הסבר דוגמא responseStatus string סטטוס הפעולה OK
yAfastVersion string גירסת מערכת rows array מערך תנועות פירוט איבר במערך:
שם תיאור transactionTime זמן תנועה amount סכום תנועה ביחידות description תיאור החיוב newBalance יתרת יחידות עדכנית בביצוע הפעולה expireDate תאריך תפוגה עדכני בביצוע הפעולה who מבצע הפעולה -
-
חשבונות SIP
תיעוד api הנוגע לחשבונות SIP
כל השירותים שקשורים לSIP קיימים רק בשרתים תומכים.
בכל פניה לשרת שלא תומך תתקבל תגובה:{ responseStatus: "ERROR", message: "שרת זה אינו תומך במערכת SIP", yAfastVersion: "any" }
מאפיינים
לכל חשבון SIP במערכת יש מספר מאפיינים
- מספר החשבון במערכת (למשל
1
2
וכן הלאה) - שם המשתמש להתחברות
בדרך כלל שם המשתמש מורכב ממספר המערכת ומספר החשבון.
למשל0772222770=2
זהו שם המשתמש של חשבון 2 במערכת 0772222770 - מספר שלוחה - כל מספר שנמצא בטווח מ-200 ועד 10,000
מספר שלוחה הינו מאפיין הנתון לבחירה של מנהל המערכת וניתן לשנות אותו בכל עת.
הדבר משמש עבור חיוגים פנימיים בין החשבונות. (למשל כדי לחייג משלוחה 200 לשלוחה 201 יש לחייג למספר "201" במקרה כזה מה שיופיע על הצג אצל מקבל השיחה זה "200") - סיסמת התחברות
- פרוטוקול SIP להתקשרות (נכון לעכשיו התמיכה היא בפרוטוקולים UDP WSS)
יצירת חשבון
הפקודה היא -
CreateSipAccount
הפרמטרים הנדרשים
פרמטר תיאור סוג token טוקן string extNumber אפשר לציין מספר שלוחה. לא חובה. מספר שלוחה יכול להיות בין 200 ל10000. int מענה בעת הצלחה
מאפיין סוג הסבר דוגמא responseStatus string סטטוס הפעולה OK
accountID string שם המשתמש שם החשבון שנוצר. accountNumber int מספר החשבון במערכת (לא מספר שלוחה) PASS string הסיסמה של החשבון להתחברות
קבלת רשימת החשבונות במערכת
הפקודה היא -
GetSipAccountsInCustomer
הפרמטרים הנדרשים
פרמטר תיאור סוג token טוקן string מענה בעת הצלחה
מאפיין סוג הסבר דוגמא responseStatus string סטטוס הפעולה OK
accounts array מערך חשבונות accountLimit int כמות החשבונות שהלקוח יכול ליצור במערכת 6 מערך החשבונות
מאפיין סוג הסבר דוגמא id string שם המשתמש של החשבון accountNumber int מספר חשבון במערכת customerExtension int מספר שלוחה, אם מוגדר transport string סוג התקשורת המותרת בחשבון. transport-udp
\transport-wss
callerid string מערכת לחיוב יחידות specialCallerID string זיהוי מיוחד להוצאת שיחות password string סיסמה להתחברות בsip created_date string תאריך יצירה של החשבון
שינוי התעבורה המותרת בחשבון - UDP \ WSS
מאפשר לשנות את סוג התעבורה המותרת. תיתן להתחבר לחשבונות הsip עם תקשורת של UDP או עם חיבור לwebsocet של שרת הסיפ, למשל כדי להטמיע את השירות בדפדפן על ידי פרוטוקול webRTC למשל בשימוש עם ספריית jssip.
הכתובת של שרת הsip להתחברות עם websocket היא
wss://sip.yemot.co.il:8089/ws
, החיבור הוא על בחיבור מאובטח בלבד (wss://
).הפקודה היא -
SipToWss
|SipToUdp
הפרמטרים הנדרשים
פרמטר תיאור סוג token טוקן string accountNumber מספר החשבון, אם לא צוין מוגדר על החשבון הראשון int מענה בעת הצלחה
מאפיין סוג הסבר דוגמא responseStatus string סטטוס הפעולה OK
הגדרת זיהוי יוצא קבוע
מאפשר להגדיר את הזיהוי היוצא של החשבון
מיותר לציין, שזה יעבוד רק אם המספר מאושר במערכת או שהוא מספר משנה + מספר ישראלי תקין.
הפקודה היא -
EditCallerIdInSipAccount
הפרמטרים הנדרשים
פרמטר תיאור סוג token טוקן string accountNumber מספר חשבון int callerId זיהוי יוצא string מענה בעת הצלחה
מאפיין סוג הסבר דוגמא responseStatus string סטטוס הפעולה OK
ניתן לבקש זיהוי יוצא מיוחד גם בעת השיחה עצמה ללא שינוי בהגדרות החשבון על ידי צירוף של header בשם
X-YemotCallerId
ל INTIVE של השיחה היוצאת.
במקרה של סתירה בין המופיע בהגדרות החשבון להגדרות השיחה הנוכחית, הגדרות השיחה יגברו.
מחיקת חשבון
הפקודה היא -
DeleteSipAccount
הפרמטרים הנדרשים
פרמטר תיאור סוג token טוקן string accountNumber מספר החשבון למחיקה כמספר, או מערך של מספרי חשבונות sip למחיקה. int / array מענה בעת הצלחה
מאפיין סוג הסבר דוגמא responseStatus string סטטוס הפעולה OK
affected_rows int מספר חשבונות הsip שנמחקו
ניהול מספר שלוחה
הפקודה היא -
SipExtensionManagement
הפרמטרים הנדרשים
פרמטר תיאור סוג token טוקן string SipExtensionManagement פעולה לביצוע. Get
עבור קבלת מספר השלוחה ללא ביצוע שינוי.Set
עבור שינוי או הגדרה של מספר שלוחה.string accountNumber מספר חשבון ברירת מחדל החשבון הראשון extNumber מספר שלוחה. לא חובה בפעולת Get, אם לא צויין בפעולת Set מספר השלוחה ימחק. מענה בעת הצלחה
מאפיין סוג הסבר דוגמא responseStatus string סטטוס הפעולה OK
extNumber int מספר השלוחה. במידה שמדובר בפעולת Set זה יכיל את המספר שלוחה החדש.
מידע טכני נוסף על קבלת שיחות לחשבון SIP
ב
INVITE
שמגיע מימות המשיח ללקוח בכל שיחה יש 2 header שנוספים בכל שיחה.X-Yemot-Path
= מספר השלוחה שממנה הגיע השיחה.
X-Yemot-CallID
= מזהה השיחה. ניתן להשוות את זה עם מודול תור בשימוש עם queue_api_send=yes, שם זה מגיע לשרת בערךYemotCallID
. - מספר החשבון במערכת (למשל
-
שינוי שימוש (usage) של מספר משנה
הפקודה היא -
SetSecondaryDidUsageDescription
הפרמטרים הנדרשים
פרמטר תיאור סוג token טוקן string secondaryDidId מזהה המספר משנה. מתקבל במערך המספרים המשניים ב GetCustomerData int newUsage שימוש חדש, כפי המוסבר מטה. string ניתן לשנות שימוש של מספר משנה לאחד משתי הקידומות האלה:
sip:[0-9] goto:/[A-Za-z0-9א-ת/]
בנוסף, עם השימוש הישן הוא לא משהוא שאפשר לבחור אותו לא יתאפשר בכלל לשנות את השימוש.
הסבר על שימוש sip:X:
מאפשר לשייך מספר משנה למספר חשבון sip במערכת, כך שבחיוג ישיר למספר המשנה יגיעו לחשבון הsip. למשל, כדי לשייך לחשבון מספר 5 של המערכת יש לכתוב
sip:5
. גם ציון מספר שלוחה אפשרי ויחייג למספר השלוחה. האפשרות תעבור רק בשרתים תומכי sip.הסבר על שימוש goto:/:
מאפשר לשייך מספר משנה לשלוחה ספציפית במערכת - למשל, כדי לשייך לשלוחה
1/20/11
יש לכתובgoto:/1/20/11
.
מענה בעת הצלחה:
מאפיין סוג הסבר דוגמא responseStatus string סטטוס הפעולה OK
status bool הצלחה ture -
קבלת מידע כללי על תיקיה (שלוחה)
הפקודה היא
GetIVR2DirStats
הפרמטרים הנדרשים
פרמטר תיאור הערות token טוקן חובה path נתיב תיקייה חובה. לדוגמה: /
עבור שלוחה ראשית.1
עבור שלוחה 1ext/1
עבור שלוחהext/1
מאפייני תגובת השרת
מאפיין סוג הסבר type string סוג השלוחה thisPath string נתיב תיקייה נוכחית parentPath string נתיב תיקיית אב dirsCount int כמות תיקיות בשלוחה filesCount int כמות קבצים בשלוחה contentFilesCount int כמות קבצי שמע בשלוחה minFile object מידע על קובץ השמע הנמוך בשלוחה maxFile object מידע על קובץ השמע הגבוה בשלוחה מאפייני קובץ שמגיעים באובייקטים
minFile
/maxFile
מאפיין סוג הסבר exists boolean האם התיקייה/קובץ קיימים name string שם התיקייה/קובץ uniqueId string מזהה ייחודי לתיקייה/קובץ what string נתיב תיקייה/קובץ fileType string סוג תיקייה/קובץ size int גודל קובץ (בבתים) mtime string תאריך שינוי אחרון duration אורך (בדקות) durationStr string אורך בפורמט mm:ss customerDid string מספר מערכת בה נוצר הקובץ meta string אובייקט המכיל מיגע נוסף על הקובץ date string זמן יצירת קובץ dd/mm/yyyy hh:mm source string מקור הקובץ phone string טלפון יוצר הקובץ ip string כתובת IP של מעלה הקובץ -
-
-
-
-
-
ניהול תור אונליין
שימו לב, ניהול התור אונליין אפשרי לשיחות ממתינות בתור בלבד.
את הממתינים בתור מקבלים בשירות GetQueueRealTime - לכל ממתין יש מזהה שיחה.
הפקודה היא -
QueueManagement
שימו לב, שירות זה מקבל מערך. לצורך זה ניתן לפנות אליו רק בPOST עם json בbody.
בכל פניה יש לצרף:
פרמטר תיאור סוג token טוקן string queuePath מיקום התור. זהה לצורה שבה שולחים שם תור ב GetQueueRealTime string callIds מערך מזהי שיחות תור (מתקבל גם ב GetQueueRealTime במערך הממתינים array action פעולה לביצוע string moreData הוראות נוספות - רשות string פעולות:
הוצאה מהתור - kick
הפעולה היא -
kick
הפרמטרים הנדרשים בנוסף
פרמטר תיאור סוג moreData ניתן לציין בפרמטר זה שלוחה להעברת המשתמש היוצא. הפרמטר רשות. כדי להעביר למשל לשלוחה 1 יש לציין: GOTO:/1
string מענה בעת הצלחה
מאפיין סוג הסבר דוגמא responseStatus string סטטוס הפעולה OK
status object סטטוס פעולות, באופן שהkey הוא מזהה השיחה והvalue הוא הסטטוס. דוגמא לתגובה מלאה:
{ "responseStatus": "OK", "yAfastVersion": "6.6.20", "status": { "805c3b221d4b76bb53769aac9e2c57c1": "Call not found", "f6657b78a2f35d6d04dd203400828362": "OK" } }
השהיית נציג / החזרת נציג לפעילות
בפעולת אלה לא צריך לשלוח
callIds
, אלא רקqueuePath
הפעולה היא -pause
- השהיית נציג
הפעולה היא -unpause
- ביטול נציג מהשהייההפרמטרים הנדרשים בנוסף
פרמטר תיאור סוג agent שם הנציג. זהה לשם שמגיע ב GetQueueRealTime['members'][?]['agent']
string מענה בעת הצלחה
מאפיין סוג הסבר דוגמא responseStatus string סטטוס הפעולה OK
-
-
-
-
ניהול פרסומפון
הפקודה היא -
PirsumPhoneManagement
בכל פניה יש לצרף:
פרמטר תיאור סוג token טוקן string action פעולה לביצוע string פעולות:
קבלת סטטוס רישום לשירות - GetRegistrationStatus
הפעולה היא -
GetRegistrationStatus
מענה בעת הצלחה
מאפיין סוג הסבר דוגמא responseStatus string סטטוס הפעולה OK
registrationStatus boolean האם רשום או לא true
רישום לשירות - Registration
הפעולה היא -
Registration
מענה בעת הצלחה
מאפיין סוג הסבר דוגמא responseStatus string סטטוס הפעולה OK
results string הודעת הצלחה OK
הסרה מהשירות - UnRegistration
הפעולה היא -
UnRegistration
מענה בעת הצלחה
מאפיין סוג הסבר דוגמא responseStatus string סטטוס הפעולה OK
results string הודעת הצלחה OK -
שמואל
-
-
שמואל
-
הפעלת קמפיין הנכנס לשלוחה במערכת
השירות מאפשר להפעיל קמפיין לרשימת מספרים - שבעת המענה לשיחה השיחה תיכנס למערכת לשלוחה מסויימת.
הפקודה היא -
CallExtensionBridging
הפרמטרים הנדרשים
פרמטר תיאור סוג token טוקן string phones רשימת מספרים. ראה להלן צורות תמיכה ברשימת מספרים string / json ivrPath שלוחה במערכת, למשל: ivr2:/1/100
- יכניס לשלוחה 1/100string callerId זיהוי שיחה יוצא, ברירת מחדל זיהוי של המערכת/רשימת התפוצה שנבחרה string callsTimeOut זמן חיוג מקסימלי - בשניות, ברירת מחדל 30 שניות, מקסימום 35 שניות. number תמיכה בצורת רשימת מספרים:
פרמטר phones יכול להכיל רשימת מספרים בדומה לשירות
RunTzintuk
:
כאשר הפניה היא בGET או בPOST שהוא לא (
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" } ]
חיוב יחידות:
על כל מספר שנכנס לחיוג יש חיוב של 0.1 יחידות,
על כל שיחה שנענת, יש חיוב של יחידה לדקה, עם מינמום חיוב של 0.5 יחידות.שימו לב, ניתן להפעיל בשירות זה קמפיין עם עד 500 מספרים.
מענה בעת הצלחה:
פרמטר סוג הסבר דוגמא responseStatus string סטטוס הפעולה OK
module string המודול של השלוחה שהשיחות יגיעו אילה menu callerId string זיהוי השיחה היוצאת 0770770770 callsCount int כמות מספרים שנכנסו לקמפיין 6 bilingPerCall int חיוב לכל שיחה (משוער) 1 errors object מערך של מספרים שלא נכנסות לחיוג ושגיאה { "0510001": "not Vaild", "0510002": "not Vaild", "0510003": "not Vaild" }
callsTimeout int זמן שיחה יוצאת כפי שנקלט 30 campaignId string מזהה קמפיין במערכת הקמפיינים YA-1-0770770770-Yemot-1695290243349441
- רשימה מפורשת עם הפרדה של
-
-
-
-
-
-
-
-
-
-
קבלת רישומים לחשבון SIP - SipGetContexts
הפקודה היא -
SipGetContexts
בכל פניה יש לצרף:
פרמטר תיאור סוג token טוקן string accountNumber ניתן לציין מספר חשבון sip, באם ריק, זה החשבון הראשון string מענה בעת הצלחה
מאפיין סוג הסבר דוגמא responseStatus string סטטוס הפעולה OK
contexts array טבלאת רישומים מערך, יבואר מטה מבנה האובייקט אובייקט במערך contexts
בעיקרון, לא אמור להיות יותר מרישום אחד פעיל.
מאפיין סוג הסבר דוגמא expiration_time string זמן התפוגה של הרישום, באם השלוחה שולח keep_alive - הזמן מתארך 2024-06-04 15:43:38 uri string הURI לחיוג בפועל לשיחה נכנסת sip:0773137770@192.168.1.99:5060 user_agent string הפלטפורה שמחוברת Yealink SIP-T29G via_addr string ניתוב דרך. זה יכול להיות גם כתובת פנימית של השלוחה 192.168.1.110 via_port string ניתוב בפורט 5060 -
קבלת חשבונות הSIP במערכת בדגש על בדיקה אם הם רשומים - GetSipAccountsRegisteredStatus
הפקודה היא -
GetSipAccountsRegisteredStatus
בכל פניה יש לצרף:
פרמטר תיאור סוג token טוקן string מענה בעת הצלחה
מאפיין סוג הסבר דוגמא responseStatus string סטטוס הפעולה OK
accounts array טבלאת חשבונות מערך, יבואר מטה מבנה האובייקט אובייקט במערך accounts
מאפיין סוג הסבר דוגמא userName string שם המשתמש של החשבון 0773137770 createdDate string זמן יצירת החשבון 2021-06-26 23:00:00 registered bool האם רשום? true -
-
-
קבלת SMS שהתקבלו במערכת
הפקודה היא -
GetSmsIncomingLog
בכל פניה יש לצרף:
פרמטר תיאור הערות token טוקן limit כמות ה SMS האחרונים להצגה startDate מתאריך אופציונלי endDate עד תאריך אופציונלי מענה בעת הצלחה
מאפיין סוג תיאור דוגמה responseStatus string סטטוס הפעולה OK
rows array SMS שהתקבל + פרטים מערך, יבואר מטה מבנה האובייקט אובייקט במערך rows
כל הודעה נשלחת במערך נפרד, המורכב מפרמטרים כדלהלן:מאפיין סוג תיאור דוגמה dest int נשלח אל 972501234567 phone int הודעה מאת 972541234567 message string תוכן ההודעה דרוש המרה לפורמט JSON server_date string תאריך ושעת קבלת ההודעה 22:40:54 2024-07-30 דוגמא לקבלת ה SMS האחרון:
https://www.call2all.co.il/ym/api/GetSmsIncomingLog?token=xxxxx&limit=1 -
-
-