Call Log API

ישנם מקרים בהם תרצו למשוך (PULL) מאיתנו פרטי שיחות כאשר ברצונכם למשוך פרטי שיחות בטווחי זמן קבועים וידועים מראש.
לדוגמא:

1. תוכלו במרחב של כל 10 דקות (לדוגמא) לשלוח בקשת HTTP רגילה ולקבל פרטי שיחות שבוצעו בזמן האחרון.
2. תוכלו למשוך פרטי שיחות בסוף יום העבודה, הנושא יהיה בשליטתכם לפי הצורך והלוגיקה העסקית שלכם.
3. תוכלו להחליט איזה פרמטרים תרצו לקבל מחברת Voicenter.

הסבר כללי

פורמט בקשה

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": [

]

"phones": [

"972501234567",

"0722776772"

]

"extensions": [

"SipSip"

]

"IdentityCriteria": "Account",

"CallID": "xxxxxxxxxxxxxxxxxxxxxx"

}

]

"sort": [

{

"order": "desc",

"field": "date"

}

{

"order": "asc",

"field": "Duration"

}

]

}

בקשה לדוגמא בפורמט GET

          
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	מספר שלם. מציג את מספר השיחות על טווח הזמן שהגדרתם.
RETURN_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 מורשית.