Chat session metadata

This document explains the JSON schema used to structure metadata for customer support chat interactions. This schema helps ensure data consistency and facilitates effective management and analysis of chat data.

Chat session metadata schema

This schema describes the information we collect about each customer support chat session. The key components are described in the following sections.

Core information

These properties capture the core information of a chat session:

• id (integer). A unique identifier for each chat session. This is the primary key.

• lang (string): the ISO 689 language code used in the chat. For example — en for English, es for Spanish.

• chat_type (string). The type of chat, using a legacy set of types. Examples include "Messaging Inbound (App Chat)", "Messaging (SMS)", and "Messaging (WhatsApp)".

• session_type (string): a duplicate of chat_type

• session_type_v2 (string). The type of chat, using the current set of types. This may include refinements like "Messaging Inbound (Mobile Chat)".

• status (string). The current status of the chat. Possible values include queued, assigned, finished, no_response, canceled, and failed.

• sub_status (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 timestamp when the chat session was created

• assigned_at (string, date-time, or null): the timestamp when the chat was assigned to an agent, or null if not assigned

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

• `updated_at (string, date-time): the timestamp when the chat data was last updated

• first_msg_sent_at (string, date-time): the timestamp when the first message was sent in the chat

• last_msg_sent_at (string, date-time): the timestamp when the last message was sent in the chat

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

• chat_duration (integer): the total duration of the chat, in seconds

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

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

• has_feedback (boolean): indicates whether the customer provided feedback after the chat

• 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 chat interaction (false)

• fail_reason (string): the reason for any failure during the chat. Examples include no_response, expired, and end_user_opt_out.

• provider_type (string): the type of chat provider used. For example — unknown, messaging, twilio_conversations.

• message_count (integer): the total number of messages exchanged in the chat

• average_response_time (integer): the average time it took for agents to respond during the chat, in seconds

• longest_response_time (string): the longest time it took for an agent to respond during the chat, in seconds

Agent and virtual agent information

These properties explain who or what handled the chat:

• 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 unique 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 unique ID.

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

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

Menu navigation

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

  • 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 — sms_menu or web_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 — "Support/Billing".

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

• queue_priority_level (integer): An integer representing the priority level of the chat's selected queue

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

Customer flags

• customer_flag (object or null): flags marking notable attributes of the customer

  • verified_customer (boolean): whether the customer has been externally flagged as verified

  • bad_actor (boolean): whether the customer has been externally flagged as a bad actor

  • repeat_customer (boolean): whether the customer has been externally flagged as a repeat customer

Media attachments

• photos (array): list of photos associated with the chat

  • id (integer): unique identifier for the photo

  • photo_type (string): The type of photo ("photo" or "screenshot")

  • url (integer): the storage URL of the photo

  • smart_action_type (array): the type of smart action associated with the photo

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

• videos (array): list of videos associated with the chat

  • id (integer): Unique identifier for the video

  • url (integer): the storage URL of the video

  • smart_action_type (array): the type of smart action associated with the video

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

Chat transfers

• transfers (array): list of transfers that occurred during the chat

  • id (integer): the identifier of the transfer

  • status (string): status of the transfer ("transferring", "transferred", "failed", "deflected")

  • fail_reason (string): reason for transfer failure, if applicable

  • created_at (string, date-time): timestamp when the transfer was created

  • assigned_at (string, date-time, or null): timestamp when the transfer was assigned

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

  • updated_at (string, date-time, or null): timestamp when the transfer was last updated

  • wait_duration (integer): wait duration during the transfer

  • answer_type_path (string): the type of answers for the 'from' and 'to' chats, respectively

  • from_menu_path (object or null): menu path of the menu from which the transfer originated

  • to_menu_path (object or null): menu path of the destination menu of the transfer, if applicable

  • from_agent (object or null): agent who initiated the transfer

  • to_agent (object or null): agent who received the transfer

  • from_queue_priority_level (integer): priority level of the originating queue

  • to_queue_priority_level (integer): priority level of the destination queue

Chat handling durations

• handle_durations (array): log data on each segment of the chat handled by an agent

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

  • agent_id (integer): identifier of the agent

  • acw_duration (integer): after chat work duration

  • chat_duration (integer): chat duration during this phase

  • menu_path_id (string or null): menu path ID

  • menu_path (string): menu path

  • lang (string): language used

  • transfer (boolean): whether a transfer occurred

  • transfer_id (string or null): transfer identifier

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

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

  • response_count (integer): number of agent responses

  • response_time_total (integer): total agent response time

  • response_time_max (integer): longest agent response time

  • response_time_avg (integer): average agent response time

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

Queue durations

• queue_durations (array): log data on each segment of the chat where the customer was waiting in a queue

  • id (integer): the identifier

  • agent_id (integer): agent identifier

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

  • lang (string): language

  • menu_path_id (integer): menu path identifier

  • menu_path (string): menu path

  • queue_duration (integer): queue duration

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

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

  • transfer (boolean): whether a transfer occurred

  • transfer_id (integer): transfer identifier

  • service_level_abandon_time_threshold (integer): service level abandonment threshold

  • service_level_event (string): service level event status

  • service_level_target_percent (integer): service level target percentage

  • service_level_target_time (integer): service level target time

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 chat was handled by a virtual agent

  • id (integer): the identifier

  • virtual_agent (object): virtual agent details

  • chat_duration (integer): duration of the segment

  • escalation_reason (string): reason for escalation

  • finish_reason (string): reason the interaction finished

  • response_count (integer): virtual agent response count

  • response_time_total (integer): total virtual agent response time

  • response_time_max (integer): longest virtual agent response time

  • response_time_avg (string): average virtual agent response time

  • 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 chat was transferred

  • transfer_id (integer): transfer event identifier

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

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

Consumer handling durations

• consumer_handle_durations (array): durations the consumer was in the chat

  • id (integer): identifier

  • chat_duration (integer): consumer segment duration

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

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

  • message_count (integer): number of consumer messages

  • response_count (integer): number of consumer responses

  • response_time_total (integer): total consumer response time

  • response_time_max (integer): longest consumer response time

  • response_time_avg (integer): average consumer response time

Consumer event durations

• consumer_event_durations (array): details of consumer chat events. For example — CSAT, payment

  • id (integer): 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

Participants

• participants (array): information about each participant in the chat. For example &mdash: customer, agent, virtual agent)

  • id (integer): unique 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 chat

  • 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

  • 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

  • chat_id (integer): identifier for the chat

  • chat_duration (integer): chat duration for the participant

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

Offer events

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

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

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

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

Other details

• dismiss_duration (integer): duration the chat spent in the "dismissed" status

• answer_type (string or null): how the chat was answered ("manual" or "auto")

• inbound_number (string): inbound phone number

• outbound_number (string): outbound phone number

• after_hours (boolean): whether the chat was conducted after hours

• dispositions (array): dispositions recorded during the chat

• auto_session_summaries (array): automatically generated summaries of the session

• transfer_limit (object): transfer limit data for the chat

• 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 to define reusable components:

• menu_path: describes a hierarchical menu path

• agent: describes a human agent

• virtual_agent: describes a virtual agent