Call session metadata

This document provides an explanation of the JSON schema used to structure metadata for call sessions. This schema is crucial for accurately representing and processing call sessions.

Call session metadata schema

This schema describes the structure of data related to call session metadata. The key components are described in the following sections.

Core information

These properties capture the core information of the call:

  • id (integer). The identifier for each call session. This is the primary key that distinguishes one call from another.

  • lang (string). The ISO 689 language code used during the call, for example — en for English or es for Spanish. This is crucial for language-specific analysis and reporting.

  • call_type (string). The type of call, using a legacy set of types. Examples include — Voice Inbound (App), Voice Outbound, and Voice Internal. This helps categorize calls based on their origin and purpose.

  • session_type (string): a duplicate of call_type

  • session_type_v2 (string). The type of call, using the current set of types. This is similar to call_type but may include more granular distinctions, like Voice Inbound (Mobile) or Voice Inbound (IVR using Mobile).

  • status (string). The current status of the call. Possible values include scheduled, queued, connected, finished, failed, and deflected. This tracks the call's progression through its lifecycle.

  • subStatus(string). Provides a more detailed status of the call. Possible values include waiting_for_agent, in_queue, and connected_with_agent.

  • created_at (string, date-time): the precise timestamp when the call record was created

  • queued_at (string, date-time, or null): the timestamp when the call entered the queue, or null if it was never queued

  • assigned_at (string, date-time, or null): the timestamp when the call was assigned to an agent, or null if it wasn't assigned

  • connected_at (string, date-time, or null): the timestamp when the call was successfully connected

  • ends_at (string, date-time, or null): the timestamp when the call ended

  • scheduled_at (string, date-time, or null): the timestamp when the call was scheduled, or null if it was an immediate call

  • updated_at (string, date-time): the timestamp when the call data was last modified

  • wait_duration (integer): the total time the customer spent waiting, in seconds

  • call_duration (integer): the total duration of the call, in seconds

  • hold_duration (integer): the total time the customer was placed on hold, in seconds, or null if there was no hold time

  • rating (integer or null): the customer satisfaction (CSAT) rating provided by the customer, or null if no rating was given

  • has_feedback (boolean): a flag indicating whether the customer provided feedback after the call

  • voip_provider (string): the VoIP provider used for the call. This field is deprecated and will always return deprecated.

  • out_ticket_id (string): the identifier of the ticket created in the external CRM system

  • out_ticket_url (string, uri): the URL of the CRM ticket

  • is_out_ticket_account (boolean): indicates whether the CRM ticket represents a customer (true) or a call interaction (false)

  • verified (boolean): indicates if the interaction was verified through the verification smart action

  • recording_url (string, uri, or null): the URL of the call recording, or null if no recording is available

  • recording_permission (string). The status of the customer's recording permission. Possible values include not_asked, granted, or denied.

  • voicemail_reason (string). The reason a voicemail was left, if applicable. Options include not_voicemail, temporary_redirection, and after_hour_deflection.

Agent and virtual agent information

These sections explain who or what handled the call:

  • agent_info (object). This field can hold information about either a human agent or a virtual agent. It uses the one of keyword to specify that it can be one of two types.

    • agent (object): information about the human agent:

      • id (integer): the agent's ID

      • agent_number (string or null): an identifier assigned to the agent

      • email (string, email): the agent's email address

      • name (string): the agent's full name

      • last_name (string): the agent's last name

      • first_name (string): the agent's first name

      • avatar_url (string, uri): the URL of the agent's avatar image

    • virtual_agent (object): information about the virtual agent:

      • id (integer): the virtual agent's ID

      • name (string): the virtual agent's name

      • avatar_url (string, uri): the URL of the virtual agent's avatar image

  • selected_menu (object or null): information about the menu the customer selected during the call

    • id (integer): the ID of the menu

    • name (string): the name of the menu

    • parent_id (integer or null): the ID of the parent menu, if any

    • position (integer): the menu position relative to other menus at the same level

    • deleted (boolean): whether the menu has been deleted

    • menu_type (string): the type of menu. For example — ivr_menu or sms_menu.

    • hidden (boolean): whether the menu is visible and available for use

  • menu_path (object or null): describes the hierarchical path of menus the customer navigated

    • items_count (integer): the number of menus in the path

    • name (string): a slash-separated string of menu names. For example — dupport or billing.

    • materialized_path (string): a slash-separated string of menu IDs

End-user details

  • end_user (object): information about the customer

    • id (integer): the customer's internal ID

    • identifier (string or null): an external identifier for the customer

    • out_contact_id (string or null): the customer's ID in the CRM

Call deflection

  • deflection (string): indicates if and how the call was deflected. For example — no_deflection, over_cap_phone, after_hours_voicemail.

  • deflection_details (array): provides a detailed log of deflections that occurred during the call. Each entry includes:

    • id (integer): the identifier for the deflection log record

    • call_id (integer): the identifier of the call

    • transfer_id (integer or null): the identifier of the transfer associated with the deflection, if applicable

    • deflection (string): the type of deflection

    • created_at (string, date-time): timestamp when the deflection occurred

    • from_menu_path (object or null): menu path from which the call was deflected

    • to_menu_path (object or null): menu path to which the call was deflected

    • to_sip_uri (string or null): SIP URI to which the call was deflected, if applicable

    • to_sip_headers (object): SIP headers with which the call was deflected, if applicable

Call handling durations

  • handle_durations (array): an array of objects, each representing a segment of the call handled by an agent. This is useful for analyzing agent handling time.

    • id (integer): the identifier for the handle duration

    • agent_id (integer): ID of the agent

    • acw_duration (integer): after call work duration

    • bcw_duration (integer): before call work duration

    • call_duration (integer): call duration during this segment

    • menu_path_id (string or null): ID of the menu path

    • menu_path (string): name of the menu path

    • lang (string): language used

    • barged (boolean): whether the call was barged in on

    • transfer (boolean): whether a transfer occurred

    • transfer_id (string or null): ID of the transfer

    • transfer_cold (boolean or null): whether the transfer was cold

    • started_at (string, date-time): start timestamp

    • ended_at (string, date-time): end timestamp

    • scheduled_at (string, date-time, or null): scheduled timestamp

    • hold_duration (integer or null): hold duration during this segment

    • assigned_connection_duration (integer): duration the end user waited while the agent was connected during this phase

    • session_breakthrough (object): details on assignment of the call breaking through an agent's unavailable status, if applicable

Queue durations

  • queue_durations (array): an array of objects, each representing a segment of the call where the customer was in a queue. This is crucial for analyzing wait times and service levels.

    • id (integer): the identifier for the queue duration

    • agent_id (integer): ID of the agent

    • ended_at (string, date-time): end timestamp

    • lang (string): language used

    • menu_path_id (integer): ID of the menu path

    • menu_path (string): name of the menu path

    • queue_duration (integer): duration of the queue segment

    • started_at (string, date-time): start timestamp

    • transfer_cold (boolean): whether the call was cold transferred

    • transfer (boolean): whether a transfer occurred

    • transfer_id (integer): ID of the transfer

    • service_level_abandon_time_threshold (integer): time threshold for service level abandonment

    • service_level_event (string): service level event status. For example — excluded, in_sla, not_in_sla.

    • service_level_target_percent (integer): target percentage for service level compliance

    • service_level_target_time (integer): target time for service level compliance

Virtual agent escalations

  • virtual_agent_deflected_escalations (array): details of escalations from virtual agents that were deflected

    • id (integer): the identifier

    • deflection (string): deflection type

    • escalation_id (integer): escalation event identifier

    • escalation_reason (string): reason for escalation

    • escalated_at (string, date-time): escalation timestamp

    • menu_path_id (integer): menu path ID

    • menu_path (string): menu path

    • lang (string): language

    • virtual_agent (object): virtual agent details

Virtual agent handling durations

  • virtual_agent_handle_durations (array): segments of time the call was handled by a virtual agent

    • id (integer): the identifier

    • virtual_agent (object): virtual agent details

    • call_duration (integer): duration of the segment

    • escalation_reason (string): reason for escalation

    • finish_reason (string): reason the interaction finished

    • sentiment (integer): end-user sentiment

    • response_count (integer): virtual agent response count

    • fallback_response_count (integer): fallback response count

    • initiated_by (string): how the virtual agent session was initiated

    • menu_path_id (integer): menu path ID

    • menu_path (string): menu path

    • lang (string): language

    • transfer (boolean): whether the call was transferred

    • transfer_id (integer): transfer event identifier

    • started_at (string, date-time): start timestamp

    • ended_at (string, date-time): end timestamp

End-user handling durations

  • consumer_handle_durations (array): durations the end-user was on the call

    • id (integer): the identifier

    • call_duration (integer): end-user segment duration

    • hold_duration (integer): end-user hold duration

    • started_at (string, date-time): start timestamp

    • ended_at (string, date-time): end timestamp

End-user event durations

  • consumer_event_durations (array): details of end-user call events. For example — CSAT or payment.

    • id (integer): the identifier

    • duration (integer): event duration

    • type (string): event type

    • event (string): event outcome

    • menu_path_id (integer): menu path ID

    • menu_path (string): menu path

    • lang (string): language

    • started_at (string, date-time): start timestamp

    • ended_at (string, date-time): end timestamp

End-user in-menu durations

  • consumer_in_menu_durations (array): durations of end-user interactions within menus

    • id (integer): the identifier

    • duration (integer): duration within the menu

    • event (string): menu interaction outcome

    • menu_path_id (integer): menu path ID

    • menu_path (string): menu path

    • lang (string): language

    • started_at (string, date-time): start timestamp

    • ended_at (string, date-time): end timestamp

Participants

  • participants (array): information about each participant in the call. For example — customer, agent, virtual agent.

    • id (integer): the identifier for the participant

    • type (string): type of participant. For example — end_user, agent, virtual_agent, etc.

    • entry_type (string): how the participant entered the call

    • user_id (integer or null): user ID if the participant is an agent

    • end_user_id (integer or null): end-user ID if the participant is the customer

    • virtual_agent_id (integer or null): virtual agent ID if the participant is a virtual agent

    • virtual_agent_params (object): custom metadata used by the virtual agent

    • status (string): status of the participant. For example — waiting, connected, finished, etc.

    • fail_reason (string): reason for failure, if any

    • connected_at (string, date-time): timestamp when the participant connected

    • phone_number (string): phone number of the participant

    • call_id (integer): identifier for the call

    • call_duration (integer): call duration for the participant

    • hold_duration (integer or null): hold duration for the participant

    • ended_at (string, date-time): timestamp when the participant's involvement ended

    • adapter_fail_code (integer or null): numeric code corresponding to fail reason

    • adapter_fail_message (string or null): human-readable description of fail_reason, if available.

Recordings

  • recordings (array): information about call recordings

    • id (integer): the identifier for the recording

    • call_id (integer): call identifier

    • conference_sid (string): VoIP provider's call identifier

    • duration (integer): recording duration

    • recording_type (string): type of recording

    • redaction_times (array): time segments that were redacted

    • started_at (string, date-time): recording start timestamp

Offer events

  • offer_type (string or null): manner in which the call was offered to the agent

  • offer_events (array): events where the call was offered to agents

    • casting_time (date-time): time the call was offered

    • group (string): Group to which the call was offered

Other details

  • answer_type (string or null): how the call was answered. For example — manual or auto.

  • outbound_number (string): outbound phone number used

  • wait_time_sms (array): wait time SMS interactions

  • in_call_sms (array): SMS interactions during the call

  • dispositions (array): dispositions recorded during the call

  • email (string, email, or null): customer's email address

  • feedback (string or null): customer feedback

  • smart_action_text (string or null): text of any smart action taken

  • custom_data_secured (object or null): custom, securely signed data

  • custom_data_not_secured (object or null): custom, non-securely signed data

Key definitions

The schema also includes a definitions section, which defines reusable schema components:

  • menu_path: a hierarchical menu path

  • agent: a human agent

  • virtual_agent: a virtual agent

  • deflection: defines the possible deflection statuses