Metadados da transcrição do chat

Este documento explica o esquema do registro de metadados da transcrição do chat. Este é o arquivo JSON que a Contact Center AI Platform (CCAI Platform) gera para uma transcrição de chat concluída. O registro de metadados da transcrição do chat é produzido pela exportação JSON do histórico de chat e pode ser entregue por uploads de transcrição do CRM e arquivos de transcrição de armazenamento externo, dependendo da configuração da sua instância. Use esse esquema para analisar o JSON da transcrição, validar os payloads recebidos ou mapear mensagens de transcrição em sistemas downstream.

Raiz do esquema

O registro de metadados da transcrição de chat é um único objeto JSON que representa um artefato de transcrição de chat. Os campos na raiz identificam a comunicação, a versão do formato da transcrição e o conjunto ordenado de entradas de transcrição.

Identificadores de comunicação comm_type e comm_id

Juntos, comm_type e comm_id identificam a comunicação que este registro de transcrição representa.

  • comm_type identifica o tipo de comunicação. O valor geralmente é chat. Pode ser call para uma chamada de voz que inclui conteúdo de transcrição de SMS combinados.

  • comm_id é o identificador do chat ou da ligação representada pela transcrição.

Versão do formato transcript_version

Identifica a versão do formato de transcrição JSON. As integrações precisam usar esse campo para análise compatível com versões futuras e ignorar campos não reconhecidos.

Discriminador de entrada: entries[].type e entries[].body.type

Cada item em entries representa uma mensagem ou um evento de transcrição. O campo type de nível básico reflete o tipo de corpo da mensagem. O objeto body aninhado carrega o payload, cujo formato varia de acordo com o tipo, por exemplo, text, markdown, photo, noti ou action.

Esquema de metadados de transcrição do chat

Esse esquema descreve a estrutura de dados das transcrições de chat. As seções a seguir descrevem os componentes principais.

Principais informações da transcrição

As propriedades a seguir fornecem as informações fundamentais sobre a transcrição:

  • comm_type (string): o tipo de comunicação que a transcrição representa. Valores possíveis: chat, call. O valor call indica uma chamada de voz com conteúdo de transcrição de SMS combinado.

  • comm_id (número inteiro): identificador exclusivo da comunicação representada pela transcrição.

  • transcript_version (string): versão do formato JSON da transcrição. O valor atual é "1.0". Consulte Controle de versões e descontinuações.

  • assigned_at (string, data/hora): carimbo de data/hora em que o chat foi atribuído.

  • timezone (string): fuso horário do contexto da transcrição, como "America/Los_Angeles".

Entradas de transcrição

  • entries (matriz): lista ordenada de entradas de transcrição. Cada entrada representa uma mensagem, notificação ou ação na conversa.

    • timestamp (número inteiro): carimbo de data/hora da época Unix, em segundos, quando o sistema criou a entrada.

    • type (string): tipo do corpo da mensagem. Esse valor reflete body.type. Consulte Definições para ver os tipos de corpo compatíveis.

    • body (objeto): payload de entrada. A forma depende do valor de type / body.type.

    • role (string): função do participante ou do componente do sistema que produziu a entrada. Valores possíveis: end_user, agent, manager, virtual_agent, external_agent, task_virtual_agent, system.

    • user_data (objeto): metadados do remetente. Para entradas agent, manager, virtual_agent, external_agent e task_virtual_agent, esse objeto contém os dados de exibição do remetente. Para entradas end_user e system, esse objeto está vazio.

      • name (string; presente apenas quando os metadados do remetente estão disponíveis): nome de exibição do remetente.

      • id (número inteiro; presente apenas quando os metadados do remetente estão disponíveis): identificador do remetente.

      • avatar_url (string, uri; presente apenas quando os metadados do remetente estão disponíveis): URL da imagem do avatar do remetente.

Corpos de mensagens de texto

  • text (objeto): corpo da mensagem de texto simples.

    • type (string): sempre text.

    • content (string): texto da mensagem.

    • lang (string; presente apenas quando os metadados de idioma estão disponíveis): código do idioma associado à mensagem.

  • text_template (objeto): corpo da mensagem de texto com modelo.

    • type (string): sempre text_template.

    • content (string): texto do modelo.

  • markdown (objeto): corpo da mensagem formatado em Markdown.

    • type (string): sempre markdown.

    • content (string): conteúdo em Markdown.

    • lang (string; presente apenas quando os metadados de idioma estão disponíveis): código do idioma associado à mensagem.

  • markdown_template (objeto): corpo da mensagem em Markdown com modelo.

    • type (string): sempre markdown_template.

    • content (string): conteúdo do modelo do Markdown.

Corpos de mensagens de mídia e arquivos

  • photo (objeto): corpo da mensagem com foto ou captura de tela.

    • type (string): sempre photo.

    • media_id (número inteiro): identificador da mídia de foto armazenada.

  • video (objeto): corpo da mensagem de vídeo.

    • type (string): sempre video.

    • media_id (inteiro; presente quando o sistema armazena o vídeo como mídia da CCAI Platform): identificador da mídia de vídeo armazenada.

    • title (string; presente quando um objeto de vídeo incorporado representa o vídeo): título do vídeo.

    • video (objeto; presente quando um objeto de vídeo incorporado representa o vídeo): detalhes do vídeo.

      • url (string, uri): URL do vídeo.

      • text (string): texto alternativo ou URL de substituição do vídeo.

  • image (objeto): corpo da mensagem com imagem.

    • type (string): sempre image.

    • title (string; presente quando o remetente da mensagem fornece): título da imagem.

    • image (objeto): detalhes da imagem.

      • url (string, uri): URL da imagem.

      • text (string): alternativa de texto ou URL de substituição para a imagem.

  • document (objeto): corpo da mensagem do documento.

    • type (string): sempre document.

    • media_id (inteiro; presente quando o sistema armazena o documento como mídia da CCAI Platform): identificador da mídia do documento armazenado.

    • title (string; presente quando um objeto de documento incorporado representa o documento): título do documento.

    • document (objeto; presente quando um objeto de documento incorporado representa o documento): detalhes do documento.

      • url (string, uri): URL do documento.

      • text (string): texto alternativo ou URL de substituição do documento.

  • audio (objeto): corpo da mensagem de áudio.

    • type (string): sempre audio.

    • media_id (número inteiro; presente quando o sistema armazena o áudio como mídia da plataforma CCAI): identificador da mídia de áudio armazenada.

    • title (string; presente quando um objeto de áudio incorporado representa o arquivo de áudio): título do arquivo de áudio.

    • audio (objeto; presente quando um objeto de áudio incorporado representa o arquivo de áudio): detalhes do áudio.

      • url (string, uri): URL do arquivo de áudio.

      • text (string): texto alternativo ou URL de substituição para o arquivo de áudio.

Corpos de mensagens interativas

  • inline_button (objeto): corpo da mensagem do botão inline.

    • type (string): sempre inline_button.

    • title (string): título a ser exibido acima dos botões.

    • buttons (matriz): lista de definições de botões.

      • title (string): rótulo do botão.

      • action (string): ação associada ao botão.

      • link (string, uri; presente apenas para respostas rápidas no estilo link): URL associado ao botão.

  • sticky_button (objeto): corpo da mensagem do botão fixo.

    • type (string): sempre sticky_button.

    • title (string): título a ser exibido acima dos botões.

    • buttons (matriz): lista de definições de botões.

      • title (string): rótulo do botão.

      • action (string): ação associada ao botão.

      • link (string, uri; presente apenas para respostas rápidas no estilo link): URL associado ao botão.

  • content_card (objeto): corpo da mensagem do card de conteúdo.

    • type (string): sempre content_card.

    • cards (matriz): lista de cards de conteúdo.

      • title (string): título do card.

      • body (string; presente apenas quando você configura o texto do corpo do card): texto do corpo do card.

  • form_complete (objeto): corpo da mensagem de conclusão do formulário que o cliente envia quando um consumidor conclui, falha ou cancela um formulário.

    • type (string): sempre form_complete.

    • signature (string; presente apenas quando o evento de conclusão contém uma assinatura): assinatura do payload de conclusão do formulário.

    • data (objeto): detalhes do preenchimento do formulário.

      • status (string): status da conclusão. Valores possíveis: success, error, cancelled.

      • smart_action_id (número inteiro): identificador da ação inteligente associada ao formulário.

      • timestamp (string, data e hora): carimbo de data/hora em que o evento de conclusão do formulário ocorreu. Isso é diferente do timestamp básico, que é um carimbo de data/hora Unix inteiro em segundos.

      • details (objeto; presente apenas quando o payload fornece mais detalhes de conclusão): detalhes de status adicionais.

        • error_code (string; presente apenas para erros com um código): código de erro associado ao resultado da conclusão.

        • message (string): detalhe do status legível.

Corpos de mensagens gerados pelo servidor e de encaminhamento

  • server_message (objeto): corpo da mensagem gerado pelo servidor. A transcrição inclui entradas server_message somente se você ativar o conteúdo da transcrição do agente virtual de tarefas na sua conta. Caso contrário, a transcrição omite essas entradas. Use esse objeto quando a transcrição fizer referência a uma mensagem armazenada do lado do servidor.

    • type (string): sempre server_message.

    • message_id (número inteiro): identificador da mensagem armazenada no servidor.

    • visibility (string ou nulo): configuração de visibilidade da mensagem armazenada no servidor.

  • passthrough (objeto): uma carga útil personalizada que o sistema transmite pela plataforma CCAI para uma integração de agente virtual ou CCaaS. Sua integração define o content, que não faz parte do esquema da plataforma CCAI. Trate-o como opaco.

    • type (string): sempre passthrough.

    • content (string ou objeto): payload definido pela integração. A estrutura varia de acordo com a integração, e a Plataforma CCAI não a interpreta.

Corpos de mensagens de ação

  • action (objeto): ação solicitada por um agente virtual ou fluxo de chatbot. O campo action determina o formato do payload de ação.

    • type (string): sempre action.

    • action (string): tipo de ação. Os valores possíveis incluem escalation, deflection e end.

    • escalation_reason (string; presente somente quando action é escalation): motivo da escalonamento da conversa.

    • menu_id (inteiro; presente apenas quando action é escalation): identificador do menu para o qual a conversa deve ser encaminhada.

    • language (string; presente apenas quando action é escalation): código do idioma da fila de destino.

    • deflection_type (string; presente apenas quando action é deflection): tipo de evasão solicitada.

    • sip_parameters (objeto ou nulo; presente apenas quando action é deflection): parâmetros SIP para encaminhar como parte do desvio.

Corpos de mensagens de notificação

  • noti (objeto): corpo da mensagem de notificação. As notificações descrevem eventos do sistema que ocorreram durante o chat.

    • type (string): sempre noti.

    • event (string): nome do evento de notificação.

    • agent (objeto; presente apenas para eventos associados a um agente humano): agente associado ao evento.

      • id (inteiro): identificador do agente.

      • email (string, e-mail): endereço de e-mail do agente.

      • name (string): nome de exibição do agente.

    • from_agent (objeto; presente apenas para eventos de transferência com um agente de origem): agente de origem do evento.

      • id (inteiro): identificador do agente.

      • email (string, e-mail): endereço de e-mail do agente.

      • name (string): nome de exibição do agente.

    • to_agent (objeto; presente apenas em eventos de transferência ou encaminhamento com um agente humano de destino): agente humano de destino do evento.

      • id (inteiro): identificador do agente.

      • email (string, e-mail): endereço de e-mail do agente.

      • name (string): nome de exibição do agente.

    • from_virtual_agent (objeto; presente apenas para eventos de encaminhamento de um agente virtual): agente virtual de origem do evento.

      • id (número inteiro): identificador do agente virtual.

      • name (string): nome de exibição do agente virtual.

      • avatar_url (string, uri ou nulo): URL da imagem do avatar do agente virtual.

    • to_virtual_agent (objeto; presente apenas para eventos de transferência para um agente virtual): agente virtual de destino do evento.

      • id (número inteiro): identificador do agente virtual.

      • name (string): nome de exibição do agente virtual.

      • avatar_url (string, uri ou nulo): URL da imagem do avatar do agente virtual.

    • target (string; presente apenas para eventos de transferência): tipo de destino da transferência. Os valores possíveis incluem menu e agent.

    • status (string; presente apenas para eventos que têm um status de chat): status do chat associado ao evento.

    • timeout (booleano; presente apenas para eventos relacionados a tempo limite): indica se um tempo limite causou o evento.

    • memberIdentity (string; presente apenas em eventos de entrada ou saída de participantes): identidade do participante.

    • memberName (string; presente apenas em eventos de entrada ou saída de participantes): nome de exibição do participante.

    • name (string; presente apenas para eventos de agente virtual ou task-va): nome de exibição associado ao evento.

    • reason (string; presente apenas em eventos de conclusão de task-va): motivo do encerramento da sessão de task-va.

    • escalation_reason (string; presente apenas para eventos de encaminhamento): motivo do encaminhamento.

    • deflection (objeto; presente apenas para eventos de evasão): detalhes da evasão.

    • detail (objeto; presente apenas para eventos de notificação personalizados): detalhes do evento personalizado.

      • key (string): chave de evento personalizado.

      • data (objeto): payload de evento personalizado.

Nomes de eventos de notificação

O campo event identifica o evento de notificação. O provedor de chat, que serve como única fonte de verdade, mantém todos os eventos de notificação na lista a seguir no JSON da transcrição. A lista agrupa esses eventos por família.

Solicitações de ação inteligente

  • verificationRequested

  • photoRequested

  • videoRequested

  • screenshotRequested

  • textRequested

  • cobrowseRequestedFromAgent

Resultados de ações inteligentes

  • Concluído: photoFinished, videoFinished, screenshotFinished, textFinished

  • Cancelado: photoCanceled, videoCanceled, screenshotCanceled, textCanceled, cobrowseCanceled

  • Falha: photoFailed, videoFailed, screenshotFailed, textFailed, verificationFailed

Verificação

  • endUserVerified

Co-navegação

  • cobrowseRequestedFromEndUser

  • cobrowseCodeGenerated

  • cobrowseStarted

  • cobrowseEnded

  • cobrowseFailed

Formulários

  • formRequested

  • formSent

  • formCompleted

Transferências

  • transferStarted

  • transferAccepted

  • transferFailed

Encaminhamentos para um supervisor pelo agente virtual

  • escalationStarted

  • escalationAccepted

  • escalationDeflected

  • escalationFailed

Agente virtual de tarefas

  • taskVaStarted

  • taskVaFinished

Associação

  • memberJoined

  • memberLeft

Ciclo de vida da sessão

  • chatEnded

  • chatEndedWithPostSession

  • chatDismissed

  • checkInRequired

  • checkInTimedOut

  • transcriptRequested

  • transcriptUpdated

Personalizado

  • custom

Para registros com comm_type definido como call, outros eventos de notificação de transcrição de chamada podem aparecer. Esses eventos estão associados ao processamento de transcrições de chamadas ou do Agent Assist, e não às famílias de eventos de chat comuns.

Definições

Os subesquemas a seguir aparecem no documento de metadados da transcrição do chat. Esta seção define cada subesquema uma vez. Os grupos de propriedades que os referenciam apontam de volta para esta seção em vez de redefinir a forma deles inline.

entry (objeto)

Representa uma mensagem de transcrição, notificação ou ação. Cada entrada tem um timestamp da época Unix, um type de nível superior, um objeto body cujo tipo corresponde a esse formato, um role remetente e um objeto user_data. Consulte Entradas de transcrição para ver a lista completa de campos.

user_data (objeto)

Descreve o remetente de uma entrada de transcrição quando os metadados do remetente estão disponíveis. As entradas "agent", "manager", "virtual-agent", "external-agent" e "task-virtual-agent" podem conter name, id e avatar_url. As entradas de consumidor e do sistema têm um objeto vazio.

corpo da mensagem (objeto, oneOf)

O objeto body em cada entrada usa o valor de body.type para selecionar uma das formas de corpo de mensagem compatíveis. Os tipos de corpo compatíveis incluem corpos de texto, mídia ou arquivo, interativos, gerados pelo servidor, de ação e de notificação. Consulte Corpos de mensagens de texto em Corpos de mensagens de notificação para ver a lista completa de variantes documentadas.

função do participante (string, enumeração)

Identifica a categoria do remetente de uma entrada de transcrição.

Valores permitidos

  • end_user: o consumidor.

  • agent: um agente humano.

  • manager: um participante administrador.

  • virtual_agent: um agente virtual.

  • external_agent: um participante agente externo.

  • task_virtual_agent: um agente virtual de tarefas.

  • system: uma entrada gerada pelo sistema.

Controle de versões e suspensões de uso

O documento de metadados da transcrição do chat é compatível com a evolução do esquema compatível com versões anteriores. O sistema pode adicionar novos campos e variantes de corpo da mensagem ao longo do tempo, e as integrações precisam ignorar chaves não reconhecidas para garantir a funcionalidade contínua.

Versão atual do formato

  • transcript_version (string) - Valor atual: "1.0". As integrações precisam analisar a transcrição com base nos campos presentes no payload e não podem falhar se versões futuras adicionarem novos campos ou tipos de corpo de mensagem.

Tipos de corpo de mensagem desconhecidos

Quando uma entrada de transcrição contém um type ou body.type não reconhecido, preserve a entrada bruta, se possível, e continue analisando o restante da transcrição. O sistema pode adicionar novos tipos de corpo de mensagem sem mudar o significado dos campos atuais.

Campos descontinuados

Este documento não lista campos descontinuados para o registro de metadados da transcrição do chat.