This document explains the schema of the chat transcript metadata record. This is the JSON file that Contact Center AI Platform (CCAI Platform) generates for a completed chat transcript. The chat transcript metadata record is produced by the chat-history JSON export and can be delivered through CRM transcript uploads and external-storage transcript files, depending on your instance configuration. Use this schema to parse transcript JSON, validate received payloads, or map transcript messages into downstream systems. ## Schema root The chat transcript metadata record is a single JSON object representing one chat transcript artifact. The fields at the root identify the communication, the transcript format version, and the ordered set of transcript entries. ### Communication identifiers `comm_type` and `comm_id` Together, `comm_type` and `comm_id` identify the communication that this transcript record represents. - `comm_type` identifies the communication type. The value is usually `chat`. It may be `call` for a voice call that includes blended SMS transcript content. - `comm_id` is the identifier of the chat or call represented by the transcript. ### Format version `transcript_version` Identifies the version of the JSON transcript format. Integrations should use this field for forward-compatible parsing and should ignore unrecognized fields. ### Entry discriminator - `entries[].type` and `entries[].body.type` Each item in `entries` represents one transcript message or event. The entry-level `type` field mirrors the message body type. The nested `body` object carries the payload whose shape varies by type - for example, `text`, `markdown`, `photo`, `noti`, or `action`. ## Chat transcript metadata schema This schema describes the data structure of chat transcripts. The following sections describe the core components. ### Core transcript information The following properties provide the fundamental information about the transcript itself: - `comm_type` (string): The communication type that the transcript represents. Possible values: `chat`, `call`. The value `call` indicates a voice call with blended SMS transcript content. - `comm_id` (integer): Unique identifier of the communication represented by the transcript. - `transcript_version` (string): Version of the transcript JSON format. The current value is `"1.0"`. See [Versioning and deprecations](https://docs.cloud.google.com/contact-center/ccai-platform/docs/chat-transcript-metadata#versioning-deprecations). - `assigned_at` (string, date-time): Timestamp when the chat was assigned. - `timezone` (string): Time zone for the transcript context, such as `"America/Los_Angeles"`. ### Transcript entries - `entries` (array): Ordered list of transcript entries. Each entry represents one message, notification, or action in the conversation. - `timestamp` (integer): Unix epoch timestamp, in seconds, when the system created the entry. - `type` (string): Message body type. This value mirrors `body.type`. See [Definitions](https://docs.cloud.google.com/contact-center/ccai-platform/docs/chat-transcript-metadata#definitions) for supported body types. - `body` (object): Entry payload. Its shape depends on the value of `type` / `body.type`. - `role` (string): Role of the participant or system component that produced the entry. Possible values: `end_user`, `agent`, `manager`, `virtual_agent`, `external_agent`, `task_virtual_agent`, `system`. - `user_data` (object): Sender metadata. For `agent`, `manager`, `virtual_agent`, `external_agent`, and `task_virtual_agent` entries, this object contains the sender's display data. For `end_user` and `system` entries, this object is empty. - `name` (string; present only when sender metadata is available): Display name of the sender. - `id` (integer; present only when sender metadata is available): Identifier of the sender. - `avatar_url` (string, uri; present only when sender metadata is available): URL of the sender's avatar image. ### Text message bodies - `text` (object): Plain text message body. - `type` (string): Always `text`. - `content` (string): Message text. - `lang` (string; present only when language metadata is available): Language code associated with the message. - `text_template` (object): Templated text message body. - `type` (string): Always `text_template`. - `content` (string): Template text. - `markdown` (object): Markdown-formatted message body. - `type` (string): Always `markdown`. - `content` (string): Markdown content. - `lang` (string; present only when language metadata is available): Language code associated with the message. - `markdown_template` (object): Templated Markdown message body. - `type` (string): Always `markdown_template`. - `content` (string): Markdown template content. ### Media and file message bodies - `photo` (object): Photo or screenshot message body. - `type` (string): Always `photo`. - `media_id` (integer): Identifier of the stored photo media. - `video` (object): Video message body. - `type` (string): Always `video`. - `media_id` (integer; present when the system stores the video as CCAI Platform media): Identifier of the stored video media. - `title` (string; present when an embedded video object represents the video): Title of the video. - `video` (object; present when an embedded video object represents the video): Video details. - `url` (string, uri): URL of the video. - `text` (string): Text alternative or fallback URL for the video. - `image` (object): Image message body. - `type` (string): Always `image`. - `title` (string; present when the message sender supplies it): Title of the image. - `image` (object): Image details. - `url` (string, uri): URL of the image. - `text` (string): Text alternative or fallback URL for the image. - `document` (object): Document message body. - `type` (string): Always `document`. - `media_id` (integer; present when the system stores the document as CCAI Platform media): Identifier of the stored document media. - `title` (string; present when an embedded document object represents the document): Title of the document. - `document` (object; present when an embedded document object represents the document): Document details. - `url` (string, uri): URL of the document. - `text` (string): Text alternative or fallback URL for the document. - `audio` (object): Audio message body. - `type` (string): Always `audio`. - `media_id` (integer; present when the system stores the audio as CCAI Platform media): Identifier of the stored audio media. - `title` (string; present when an embedded audio object represents the audio file): Title of the audio file. - `audio` (object; present when an embedded audio object represents the audio file): Audio details. - `url` (string, uri): URL of the audio file. - `text` (string): Text alternative or fallback URL for the audio file. ### Interactive message bodies - `inline_button` (object): Inline-button message body. - `type` (string): Always `inline_button`. - `title` (string): Title to display above the buttons. - `buttons` (array): List of button definitions. - `title` (string): Button label. - `action` (string): Action associated with the button. - `link` (string, uri; present only for link-style quick replies): URL associated with the button. - `sticky_button` (object): Sticky-button message body. - `type` (string): Always `sticky_button`. - `title` (string): Title to display above the buttons. - `buttons` (array): List of button definitions. - `title` (string): Button label. - `action` (string): Action associated with the button. - `link` (string, uri; present only for link-style quick replies): URL associated with the button. - `content_card` (object): Content-card message body. - `type` (string): Always `content_card`. - `cards` (array): List of content cards. - `title` (string): Card title. - `body` (string; present only when you configure card body text): Card body text. - `form_complete` (object): Form-completion message body that the client sends when a consumer completes, fails, or cancels a form. - `type` (string): Always `form_complete`. - `signature` (string; present only when the completion event contains a signature): Signature for the form-completion payload. - `data` (object): Form-completion details. - `status` (string): Completion status. Possible values: `success`, `error`, `cancelled`. - `smart_action_id` (integer): Identifier of the smart action associated with the form. - `timestamp` (string, date-time): Timestamp when the form-completion event occurred. This is distinct from the entry-level `timestamp`, which is an integer Unix epoch timestamp in seconds. - `details` (object; present only when the payload provides additional completion details): Additional status details. - `error_code` (string; present only for errors with a code): Error code associated with the completion result. - `message` (string): Human-readable status detail. ### Server-generated and passthrough message bodies - `server_message` (object): Server-generated message body. The transcript includes `server_message` entries only if you enable task virtual agent transcript content for your account; otherwise, the transcript omits these entries. Use this object when the transcript references a stored server-side message. - `type` (string): Always `server_message`. - `message_id` (integer): Identifier of the stored server message. - `visibility` (string or null): Visibility setting for the stored server message. - `passthrough` (object): A custom payload that the system passes through CCAI Platform for a virtual-agent or CCaaS integration. Your integration defines its `content`, which isn't part of the CCAI Platform schema; treat it as opaque. - `type` (string): Always `passthrough`. - `content` (string or object): Integration-defined payload. Its structure varies by integration, and CCAI Platform doesn't interpret it. ### Action message bodies - `action` (object): Action that a virtual agent or chatbot flow requests. The `action` field determines the action payload shape. - `type` (string): Always `action`. - `action` (string): Action type. Possible values include `escalation`, `deflection`, and `end`. - `escalation_reason` (string; present only when `action` is `escalation`): Reason the conversation escalated. - `menu_id` (integer; present only when `action` is `escalation`): Identifier of the menu to which the conversation should escalate. - `language` (string; present only when `action` is `escalation`): Language code of the destination queue. - `deflection_type` (string; present only when `action` is `deflection`): Type of deflection requested. - `sip_parameters` (object or null; present only when `action` is `deflection`): SIP parameters to forward as part of the deflection. ### Notification message bodies - `noti` (object): Notification message body. Notifications describe system events that occurred during the chat. - `type` (string): Always `noti`. - `event` (string): Notification event name. - `agent` (object; present only for events associated with a human agent): Agent associated with the event. - `id` (integer): Agent identifier. - `email` (string, email): Agent email address. - `name` (string): Agent display name. - `from_agent` (object; present only for transfer events with a source agent): Source agent for the event. - `id` (integer): Agent identifier. - `email` (string, email): Agent email address. - `name` (string): Agent display name. - `to_agent` (object; present only for transfer or escalation events with a destination human agent): Destination human agent for the event. - `id` (integer): Agent identifier. - `email` (string, email): Agent email address. - `name` (string): Agent display name. - `from_virtual_agent` (object; present only for escalation events from a virtual agent): Source virtual agent for the event. - `id` (integer): virtual-agent identifier. - `name` (string): virtual-agent display name. - `avatar_url` (string, uri, or null): URL of the virtual agent's avatar image. - `to_virtual_agent` (object; present only for transfer events to a virtual agent): Destination virtual agent for the event. - `id` (integer): virtual-agent identifier. - `name` (string): virtual-agent display name. - `avatar_url` (string, uri, or null): URL of the virtual agent's avatar image. - `target` (string; present only for transfer events): Destination type of the transfer. Possible values include `menu` and `agent`. - `status` (string; present only for events that carry a chat status): Chat status associated with the event. - `timeout` (boolean; present only for timeout-related events): Whether a timeout caused the event. - `memberIdentity` (string; present only for participant join or leave events): Identity of the participant. - `memberName` (string; present only for participant join or leave events): Display name of the participant. - `name` (string; present only for virtual-agent or task-va events): Display name associated with the event. - `reason` (string; present only for task-va completion events): Reason the task-va session ended. - `escalation_reason` (string; present only for escalation events): Reason for the escalation. - `deflection` (object; present only for deflection events): Deflection details. - `detail` (object; present only for custom notification events): Custom event detail. - `key` (string): Custom event key. - `data` (object): Custom event payload. #### Notification event names The `event` field identifies the notification event. The chat provider, which serves as the single source of truth, persists all notification events in the following list to the transcript JSON. The list groups these events by family. #### Smart-action requests - `verificationRequested` - `photoRequested` - `videoRequested` - `screenshotRequested` - `textRequested` - `cobrowseRequestedFromAgent` #### Smart-action outcomes - Finished: `photoFinished`, `videoFinished`, `screenshotFinished`, `textFinished` - Canceled: `photoCanceled`, `videoCanceled`, `screenshotCanceled`, `textCanceled` - Failed: `photoFailed`, `videoFailed`, `screenshotFailed`, `textFailed`, `verificationFailed` #### Verification - `endUserVerified` #### Co-browse - `cobrowseRequestedFromEndUser` - `cobrowseCodeGenerated` - `cobrowseStarted` - `cobrowseEnded` - `cobrowseFailed` #### Forms - `formRequested` - `formSent` - `formCompleted` #### Transfers - `transferStarted` - `transferAccepted` - `transferFailed` #### Virtual-agent escalations - `escalationStarted` - `escalationAccepted` - `escalationDeflected` - `escalationFailed` #### Task virtual agent - `taskVaStarted` - `taskVaFinished` #### Membership - `agentJoined` - `memberJoined` - `memberLeft` #### Session lifecycle - `chatEnded` - `chatEndedWithPostSession` - `chatDismissed` - `chatReactivated` - `checkInRequired` - `checkInTimedOut` - `transcriptRequested` - `transcriptUpdated` #### Custom - `custom` For records with `comm_type` set to `call`, additional call-transcript notification events may appear. These events are associated with call or Agent Assist transcript handling rather than the ordinary chat event families. ## Definitions The following sub-schemas appear in the chat transcript metadata document. This section defines each sub-schema once; property groups that reference them point back to this section rather than redefining their shape inline. ### entry (object) Represents one transcript message, notification, or action. Each entry has a Unix-epoch `timestamp`, a top-level `type`, a `body` object whose type matches that shape, a sender `role`, and a `user_data` object. See [Transcript entries](https://docs.cloud.google.com/contact-center/ccai-platform/docs/chat-transcript-metadata#transcript-entries) for the full list of fields. ### user_data (object) Describes the sender of a transcript entry when sender metadata is available. Agent, manager, virtual-agent, external-agent, and task-virtual-agent entries can carry `name`, `id`, and `avatar_url`. Consumer and system entries carry an empty object. ### message body (object, oneOf) The `body` object on each entry uses the value of `body.type` to select one of the supported message-body shapes. Supported body types include text bodies, media or file bodies, interactive bodies, server-generated bodies, action bodies, and notification bodies. See [Text message bodies](https://docs.cloud.google.com/contact-center/ccai-platform/docs/chat-transcript-metadata#text-message-bodies) through [Notification message bodies](https://docs.cloud.google.com/contact-center/ccai-platform/docs/chat-transcript-metadata#notification-message-bodies) for the full list of documented variants. ### participant role (string, enum) Identifies the sender category for a transcript entry. #### Allowed values - `end_user` - The consumer. - `agent` - A human agent. - `manager` - A manager participant. - `virtual_agent` - A virtual agent. - `external_agent` - An external agent participant. - `task_virtual_agent` - A task virtual agent. - `system` - A system-generated entry. ## Versioning and deprecations The chat transcript metadata document supports backward-compatible schema evolution. The system may add new fields and message-body variants over time, and integrations should disregard any unrecognized keys to ensure continued functionality. ### Current format version - `transcript_version` (string) - Current value: `"1.0"`. Integrations should parse the transcript based on the fields present in the payload and shouldn't fail if future versions add new fields or message-body types. ### Unknown message-body types When a transcript entry contains an unrecognized `type` or `body.type`, preserve the raw entry if possible and continue parsing the rest of the transcript. The system may add new message-body types without changing the meaning of existing fields. ### Deprecated fields This document does not list any deprecated fields for the chat transcript metadata record.