Function
The GET/active/calls request returns details about currently active calls dialed or received by a user.
Note that calls are tracked in segments as they get routed through the phone system (this is also referred to as the call flow). The response, therefore, has two identification numbers – one for the entire call and one for the current segment. These usually have the same value for the first segment, but if a call is routed to a new phone system point, a new segment ID is assigned.
Direct outbound calls will only have one segment, while inbound and internal calls will usually have several segments.
Response Fields
The response includes the following information fields:
- server – this usually has a "null" value unless a special server was used for the call, in which case a number will identify the relevant server for making or receiving the call.
- uniqueid – a unique ID for a particular call segment (inside an entire call flow) created by combining its start time, direction, and other values.
- callid – a unique ID for the entire call as a whole. This value will be for identical all call segments. Usually callid and uniqueid have the same value for the first call segment in a call flow..
- start – the start time for the call or call segment, in Unix time format.
- answered – the time the call or a call segment was answered, in Unix time format.
- stype – a definition for the type of source point, where the call or call segment started from. This will always be "external" for an inbound call from an outside source. Otherwise it can be any of numerous points on the PBX – "ivr", "accessmenu, "queue", "extension", etc.
- snumber – the phone number of the source point that initiated the call. This can be, depending on the direction of the call, either an internal extension/number, a full telephone number, or a temporary number assigned by the system to the point in case it doesn't have one (such as in the case of an IVR).
- spresent – a value of 1 indicates that the presentation of the source call supports the ISDN format. A value of 0 indicates it is not.
- stransferred – a value of 1 indicates that the source point(defined by snumber/stype) was transferred by the system to the present call segment. A value of 0 indicates it it not. This will always be 0 in the first segment or when a call arrives at the IVR menu.
- ctype – the type of the called point (where the source customer originally dialed) in the current call or call segment. This has no value for outbound calls. For inbound or internal calls, the value is not absolute for the entire call but is assigned by the system based on the call flow progression.
- cnumber – the phone number of the called point (where the source customer originally dialed) in the current call or call segment. The value is not absolute for the entire call but is assigned by the system based on the progression of the call in the call flow.
- dtype – the type of destination point (where the call was routed to) for the call or call segment. Examples can be "ivr", "accessmenu, "queue", "phone", "mailbox", etc. The type will always be "external" for outbound calls.
- dnumber– the phone number of the destination point where the call was routed to for the call or call segment.
Note that in inbound and internal calls, ctype and cnumber will differ from dtype and dnumber only in the first segment or two. After that they are usually identical. - ptransferred – an indication that the call was transferred to a parking area before reaching the user.
- dtransferred – a value of 1 indicates that the destination point (defined by dnumber/dtype) requires a transfer between points to be reached from the current call segment. A value of 0 indicates it is not. For example, when a call moves from a phone number to its mailbox this will have a 0 value since a mailbox is considered the same point as its number.
- callerid_internal –A caller ID number assigned to the user who received the call (for inbound or internal calls) or initiated it (for outbound calls). This is usually the same as the user's phone line or extension number.
Internal caller IDs are only applicable to PBX and internal functions of the phone system. They are not shared with external contacts.
For incoming call segment where a user is not yet involved (like the call is still ringing or in the IVR), the system will assign the callerIdExternal value instead - callerid_external –A ten-digit caller ID assigned to the user's line and is shared with external contacts during outbound calls, but is not relevant to internal calls.
- callername_internal –The name of the user who received the call (for inbound or internal calls) or inititiated it (for outbound calls). It is not shared with external contacts.
For an incoming call segment where a user is not yet involved (when the call is still ringing or holding in the IVR), the system will assign the callerNameExternal value instead. - callername_external –A caller ID name assigned globally to all user lines as a company or organization name and can be modified on the Admin Center by going to Account>Profile>Organization name.
The external caller name is shared with external contacts during outbound calls but is not relevant to internal calls. - park – if the call was parked during the call flow before reaching the user, this is the number of the extension or line where it was parked.
- status – indication of the status of the call, in the current call segment, in terms of the connection between the caller and recipient. Possible responses include "answer", "noanswer" (by the recipient), "cancel" (by the caller), "congestion" (too much traffic preventing a connection), "busy" (the recipient is on another call), or "chanunavail" – the destination communication channel (his phone line or number) is unavailable or the requested peer is not be registered.
- duration – total duration of the call segment in seconds.
- caller– name, extension, or number of the caller. This may temporarily take the virtual extension number of the IVR when the call is being handled by it.
- called – name or extension of the recipient of the call. If not available (for external recipient), the called number will be given here.
- callednumber– phone number of the recipient of the call.
Request Parameters
None required!
The Limit and Offset optional parameters may be used if dealing with a large number of active calls (rarely, if ever, the case).
Examples
To get details of the active call logs for a user use the following syntax:
HTTPS method: GET
webserv.telebroad.com/api/teleconsole/rest/active/calls/panel
Response:
If no active call it taking place:
{
"error": null,
"result": []
}
Outbound call example with only one call flow segment:
{
"error": null,
"result": [
{
"server": null,
"uniqueid": "1580622316.049471",
"callid": "1580622316.049471",
"start": "1580622316",
"answered": "1580622323",
"stype": "phone",
"snumber": "1113834",
"spresent": "1",
"stransferred": "0",
"ctype": "",
"cnumber": "12128835335",
"dtype": "external",
"dnumber": "12128835335",
"dtransferred": "0",
"ptransferred": "0",
"callerid_internal": "201",
"callerid_external": "16312828888",
"callername_internal": "Rick Goodwin",
"callername_external": "Rick Goodwin",
"park": "",
"status": "answer",
"duration": "00:00:18",
"caller": "1113834",
"called": "12128835335",
"callednumber": "12128835335"
}
]
}
Inbound call example with multiple call flow segments:
{
"error": null,
"result": [
{
"server": null,
"uniqueid": "1580623617.015555",
"callid": "1580623617.015555",
"start": "1580623617",
"answered": "1580623617",
"stype": "external",
"snumber": "12128835335",
"spresent": "1",
"stransferred": "0",
"ctype": "",
"cnumber": "16466991356",
"dtype": "ivr",
"dnumber": "6208",
"dtransferred": "0",
"ptransferred": "0",
"callerid_internal": "12128835335",
"callerid_external": "12128835335",
"callername_internal": "THOMPSON ANDREW",
"callername_external": "THOMPSON ANDREW",
"park": "",
"status": "",
"duration": "00:02:10",
"caller": "12128835335",
"called": "16466991356",
"callednumber": "16466991356"
},
{
"server": null,
"uniqueid": "1580623626.076365",
"callid": "1580623617.015555",
"start": "1580623626",
"answered": "1580623626",
"stype": "ivr",
"snumber": "6208",
"spresent": "1",
"stransferred": "0",
"ctype": "queue",
"cnumber": "1409",
"dtype": "queue",
"dnumber": "1409",
"dtransferred": "1",
"ptransferred": "0",
"callerid_internal": "12128835335",
"callerid_external": "12128835335",
"callername_internal": "THOMPSON ANDREW",
"callername_external": "THOMPSON ANDREW",
"park": "",
"status": "",
"duration": "00:02:01",
"caller": "6208",
"called": "1409",
"callednumber": "1409"
},
{
"server": null,
"uniqueid": "1580623692.561944",
"callid": "1580623617.015555",
"start": "1580623692",
"answered": "1580623693",
"stype": "",
"snumber": "12128835335",
"spresent": "1",
"stransferred": "0",
"ctype": "",
"cnumber": "1113834",
"dtype": "phone",
"dnumber": "1113834",
"dtransferred": "1",
"ptransferred": "0",
"callerid_internal": "12128835335",
"callerid_external": "12128835335",
"callername_internal": "THOMPSON ANDREW",
"callername_external": "THOMPSON ANDREW",
"park": "",
"status": "answer",
"duration": "00:00:54",
"caller": "12128835335",
"called": "1113834",
"callednumber": "1113834"
},
{
"server": null,
"uniqueid": "1580623693.315819",
"callid": "1580623617.015555",
"start": "1580623693",
"answered": "1580623693",
"stype": "phone",
"snumber": "1113834",
"spresent": "1",
"stransferred": "1",
"ctype": "mailbox",
"cnumber": "201",
"dtype": "mailbox",
"dnumber": "201",
"dtransferred": "0",
"ptransferred": "0",
"callerid_internal": "12128835335",
"callerid_external": "12128835335",
"callername_internal": "THOMPSON ANDREW",
"callername_external": "THOMPSON ANDREW",
"park": "",
"status": "",
"duration": "00:00:54",
"caller": "12128835335",
"called": "201",
"callednumber": "201"
}
]
}