Chat transcript metadata

This document explains the JSON schema used to structure metadata for chat transcripts. This schema is necessary for accurately representing and processing chat conversations.

Chat transcript metadata schema

This schema describes the data structure data of chat transcripts. The core components are described in the following sections:

Core transcript information

The following properties provide the fundamental information about the transcript itself:

• comm_type (string). The type of communication this transcript belongs to. It can be chat or call for calls with blended SMS functionality.

• comm_id (integer). An identifier for the communication, for example — chat or call to which this transcript is related.

• transcript_version (string). The version of the transcript format. This is required for backward compatibility when parsing transcripts.

• assigned_at (string, date-time). The timestamp for when the chat was assigned.

• timezone (string). The timezone in which the chat was conducted.

Message Definitions

The definitions section contains reusable schema components that define the structure of different message types within the transcript. This provides flexibility in handling various content formats:

• text (object): represents a text message

  • type (string): must be "text"

  • content (string): the actual text content of the message

  • lang (string): the language of the text content

• text_template (object): represents a templated text message

  • type (string): must be text_template

  • content (string): the text template content, which might include placeholders

• markdown (object): represents a message using Markdown formatting

  • type (string): must be Markdown

  • content (string): the Markdown template content

• markdown_template (object): represents a templated Markdown message

  • type (string): must be markdown_template.

  • content (string): the Markdown template content, possibly with placeholders

• photo (object): represents a message containing a photo

  • type (string): must be photo

  • media_id (integer): the ID of the media file for the photo

• video (object): represents a message containing a video

  • title (string): title of the video

  • video (object): details about the video

    • url (string): URL of the video

    • text (string): text alternative to the video URL

  • media_id (integer): media ID to retrieve the video URL if not directly provided

• image (object): represents a message containing an image

  • title (string): title of the image

  • image (object): details about the image

    • url (string): URL of the image

    • text (string): text alternative to the image URL

• document (object): represents a message containing a document

  • title (string): title of the document

  • document (object): details about the document

    • url (string): URL of the document.

    • text (string): text alternative to the document URL

• inline_button (object): represents a set of inline buttons

  • title (string): title of the inline button set

  • buttons (array): array of button objects

    • title (string): title of the button

    • action (string): name of the action indicated by the button

    • link (string): URL link for quick reply link actions

• sticky_button (object): represents a set of sticky buttons

  • title (string): title of the sticky button set

  • buttons (array): array of button objects

    • title (string): title of the button

    • action (string): name of the action indicated by the button

    • link (string): URL link for quick reply link actions

• content_card (object): represents a content card

  • cards (array): array of content card objects

    • title (string): title of the content card

    • body (string): body text of the content card

• server_message (object): represents a message retrieved from the server

  • message_id (integer): ID of the stored server message

  • content (string): content of the message retrieved from the server

• action (object): represents an action taken during the chat. It can be one of the following:

  • action_escalation (object): represents an escalation action

    • action (string): must be "escalation"

    • escalation_reason (string): the reason for the escalation.

    • menu_id (integer): the ID to which the communication should be escalated

    • language (string): ISO 689 language code of the queue to which to escalate

  • action_deflection (object): represents a deflection action

    • action (string): must be deflection

    • deflection_type (string): the type of deflection

    • sip_parameters (object or null): SIP parameters to forward as part of the deflection, if present

  • action_end (object): represents an end action

    • action (string): must be end

• noti (object): represents a notification message. It can be one of various notification types:

  • noti_transfer_started (object): notification for a transfer starting.

    • type (string): must be noti

    • event (string): must be "transferStarted"

    • target (string): the target destination of the transfer, for example — menu or agent.

    • agent (object): the agent that started the transfer

      • id (integer): ID of the agent

      • email (string): email of the agent

      • name (string): name of the agent

  • noti_verification_requested (object): notification for a verification request

  • type (string): must be noti

  • event (string): must be verificationRequested

  • agent (object): the agent requesting verification

    • id (integer): ID of the agent requesting verification

    • email (string): email of the agent requesting verification

    • name (string): name of the agent requesting verification

  • noti_end_user_verified (object): notification for when an end-user is verified

    • type (string): must be noti

    • event (string): must be endUserVerified

  • Other noti_\* types define notifications for various events like photo requests, video requests, cobrowsing events, task virtual agent events, agent joining, and transfer or escalation status changes.

  • noti_custom (object): represents a custom notification.

    • type (string): must be noti

    • event (string): must be custom

    • detail (object): custom event details

    • key (string): key representing the custom event detail

    • data (object): custom defined event payload

Transcript entries

• entries (array): An array of objects, where each object represents an individual message sent in the chat.

  • timestamp (string): the timestamp when the message was sent

  • type (string): the type of message, referencing one of the definitions described earlier, for example — text, photo, noti.

  • body (object): the content of the message, conforming to the structure defined by the message's type. It uses oneOf to allow for different body types.

  • role (string): the role of the participant who sent the message. Possible values include end_user, agent, manager, virtual_agent, external_agent, task_virtual_agent, system.

  • user_data (object): data for the user who sent the message, unless it's an end_user or system message.

    • name (string): the user's name

    • id (integer): the user's unique ID

  • avatar_url (string): storage URL for the user's avatar