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

[שמואל]

חשבונות SIP

---

תיעוד api הנוגע לחשבונות SIP

כל השירותים שקשורים לSIP קיימים רק בשרתים תומכים.
בכל פניה לשרת שלא תומך תתקבל תגובה:

{
responseStatus: "ERROR",
message: "שרת זה אינו תומך במערכת SIP",
yAfastVersion: "any"
}

---

מאפיינים

לכל חשבון SIP במערכת יש מספר מאפיינים

1. מספר החשבון במערכת (למשל 1 2 וכן הלאה)
2. שם המשתמש להתחברות
   בדרך כלל שם המשתמש מורכב ממספר המערכת ומספר החשבון.
   למשל 0772222770=2 זהו שם המשתמש של חשבון 2 במערכת 0772222770
3. מספר שלוחה - כל מספר שנמצא בטווח מ-200 ועד 10,000
   מספר שלוחה הינו מאפיין הנתון לבחירה של מנהל המערכת וניתן לשנות אותו בכל עת.
   הדבר משמש עבור חיוגים פנימיים בין החשבונות. (למשל כדי לחייג משלוחה 200 לשלוחה 201 יש לחייג למספר "201" במקרה כזה מה שיופיע על הצג אצל מקבל השיחה זה "200")
4. סיסמת התחברות
5. פרוטוקול 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 עבור שלוחה 1 ext/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/100	string
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

[אלחנן1]

קבלת 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

[שמואל]

קבלת זיהויים מאושרים במערכת להוצאת שיחות/סמסים

---

הפקודה היא - GetApprovedCallerIDs

כל המספרים הם במבנה e164

בכל פניה יש לצרף:

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

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

מאפיין	סוג	תיאור	דוגמה
responseStatus	string	סטטוס הפעולה	OK
call	object	זיהויים לשיחות	יבואר מטה מבנה האובייקט
sms	object	זיהויים לשיחות	יבואר מטה מבנה האובייקט

אובייקט call

מאפיין	סוג	תיאור
mainDid	string	המספר הראשי של המערכת
secondaryDids	array	מערך מספרי משני
callerIds	array	מערך זיהויים מאושרים חיצוניים

אובייקט sms

מאפיין	סוג	תיאור
smsId	string	זיהוי הסמסים (אם יש זיהוי סמסים, זה אומר שסמסים יוצאים רק איתו, אם לא, ניתן לבחור בכל זיהוי שיחה גם לסמס)
allowText	bool	האם מאושר זיהויים טקסט

[שמואל]

בדיקת זיהוי האם הוא מאושר לשימוש בשיחה/סמס

---

הפקודה היא - IsCallerIDApproved

בכל פניה יש לצרף:

פרמטר	תיאור	הערות
token	טוקן
callerId	זיהוי לבדיקה
serviceType	סוג שירות לבדיקה. ברירת מחדל שיחות	sms אוcall

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

מאפיין	סוג	תיאור	דוגמה
responseStatus	string	סטטוס הפעולה	OK
parsedCallerId	string	המספר כE164	+972773137770
isApproved	bool	האם מאושר
reason	string	סיבה	INVALID_CALLER = זיהוי לא תקין / SMS_ID = נעילת זיהוי סמסים / INCLUDE = רשימת מספרים מורשים