Understanding Zoom Phone call logs

This article will discuss how to access and read Zoom Phone call logs using our REST APIs.

Listing the call logs

The Zoom Phone API offers two endpoints to get a list of call logs:

  • Get account’s call logs
  • Get user’s call logs
    • User level API with a user centric response
    • Available to JWT, Account level oAuth apps with phone:read:admin scope, and User level oAuth apps with phone:read scope
    • API Reference for get user’s call logs

These two APIs return a list of call log records. The response to the get user’s call logs API is limited to the request user’s perspective. As such, it does not always contain all information about a call for certain events that happened before the call was routed to that particular user. Therefore, for purposes of full call accounting and analytics, this discussion will focus on the use of the get account’s call logs API.

Interpreting the get account’s call logs API response

The above API returns a JSON array that includes the top-level data for each call record. For outbound calls, the top-level data is generally the entire call. However, for inbound calls, the top-level data may show only a small fraction of how the call routed within the Zoom Phone platform.

There can be many different call flows within the Zoom Phone platform, some of the more common call flows are:

  1. User placed outbound call.
  2. Inbound call placed to a user’s direct phone number.
  3. Inbound call placed to an auto receptionist, callers dials a user’s extension, user then answers the call.[1]
  4. Inbound call placed to a call queue and then answered by a particular user.[1]
  5. Inbound call placed to an Auto Receptionist, caller makes a menu selection and the call is routed to a call queue, which then routes the call to users, one of whom can answer the call.[1]
  6. Inbound call placed to a shared line and answered by a particular user.[1]

[1] In the above example, scenarios 3, 4, 5, and 6 involve the call routing through multiple components within Zoom Phone. In order to see all of the call details for call scenarios such as these, you must query the call log detail API for each call. This API will return a detailed response that includes the subsequent components that routed the call.

Get call log details

The get call log details API is used to query the Zoom Phone platform for detailed information about a particular call. The response will include data such as the call queue that routed the call, the user’s that were offered the call, and the user that ultimately answered the call.

To query the call log detail API, you will need to provide a CallID or callLogId that you obtained from either a webhook event or the response from get account’s call logs API.

Putting it all together

Let’s say we have a call flow shown below:

  1. An external caller dials into a phone number assigned to an auto receptionist named Marketing Hotline.
  2. The external caller makes a menu selection on the auto receptionist which then routes the call to a particular call queue named Marketing Queue.
  3. The call queue is configured with rotating distribution and routes the call to a group that contains 5 users.
  4. The call first rings to user Sally Smith, but Sally isn’t able to answer the call.
  5. The call then rings to user Julie Jones, Julie answers the call.

Let’s take a look at the APIs that we can use to gather the data associated with the above call flow.

Find this call in the list accounts call logs API

Request GET https://api.zoom.us/v2/phone/call_logs

Response

{
   "next_page_token": "565fdfgs4645",
   "page_size": 30,
   "total_records": 120,
   "from": "2021-05-10",
   "to": "2021-05-11",
   "call_logs": [
       {
           "id": "dcasgfdd-gfb0-4ea7-8dc0-c96rer34d7",
           "call_type": "voip",
           "caller_number": "+16695551234",
           "caller_number_type": 2,
           "caller_location": "San Jose, CA",
           "callee_number": "150002",
           "callee_number_type": 1,
           "callee_name": "Marketing Hotline",
           "direction": "inbound",
           "duration": 12,
           "result": "Call connected",
           "date_time": "2021-05-11T23:11:44Z",
           "path": "autoReceptionist",
           "site": {
               "id": "W454_mIgsdia4-Yn53334Hw",
               "name": "Headquarters"
           },
           "has_recording": false,
           "has_voicemail": false,
           "call_id": "696165649876346057",
           "owner": {
               "type": "autoReceptionist",
               "id": "4KL1uortyet5644boSbtEw",
               "name": "Marketing Hotline",
               "extension_number": 150002
           },
           "answer_start_time": "2021-05-11T23:11:44Z"
       },
       ...
    ],
    ...
}

From the above response we can see the information about the caller, and we can see that they dialed into the Marketing Hotline auto receptionist.

Since we know this is an auto receptionist call, we know there is usually more information than we can see from list accounts call logs. Let’s query the call log detail API for this particular call with call_id 696165649876346057 to get more information.

Querying the call Llg detail API

Taking the call_id from the above example, we can query the call log detail API.

Request GET https://api.zoom.us/v2/phone/call_logs/696165649876346057

Response

{
   "id": "dcasgfdd-gfb0-4ea7-8dc0-c96rer34d7",
   "call_type": "voip",
   "caller_number": "+16695551234",
   "caller_number_type": 2,
   "caller_location": "San Jose, CA",
   "callee_number": "150002",
   "callee_number_type": 1,
   "callee_name": "Marketing Hotline",
   "direction": "inbound",
   "duration": 12,
   "result": "Call connected",
   "date_time": "2021-05-11T23:11:44Z",
   "path": "autoReceptionist",
   "has_recording": false,
   "has_voicemail": false,
   "log_details": [
       {
           "id": "4c6eree7-5b1e-4833-a672-b9234534b868",
           "caller_location": "San Jose, CA",
           "duration": 12,
           "result": "Auto Recorded",
           "date_time": "2021-05-11T23:11:56Z",
           "path": "callQueue",
           "site": {
               "id": "W454_mIgsdia4-Yn53334Hw",
               "name": "Headquarters"
           },
           "recording_id": "79b4147ad442354234239abd3633a5",
           "recording_type": "Automatic",
           "forward_to": {
               "type": "callQueue",
               "name": "Marketing Queue",
               "id": "EzYX42345pQgfMA_U6UQ",
               "extension_number": "151006"
           },
           "answer_start_time": "2021-05-11T23:11:44Z"
       },
       {
           "id": "9456434-6656f-4645-b912-cc3b5356a1",
           "call_type": "voip",
           "caller_location": "San Jose, CA",
           "duration": 0,
           "result": "Answered by Other Member",
           "date_time": "2021-05-11T23:11:58Z",
           "path": "extension",
           "site": {
               "id": "W454_mIgsdia4-Yn53334Hw",
               "name": "Headquarters"
           },
           "forward_to": {
               "type": "user",
               "name": "Sally Smith",
               "id": "XnK5466456xPIzSg",
               "extension_number": "150001"
           }
       },
       {
           "id": "7453147a-d60c-4211-ab01-6b4545633a5",
           "call_type": "voip",
           "caller_location": "San Jose, CA",
           "duration": 12,
           "result": "Call connected",
           "date_time": "2021-05-11T23:12:09Z",
           "path": "extension",
           "site": {
               "id": "W454_mIgsdia4-Yn53334Hw",
               "name": "Headquarters"
           },
           "forward_to": {
               "type": "user",
               "name": "Julie Jones",
               "id": "uK9clxm34534543lGCAOdA",
               "extension_number": "151011"
           },
           "answer_start_time": "2021-05-11T23:12:11Z"
       }
   ],
   "call_id": "696165649876346057",
   "answer_start_time": "2021-05-11T23:11:44Z"
}

Based on this response, we can now see that the caller went into a call queue named Marketing Queue and that the call rang on both Sally Smith’s Zoom Phone devices and also Julie Jones Zoom Phone devices. Because the date_time for Sally was before Julie, we know that Sally rang first and didn’t answer the call. We know that Julie ultimately answered this call because Julie’s result is “Call connected.”

Summary

When you need to see the entire picture for inbound calls, use both the list accounts call log API and the call log detail API to retrieve information about the call. Together these two APIs will provide the detail needed to properly analyze and report on your Zoom Phone call data.