3CX XAPI - CallHistoryView code explanations?

[dkrilcic]

Hey all,

I've been researching 3CX XAPI, and I got the Call History exported from our system using endpoint at /xapi/v1/CallHistoryView

I've noticed some codes there that would most likely be helpful, but I haven't found any documentation about it.

I've tried some logical "decoding", combined with comparisons in the web UI, and came to these rough conclusions...

For fields: SrcDnType & DstDnType
0 = phones with internal numeration
1 = external phone numbers
4 = calls to queues
5 = calls to VMail (voice mail)
6 = IVR (PlayFile) ???
7 = Fax
8 = Parking
12/13 = looks like calls to numbers that are blocked, unreachable or otherwise don't work (eg mistyped and such)
14 = special functionality?

The above look quite logical but if someone can confirm or correct anything please do!

For the field "SegmentActionId" it is way harder to simply conclude by looking at logs, but these are my current best guesses:

6 = Terminated calls, I assume after successful call
10 = call made to queue that was successfuly forwarded to agent that answered it, in web ui seems to be described as "Queue xxx replaced by John Doe"
101, 102, 103, 105 - unanswered call that was redirected somewhere else, usually to voicemail or queue, but don't see what would be distinct between these codes
5 = ???? seems like... just normal calls maybe?
2,7,8,12 = can't explain but these happen rarely so I can ignore them most probably
9 = weird status like John (1234) replaced by John (1234) which doesn't make sense but also rare so probably can be ignored
400-426 - unanswered calls without much logic connecting them, many look like made to weird numbers that probably don't exist, so I haven't yet put much effort into deducting what they mean

Now obviously, a question... Does anyone have a codebook for these, better explanations, something to paint a clearer picture?

Most of the questions at the moment that would require reports are obviously calls to queues, how these get handled, statistics for different agents, times of day, and so on. If the above codes are correct, I can filter something like DstDnType=4 (queue), and then use SegmentActionId to see if call was properly answered (code 10?) or redirected to voicemail (code 101-105?) meaning agent didn't pick up, etc, the correlations with agents and times of day/night, and so on. But the codes are currently just assumptions so I don't feel good about taking it for a fact.

Any pointers would be helpful, maybe there's a way to fetch that through some other API endpoint, maybe some deeply hidden manual, etc...

Thanks in advance!

 

[Evolute IT]

Use the ReportCallReportData function. The one used by the admin's regular call report. The data is easier to read.

 

[dkrilcic]

Thanks for a suggestion, I've seen that endpoint but didn't yet have time to try it, and certainly didn't know it's the same one used for GUI (though, logical :-/ ). It does seem trickier to use and filter, but I'll try that if I can't find these codes. At the moment I have pretty functional code that does data retrieval, formatting (dates, times, etc) and exports to Excel so seems like wasted time if I need to switch to something else :-/ I'll have a look there while waiting for some good souls to maybe confirm my findings...

Edit: I assume you meant: xapi/v1/ReportCallLogData

 

[Evolute IT]

Thanks for a suggestion, I've seen that endpoint but didn't yet have time to try it, and certainly didn't know it's the same one used for GUI (though, logical :-/ ). It does seem trickier to use and filter, but I'll try that if I can't find these codes. At the moment I have pretty functional code that does data retrieval, formatting (dates, times, etc) and exports to Excel so seems like wasted time if I need to switch to something else :-/ I'll have a look there while waiting for some good souls to maybe confirm my findings...

Edit: I assume you meant: xapi/v1/ReportCallLogData

Yes that one lol

The parameters in ( ) are part of the URL by the way, and should have values even if empty.

I can send you an example of how we use it in PHP.

 

[dkrilcic]

I can send you an example of how we use it in PHP.

Oh that'd be great as I'll probably end up with PHP when I solve all the kinks abiut requesting and parsing data properly, thanks!

 

[dkrilcic]

Thanks for the sample excerpt, I've played a few hours and got really nice XLSX export from the /xapi/v1/ReportCallLogData/Pbx.GetCallLogData()

Data inside is way better as it offers some things that are not available at the /xapi/v1/CallHistoryView endpoint, so that's great.

But I have to note that I see the very same "codes" in this dataset as well. eg.

SourceType which would probably be equivalent to SrcDnType on the other endpoint, same with
DestinationType probably being same as DstDnType
They both share codes 0/1/4/5/6/7/8/12/13/16 maybe more if I select longer timespan.
I also see ActionDnType that wasn't available in the previous endpoint, but seems to share same codes.

There is also field ActionType that correlates to "SegmentActionId" from the CallHistoryView, with codes up to 426 in my sample.

I also have that text string now, which is available in web UI call reports, such as "Terminated by ..." and it is tied to action codes 5 & 6. Distincion seems to be that 5 means that caller (source) terminated call, while 6 means that callee (destination) terminated the call. This is subtle distinction, but I am sure more such differences would surface for other codes.

As mentioned before, seems that all actions 101-105 are some kind of redirects, but they are different. I can now see what seems to be:
- 105 - forwarded to..
- 101 - no answer, forwarded to ...
- 102 - busy, forwarded to ...
- 103 - not registered, forwarded to ...
- 104 - forwarded to ...
But while 101-103 now look more clear, the question remains why is both 104 & 105 marked as "forwarded to" and what's the difference. In my case 104 gets fwd to Vmail, or queues. 105 gets forwarded to users and - queues. So ok I can assume differnce between Vmail and user, but why different codes if fwd destination is queue in both cases?

Codes have a meaning, and they are useful, so if anyone reads this, whenever in the future, and you know the answer - please share!

P.S. I will post example script later how to retrieve the Report with Powershell, just need some time to clean it up and make it better suited for general use.

 

[Colby D.]

Here is my rough estimated breakdown based on looking through the call logs and trying to cross reference what I could find, not 100% complete but should help


The underscores indicate the name/number of the entity being referenced
SourceType
0 Extension
1 Trunk
6 PlayFile


DestinationType
0 Extension
1 Number
4 Queue
5 Voicemail
6 IVR
7 Fax
8 Parking Orbit
12 invalid?
13
16 Group (?)


ActionType
2 Picked up by ___
5 Terminated by ____
6 Terminated by ____
7 Transfer of ____ failed
8
9 ____ replaced by ____
10 ____ replaced by ____
12 ____ was joined
101 No answer, forwarded to ____
102 Busy, forwarded to ____
103 Not registered, forwarded to ____
104 Forwarded to ____
105 Forwarded to ____
109 Out of office, forwarded to ____
400 Failed
408 Target not found
412 Target is busy
413 No answer by timeout
415 Not available
417 No Route Exists
418 Failed Cancelled
420 Server Error
421 Route Busy
422 Route Not Found


ActionDnType
NULL
0 Extension
1 Number
4 Queue
5 Voicemail
6 IVR
7 Fax
8 Parking Orbit
14 SPEC


ActionDnType
____ replaced by ____
____ was joined
Busy, forwarded to ____
Forwaded to ____
No answer, forwarded to ____
No Route Exists
Not Available
Not Registered, forwarded to ____
Out of office, forwarded to ____
Picked up by ____
Route Busy
Route Not Found
Terminated by ____
Transfer of ____ failed

 

[Evolute IT]

The "Reason" field shows a text version of the ActionType.

 

[dkrilcic]

Here is my rough estimated breakdown based on looking through the call logs and trying to cross reference what I could find, not 100% complete but should help

This is great info, thanks! I'll keep digging and will update with any of my own findings that I stumble upon that aren't already in this (very nice!) list .

The "Reason" field shows a text version of the ActionType.

Indeed it is, but like I've said even the text in there isn't completely enough to explain some of the differences between the codes.

 

[dkrilcic]

I've added my PowerShell scripts to github here, so they are available to anyone in need of using or researching this XAPI:

https://github.com/luxzg/3CX-XAPI_examples

Hope it helps! And thanks again to everyone in this thread that helped with their own input!

 

[Colby D.]

One recommendation I would make is to update the regex for the following to be a little more robust

^PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?$

In some reports (mostly queue login time or other status related items) this field can include delimiters beyond just H, M, and S. This can include more like D (day), W (week).
In theory it may go further than that but have yet to experience that

I've added my PowerShell scripts to github here, so they are available to anyone in need of using or researching this XAPI:

https://github.com/luxzg/3CX-XAPI_examples

Hope it helps! And thanks again to everyone in this thread that helped with their own input!

 

[dkrilcic]

Thanks for that suggestion Colby, I'll do that when I get back to the script itself.

In the meantime I've also written a huge readme on the GitHub that explains a lot of stuff I've encountered while doing all this... Hopefully it helps others as a reference related to this XAPI in general. You can just go to GitHub linked above, or directly to Readme file here:

https://github.com/luxzg/3CX-XAPI_examples/blob/main/README.md

I've included link to this thread because of the codes, so if we get anything new posted here it will hopefully improve visibility of the info in this thread.

Cheers everyone, and thanks a million times for all the info and suggestions!

 

[AA-ODITEO]

Hello guys,

We are trying to have any sort of history to show using this API. I was wondering if you fine gentlement would please care to help.

We tried:

• CallHistoryView : 200 OK but table is empty,
• ActivityLog/GetLogs returns a 404

Did you encounter that kind of issues? Are we doing something wrong?

Thanks in advance for your help and for reading this,
Antoine