הסבר כללי
הקישור של השירות שעליכם לפנות אליו
1
https://api.voicenter.com/hub/cdr/
פורמט בקשה
1. POST
2. GET
פורמט תגובה
1. JSON
אופי הפנייה שלכם
הפנייה שלכם בעצם צריכה להיות מורכבת משני חלקים:
1. הסינון שלפיו אנו נחזיר אליכם את פרטי השיחה - לדוגמא סינון לפי תאריך בפרמטרים: Fromdate + Todate.
כמו כן ישנם שדות נוספים שיאפשרו לכם לבצע סינון נוסף - מצוף בטבלה מטה.
2. השדות שתרצו לקבל בחזרה - בתגובה שלנו אנו נחזיר אליכם את פרטי השיחה שתרצו לקבל, בבקשה שלכם תצטרכו להעביר אילו פרמטרים תהיו מעוניינים לקבל חזרה.
לדוגמא, במידה ותהיו מעוניינים לדעת רק מה הקישור להקלטה, מספר טלפון של הלקוח בשיחה נכנסת ומזהה שיחה - אם תבקשו מאיתנו לקבל רק שדות אלו, שדות אחרים לא יועברו אליכם.
פרמטרים שאפשר להעביר בבקשה עבור סינון המידע
* סינון המידע מתייחס על פי איזה פרמטרים יועבר לכם המידע? למשל על פי אילו תאריכים? לפי איזה מספר טלפון? וכן הלאה, כמפורט מטה.
| שדה | תיאור | סוג |
| code | מחרוזת. ניתן לפנות גם עם bearer token. | קוד ייחודי לחשבון שלכם. פרמטר חובה. |
| fromdate | תאריך וזמן תחילת סינון בפורמט ISO 8601, הפרמטר הוא באזור זמן GMT 0. | חובה. |
| todate | תאריך וזמן סוף סינון בפורמט ISO 8601, הפרמטר הוא באזור זמן GMT 0. | חובה. |
| phones | מערך של מחרוזות, כל מחרוזת היא ספר טלפון יחד עם קידומת מדינה. מספר טלפון ישראלי ניתן לרשום ללא קידומת בינלאומית. | רשות. |
| extensions | מערך של מחרוזות, כל מחרוזת היא מזהה של שלוחה של Voicenter. | רשות. |
| IdentityCriteria | חיפוש לפי רמת חשבון, ניתן להגדיר אחת מהאפשרויות הנ"ל: חיפוש לפי כל החשבון - Account - תקף במידה ותרצו לקבל מידע על כלל החשבון לפי הקוד שהזנתם. חיפוש לפי חשבון מסוים והחשבונות תחתיו - Hierarchical - מומלץ במידה ובתת חשבון מסויים יש מספר תתי חשבונות מתחתיו. חיפוש רק לפי חשבון מסוים - Department - רלוונטי במידה ואתם רוצים תוצאה רק של חשבון מסוים חיפוש של שיחות של משתמש מסוים בלבד - User - יש להעביר את הקוד של אותו משתמש בנוסף לפרמטר זה. | רשות. |
| callID | מחרוזת, תוכלו לחפש שיחה ספציפית. | רשות. |
| cdrTypes | מערך של מספרים שלמים, נותן לכם את האפשרות לסנן תוצאות על פי סוגי שיחה מסוימים. | רשות. |
| campaignID | מערך של מספרים, כל מספר הינו מזהה קמפיין של Voicenter. | רשות. |
| queueID | מערך של מספרים, כל מספר הינו מזהה מעגל המתנה של Voicenter. | רשות. |
קביעת סדר הסינון
כמו כן, תוכלו לקבוע באיזה סדר הסינון יופיע והאם בסדר עולה או יורד.
| שדה | תיאור | סוג | תיאור |
| field | שם של השדה שלפיו יתבצע המיון. | מערך. | רשות. |
| order | ניתן לקבוע: asc/desc אשר יקבע את הסדר של המיון. | מחרוזת. | רשות. |
פרמטרים בבקשה
אלו הם הפרמטרים שבאפשרותכם לשלוח בבקשה שלכם על מנת שנחזיר אליהם מידע בשיחות על פי הסינון שביצעתם
| שדה | תיאור | דוגמא |
| CallerNumber | מציג את מספר הטלפון של המתקשר. זהו מספר הטלפון אשר מי שמקבל את השיחה ייראה. | "CallerNumber":"0722776772" |
| TargetNumber | מציג את מספר הטלפון של יעד השיחה. הפרמטר יהיה מספר טלפון או מזהה שלוחה של וויסנטר. מספרי טלפון יופיעו עם קידומת בינלאומית. | "TargetNumber":"AAPINFzL" / “TargetNumber":"972722776772" |
| Date | מציג את הזמן והתאריך שהשיחה בוצעה. | "Date":"2017-07-20 09:59:29" |
| DateEpoch | מציג את הזמן והתאריך שהשיחה בוצעה בפורמט Epoch. | "DateEpoch":1554027973 |
| Duration | מציג את משך השיחה בשניות. משך השיחה אינו כולל את משך זמן צלצול השיחה אלא רק את השיחה בפועל. | "Duration":33 |
| CallID | מציג מזהה שיחה ייחודי עבור כל שיחה. | "CallID":"20200720095ilila137b2f69s" |
| Type | מציג את סוג השיחה. לדוגמא: שיחה יוצאת/נכנסת/שיחה של מעגל המתנה. בהמשך תוצג טבלה עם פירוט על כלל סוגי השיחות. | "Type":"Incoming Call" / "Type":"Extension Outgoing" / "Type":"Click2Callleg1" |
| CdrType | מציג את סוג השיחה לפי מספר סידורי אשר שייך לסוג שיחה בטבלה מטה. | "CdrType": 4 |
| DialStatus | מציג את הסטטוס השיחה, האם נענתה? או לא? במידה ומדובר על שיחות עם 2 רגליים (כגון: קליק2קול, שיחות חייגן) שדה זה יראה מידע רק עבור הרגל הראשונה של השיחה. | "DialStatus":"ANSWER" / "DialStatus":"ABANDONE" / "DialStatus":"TE" |
| Targetextension | מציג את המזהה של השלוחה אשר קיבלה שיחה נכנסת. ישנם מקרים בהם הנתון בשדה זה עשוי להיות זהה לשדה "TargetNumber" באותה שיחה. אך ישנם מקרים כאשר שיחה נכנסת אינה מפנה ישירות לשלוחה מסוימת ולכן השדה "TargetNumber" יציג נתון שונה. | "Targetextension":"AAPINFzL" |
| Callerextension | מציג את המזהה של השלוחה אשר ביצעה שיחה יוצאת. המידע בשדה זה הוא שונה מהמידע בשדה "CallerField" מאחר ושדה "CallerField" מציג מספר מזהה של השלוחה בשיחה יוצאת. | "Callerextension":"AAPIUtdL" |
| DID | מספר הטלפון שהתקשרו אליו בשיחה נכנסת. | "DID":"0722776772" |
| QueueName | מציג את שם מעגל ההמתה אשר השיחה עברה בו. | "QueueName":"Service Queue" |
| RecordURL | קישור להקלטת השיחה. | "RecordURL":"https://cpanel.voicenter.co.i l/CallsHistory/PlayRecord/123abc.mp3" |
| RecordExpect | שדה בוליאני אשר מציג האם השיחה הוקלטה או לא. | "RecordExpect":true |
| RingTime | מציג משך זמן צלצול של השיחה. | "RingTime":23 |
| Price | מציג באגורות את מחיר השיחה. | "Price":7 |
| RepresentativeName | מציג את שם הנציג אשר היה מחובר וביצע/ענה לשיחה זו. הנציג חייב להתחבר למערכת על מנת ששדה זה יוצג. | "RepresentativeName":"Walter Melon" |
| RepresentativeCode | מציג את קוד עובד של הנציג אשר היה מחובר וביצע/ענה לשיחה זו. הנציג חייב להתחבר למערכת על מנת ששדה זה יוצג. | "RepresentativeCode":"19996" |
| UserName | בדומה לשדה "RepresentativeName" במידה והנציג היה מחובר לשלוחה בעת ביצוע/מענה לשיחה שדה זה יציג את אותו נתון. במידה ונציג לא היה מחובר לשלוחה שדה זה יציג את שם המשתמש אשר מקושר לשיחה/למספר טלפון שקשור לשיחה זה. | "UserName":"Walter Melon" |
| DepartmentName | מציג את שם החשבון כפי שהוא רשום בוויסנטר ומקושר לשיחה זו. | "DepartmentName":"Voicenter Account" |
| DepartmentId | מציג את מספר החשבון כפי שהוא רשום בוויסנטר ומקושר לשיחה זו. | "DepartmentId":123456 |
| TargetPrefixName | מציג את שם מדינת היעד בשיחה יוצאת. | "TargetPrefixName":"Israel" |
| DTMFData | שדה מסוג מערך JSON אשר מציג את מסלול שיחה נכנסת בנתב השיחות. השדות שיופיעו הם: שם השכבה - "LayerName" הקשות הלקוח בנתב - "DTMF" מספר שכבה - "LayerNumber" | "DTMFData":"[{LayerName: "Main Menu", DTMF: 2, LayerNumber: "0"}, {LayerName: "Sales", DTMF: 0, LayerNumber: "15"}]" |
| CustomData | שדה מסוג מערך JSON, מציג קוסטום דאטה אשר נשלח אלינו, בנוסף במידה ומדובר על שיחה שיש לה מזהה שיחה מקורי, אז גם נתון זה יופיע בשדה זה. | "CustomData": {"OriginalIvrUniqueID":"2020072118102as sdsdas"}" / "CustomData": {"var_clientID":"2118102", {"var_clientAccountID":"123456"}" |
בקשה לדוגמא בפורמט POST-JSON
{
"code": "xxxxxxxxxxxxxxxxxxxxxxxxxxx",
"fields":
[
"Calleumber",
"TargetNumber",
"Date",
"DateEpoch",
"Duration",
"CallID",
"CustomData",
"Type",
"CdrType",
"DialStatus",
"TargetExtension",
"CallerExtension",
"DID",
"QueueName",
"RecordURL",
"Price",
"RingTime",
"RepresentativeName",
"RepresentativeCode",
"DTMFData",
"DepartmentName",
"DepartmentId"
]
"search":
{
"fromdate": "2021-10-02T08:09:40",
"todate": "2021-11-09T23:59:40",
"cdrTypes":
[
1,
8,
9
]
"phones":
[
"972501234567",
"0722776772"
]
"extensions":
[
"SipSip"
]
"IdentityCriteria": "Account",
"CallID": "xxxxxxxxxxxxxxxxxxxxxx"
}
"sort":
[
{
"order": "desc",
"field": "date"
}
{
"order": "asc",
"field": "Duration"
}
]
}
בקשה לדוגמא בפורמט GET
1
2
https://api.voicenter.com/hub/cdr/?code=xxxxxxxxxxxxxxxxxxxx&fromdate=2022-06-01T08:09:40&todate=2022-06-
01T23:59:40&phones=972501234567&extensions=SipSip&fields=Date&fields=Type&Fields=DID&Fields=CallerNumber
סוגי שיחות
יש מספר של סוגי שיחות שאתם עשויים להיתקל בהם, להלן הסבר עבור כל אחד מהם.
| סוג שיחה | מספר מזהה | תיאור |
| Incoming Call | 1 | שיחה נכנסת רגילה אשר התקבלה דרך מספר טלפון אשר ניתב ישירות לשלוחה מסוימת. |
| CC | 2 | שיחה שבוצעה בעזרת שירות מספר גישה של חברת וויסנטר. |
| Extension Outgoing | 4 | שיחה יוצאת רגילה משלוחה של וויסנטר. * לא שיחת קליק2קול. |
| Queue | 8 | שיחה נכנסת שהתקבלה אל מעגל המתנה. |
| Click2Call leg1 | 9 | שיחת קליק2קול (לא שיחת חייגן). "רגל 1" של השיחה - השיחה בין השירות לשלוחה שאמורה לחייג ליעד ב"רגל 2" של השיחה. |
| Click2Call leg2 | 10 | שיחת קליק2קול (לא שיחת חייגן). "רגל 2" של השיחה - השיחה בין השלוחה ליעד. ברשומה זו תקבלו תיעוד על פרטי השיחה וקישור להקלטות השיחה. |
| VoiceMail | 11 | שיחה אשר נענתה על ידי שירות התא קולי של וויסנטר. |
| Callference | 12 | שיחה שבוצעה בעזרת שירות חדר וועידה של חברת וויסנטר. |
| XferCDR | 13 | שיחה אשר הוערה ידנית משלוחה של מספר/שלוחה אחרת. |
| ProductiveCall Leg1 | 14 | שיחת "רגל 1" של חייגן לנציג - השיחה אשר מחברת בין השירות לנציג. |
| ProductiveCall Leg2 | 15 | שיחת "רגל 2" של חייגן לנציג - השיחה אשר מחברת בין הנציג ליעד/לקוח/ליד שהזנתם בחייגן. |
| Scrubber | 16 | שיחה שבוצעה דרך שירות הסקראבר של חברת וויסנטר. |
| Click 2 IVR | 17 | שיחת "רגל 1" של חייגן חכם - השיחה הראשונית בין החייגן ליעד. |
| Click 2 IVR Incoming | 18 | שיחת "רגל 2" של חייגן חכם - השיחה שמתרחשת לאחר חיבור מוצלח ומענה של היעד "ברגל ה1". בסוג שיחה זה מתבצע חיוג מהיעד אל נתב השיחות שלכם. סוג שיחה זה מסמן כי השיחה לא עברה למעגל המתנה אלא הועברה ישירות לנציג או השמעת הקלטה. ברשומה זו תקבלו את סטטוס השיחה וקישור להקלטת השיחה. |
| Click 2 Queue Incoming | 19 | שיחת "רגל 2" של חייגן חכם - השיחה שמתרחשת לאחר חיבור מוצלח ומענה של היעד "ברגל ה1". בסוג שיחה זה מתבצע חיוג מהיעד אל נתב השיחות שלכם. סוג שיחה זה מסמן כי השיחה עברה למעגל המתנה והיעד המתין עד למענה של נציג. ברשומה זו תקבלו את סטטוס השיחה וקישור להקלטת השיחה. |
| FaxCdr | 20 | שיחה אשר בוצעה דרך שירות הפקס הפנימי של וויסנטר. *השירות לא פעיל עדיין. |
| Attended CDR leg1 | 21 | שיחה בהעברה עם התייעצות. |
| Attended CDR leg2 | 22 | שיחה בהעברה עם התייעצות. רשומה זו תתקיים כאשר מתבצע תסריט שיחה הבא: נציג א' עונה לשיחה נכנסת, הלקוח מבקש לדבר עם נציג ב'. נציג א' מתקשר אל נציג ב'. לאחר מכן נציג א' מעביר את השיחה והלקוח לנציג ב'. סוג שיחה זה נותן מידע על השיחה של הלקוח עם נציג ב'. |
| Auto forward | 23 | שיחה שהועברה באופן אוטומטי משלוחה למספר טלפון - בדרך כלל מדובר על הגדרה דרך הטלפון IP. |
סטטוסים של שיחות
שיחה יכולה להסתיים מסיבות שונות כגון, יציאה/נטישה ממעגל המתנה, סיום שיחה לאחר מענה, ניתוק לאחר מענה וכן הלאה.
לפניכם טבלה אשר מרכזת את המידע עבור סטטוסים שונים אפשריים.
| שם סטטוס | תיאור |
| NOTDIALED | ניתוק לפני ביצוע שיחה. |
| ANSWER | מענה של שיחה לאחר חיוג/צלצול מוצלח. השיחה הגיעה ליעדה. מענה מתרחש כאשר וויסנטר מקבל איתות של מענה בשיחהכ מו כן גם הגעת השיחה לתא קולי. |
| BUSY | כאשר מנסים לבצע חיוג ליעד מסוים אבל מספר הטלפון שולח בחזרה איתות של "עסוק". |
| NOANSWER | אין מענה. השיחה הגיעה ליעד אך צלצלה למשך זמן מסוים עד לאי מענה. |
| CANCEL | ביטול שיחה. מצב זה קורה כאשר מחייגים ליעד מסוים אבל מתבצע ניתוק לפני מענה ביעד. |
| ABANDONE | שיחות שהגיעו למעגל המתנה והלקוח המתקשר ניתק לפני מענה מנציג. |
| TIMEOUT | שיחת מעגל המתנה אשר המתינה זמן מקסימלי במעגל. |
| FULL | שיחת אשר ניסתה להצטרף למעגל המתנה אך המעגל היה מלא בממתינים ולא היה ניתן לצרף ממתין נוסף. |
| EXIT | שיחת מעגל המתנה אשר לקוח החליט לצאת מהמתנה. |
| JOINEMPTY | לקוח מתקשר ניסה להצטרף למעגל המתנה אך לא היו בו נציגים מחוברים. |
| VOEND | ניתוק של השיחה במעמד הנתב ללא צלצול בשלוחה כלשהי או מעגל המתנה. במקרה זה לקוח התקשר הגיע לנתב השיחות וניתק. |
| TE | מתרחש כאשר השיחה מגיעה לנתב השיחות ומשמיעה הקלטה ולאחר מכן מתנתקת. |
| NOTCALLED | סטטוס זה מציין כי הרגל השנייה של השיחה לא בוצעה מאחר והרגל ה1 של השיחה לא הייתה מוצלחה (השיחה לא התחברה לשלוחה). |
| VOICEMAIL | שיחה הגיעה לתא הקולי של וויסנטר. |
| CONGESTION | סטטוס זה מסמל לרוב חיוג ליעד לא מוכר. |
| CHANUNAVAIL | ערוץ לא זמין או שלוחה לא מחוברת ורשומה. |
| INVALIDARGS | שגיאה בעיבוד פקודת חיוג ליעד. |
| SSWPREAUTH | ביטול שיחה יוצאת לפני ביצוע חיוג. |
דוגמא לתגובה בפורמט POST-JSON
{
"ERROR_NUMBER": 0,
"ERROR_DESCRIPTION": "OK",
"STATUS_CODE": 200,
"TOTAL_HITS": 2,
"RETURN_HITS": 2,
"CDR_LIST":
[
{
"CallerNumber": "0722776772",
"TargetNumber": "972501234567",
"Date": "2021-10-10T09:04:58Z",
"Duration": 2,
"CallID": "202110101204550233243ghff3189e5c",
"CustomData":
{
}
"Type": "Extension Outgoing",
"CdrType": 4,
"DialStatus": "ANSWER",
"TargetExtension": "",
"CallerExtension": "SipSip",
"DID": "",
"RecordURL": "https://cpanel.voicenter.co.il/CallsHistory/PlayRecord/2021101043950926.mp3",
"RingTime": 10,
"RepresentativeName": "rep 1",
"RepresentativeCode": "87654321",
"DTMFData":
[
]
"DepartmentName": "Test Account",
"DepartmentId": 12345678
}
{
"CallerNumber": "0501234567",
"TargetNumber": "SipSip",
"Date": "2021-10-02T12:55:18Z",
"Duration": 0,
"CallID": "202110021555160180fd3jhj455",
"CustomData":
{
"OriginalIvrUniqueID": "20211002156fdf534hfgh453df34"
}
"Type": "Incoming Call",
"CdrType": 1,
"DialStatus": "CHANUNAVAIL",
"TargetExtension": "SipSip",
"CallerExtension": "",
"DID": "0722776772",
"RecordURL": "",
"RingTime": 2,
"RepresentativeName": "rep 1",
"RepresentativeCode": "87654321",
"DTMFData":
[
{
"LayerName": "rep 1",
"DTMF": 0,
"LayerNumber": "1"
}
]
"DepartmentName": "Test Account",
"DepartmentId": 12345678,
"TargetPrefixName": ""
}
]
}
פרמטרים בתגובה
| שדה | תיאור |
| ERROR_NUMBER | מספר שלם. מציג מספר שגיאה. נא עיינו מטה לראות מספרי שגיאות אפשריים. |
| ERROR_DESCRIPTION | מחרוזת תיאור מילולי של השגיאה. |
| STATUS_CODE | מחרוזת. קוד תגובה לבקשת HTTP. |
| TOTAL_HITS | מספר שלם. מציג את מספר השיחות על טווח הזמן שהגדרתם. |
| HITS | מספר שלם. כמות השיחות שמופיעות בתגובה שקיבלתם. |
| CDR_LIST | מערך של אובייקטים. כל אובייקט הוא פירוט של שיחה. |
שגיאות אפשריות
| מספר שגיאה | תיאור שגיאה | קוד שגיאה | תיאור מילולי |
| 0 | OK | 200 | הבקשה נשלחה בהצלחה. |
| 1 | Request limit exceeded. Please try again later. | 403 | יש הגבלה על כמות הבקשות שכל ארגון יכול לשלוח בטווח זמן מסוים. מומלץ לשלוח בקשה אחת כל 5 דקות. |
| 2 | Authorization failed. | 403 | הקוד בבקשה שלכם אינו תקין. |
| 4 | IP address xx.xx.xx.xx is not trusted. | 403 | הבקשה נשלחה מכתובת IP לא מורשית. |
| 5 | Out of range | 404 | הייתה בעיה עם חיפוש שיחות לפי התאריכים שהוזנו, טווח הזמנים אינו תקין. |
דגשים
- פירוטי השיחות מעודכנים בשירות זה מספר דקות לאחר סיומם.
- ניתן לקבל עד 10,000 רשומות בבקשה אחת.
- ניתן לשלוח עד 30 בקשות בדקה.
- ניתן לשלוח בקשות רק מכתובת IP מורשית.