A Detailed Look at Call Records

In this article, we will explain the meaning of the records related to calls from API and Webhooks and what to pay attention to.

In this article, we will examine the call records you can access via the Hipcall API and webhooks. With the API and webhooks, you can obtain a lot of detailed information about calls. To make this information more understandable, we will present it to you by categorizing it.

Unique Identifier for Calls

  • Calls can be retrieved from the uuid field, which is a unique identifier.

Call Details

For information about the direction and parties of the call, the following data can be used:

1. Call Direction

  • direction: Indicates the direction of the call relative to your users. Possible values:

    • outbound: Calls initiated by your users.
    • inbound: Calls made to you.
    • internal: Conversations between users within the system.

  • number_id: The record number of the associated phone number for the call.

2. Caller

  • caller_number: The number that initiated the call, in E.164 format.

  • caller_type: The type of the party that initiated the call:

    • For outbound calls: user.
    • For inbound calls: contact.
    • Note: In later versions of Hipcall, new types may be added.

  • caller_id: The record number of the caller type in the system.

    • Example: In an outbound call where caller_type = user, this caller_id is the ID of the user who initiated the call.

3. Callee

  • callee_number: The dialed number for the call, in E.164 format.

  • callee_type: Indicates the type of the called endpoint. Possible values:

    • contact: A person saved in the address book or any E.164 number.
    • user: Hipcall users (your teammates).
    • greeting: IVR, i.e., the welcome menu.
    • team: Teams (queue).
    • voicemail: Voicemail.
    • smart_ivr: Smart routing.
    • speed_dial: Speed dial.
    • external_manager: External management.
    • hangup: Call termination.

  • Note:

    • In calls of type contact and hangup, callee_id may be empty. This happens because there is no need to record them in the system.
    • hangup represents a general action; contact represents people not yet saved in the address book.

  • callee_id: The record number of the relevant entity in the system from the types listed above.

4. User Information

  • user_id: The record number of the user who answered the call or completed the last conversation. Especially in calls coming through teams, this field indicates which of your users handled the call.
  • channel_type: Currently, this only comes as number. It indicates that the call was initiated from a number belonging to you. In the future, when Hipcall starts receiving calls from different channels, new types will be added to this field.

Address Book Information

Related address book information can be obtained with the following two data points:

  • related_type: Comes as either company or contact.

    • company: Company.
    • contact: Person.

  • related_id: The record number of the relevant individual or institution from the types above.

Call Recording Information

  • record_url: Returns a temporary URL. This URL:

    • Must be used within 4 hours after the request.
    • If it will be stored long-term, one should remember that the URL’s validity period will expire, and the recording must be stored in the system.
    • Alternatively, a new URL should be requested whenever needed.

Callback Information

If a call has a missed call status, the details of the callback for this call are contained in the fields below. However, since webhooks are received at the end of the call, these fields will generally be empty in practice. Nonetheless, when accessed via the API, you can reach the callback information that was created after the call.

  • callback_user_id: The record number of the user who returned the call.
  • callback_time: Indicates how many seconds later the callback was made. Expressed as an integer representing the difference in seconds.
  • callback_cdr_uuid: The unique UUID information of the call made for the callback.

Statistics Fields

  • started_at: The call start time in ISO 8601 format.

  • bridged_at: The time in ISO 8601 format when the call was bridged to a user.

  • answered_at: The time in ISO 8601 format when the call was answered.

    • Note: It can differ from bridged_at because the call might have been answered by IVR or a team endpoint.

  • ended_at: The time in ISO 8601 format when the call ended.

Missed Calls and Reasons

  • missing_call: If a call could not connect to any of your users, this field comes as true. This field can be used to detect missed calls.

  • missing_call_reason: The system specifies the reason for missed calls:

    • out_of_business_hours: Call received outside business hours.
    • short_abandoned: Short-duration calls. You can define this duration in your account settings (Default: 3 seconds).
    • abandoned: Call abandoned by the caller.
    • callback: Call delivered with a callback request from someone waiting in the queue.
    • denylist: Call blocked by the denylist.

Call Durations

  • first_touch_duration: Indicates how long the call waited in the system before a conversation with a user began. It can be used to analyze how quickly your call center connects callers to staff.
  • call_duration: The total duration of the call.

Termination Information

  • hangup_by: Indicates who terminated the call:

    • Possible values: user, contact, system.

Voicemail Information

If the call ended with a voicemail, the following fields will be returned:

  • voicemail_url: Temporary URL information for the audio file.

  • voicemail_id: The record number of the voicemail box.

  • voicemail_type: The type of the voicemail box:

    • Possible values: user or account.