Metadados da sessão de chamada

Este documento fornece o esquema do registro de metadados de sessão de chamada, o documento JSON que a CCAI Platform emite ao final de cada ligação. A CCAI Platform envia o registro para sua integração de CRM como o corpo do comando de fim de sessão e grava o registro na configuração de armazenamento externo como um arquivo metadata.json. Cada chamada produz exatamente um registro. O id de nível superior identifica cada registro de maneira exclusiva. Use esse esquema para ingerir registros em sistemas downstream, validar payloads recebidos ou mapear campos em colunas de data warehouse.

Raiz do esquema

O registro de metadados de sessão de ligação é um único objeto JSON que representa uma sessão de ligação. Três conceitos no nível superior determinam a identidade e o formato do registro.

Chave primária — id (número inteiro)

O id de nível superior identifica de forma exclusiva a sessão de chamada na sua instância. Há um registro por chamada. Todos os outros campos, matrizes e objetos aninhados de nível superior descrevem atributos da chamada que esse id identifica.

Discriminador de gerenciador — agent_info (objeto, oneOf)

Um único objeto com formato que varia de acordo com o último gerenciador da chamada. As duas variantes são mutuamente exclusivas, e a chave também pode estar ausente. Portanto, um registro carrega no máximo um dos três casos:

  • Variante de agente humano: presente quando a chamada tinha um agente humano e nenhum agente virtual. Transporta email, first_name, last_name e agent_number, além dos campos compartilhados id, name e avatar_url.

  • Variante de agente virtual: presente quando a chamada tinha um agente virtual e nenhum agente humano. Transporta va_alias e omite email, first_name, last_name e agent_number.

  • Chave ausente: a chave agent_info é omitida em dois casos: quando a chamada não tem um agente humano nem um agente virtual e quando tem ambos. Uma chamada carrega ambos quando um agente virtual é preservado em um encaminhamento para um agente humano. Assim, uma chamada totalmente processada pode chegar sem a chave.

Para detectar qual variante um registro carrega, primeiro verifique se a chave agent_info está presente e, em seguida, verifique se há um campo específico da variante, normalmente agent_info.email para a variante de agente humano ou agent_info.va_alias para a variante de agente virtual. Não infira o gerenciador apenas de agent_info. Para uma chamada que tenha ambos, leia o agente humano de participants[] e o agente virtual de virtual_agent_handle_durations[] ou os campos from_virtual_agent e to_virtual_agent em transfers[] e escalations[]. Para ver o formato completo de cada variante, consulte agent e virtual_agent.

Discriminadores de formato de chamada: call_type, session_type, session_type_v2 (string)

Três visualizações paralelas do mesmo tipo de chamada. Eles nunca discordam sobre o tipo de chamada que um registro representa, mas diferem apenas no vocabulário usado para nomear o tipo de chamada.

  • call_type usa o vocabulário de tipo enumerado legado (por exemplo, Voice Inbound (App), Voice Outbound ou Voice Internal).

  • session_type sempre retorna a mesma string que call_type. O CCAI Platform fornece esse campo para compatibilidade com versões anteriores de integrações que usam esse campo como chave. Trate-o como um alias descontinuado de call_type. Consulte Controle de versões e descontinuações.

  • session_type_v2 usa o vocabulário de tipo enumerado atual. Esse vocabulário estende o vocabulário call_type com distinções de entrada mais detalhadas, por exemplo, Voice Inbound (Mobile) e Voice Inbound (IVR via Mobile) em vez dos mais amplos Voice Inbound (App) e Voice Inbound (IVR via App). Para tipos de chamada que não têm um valor específico da v2, session_type_v2 retorna a mesma string que call_type. As novas integrações precisam analisar session_type_v2.

Para os valores de cada campo, consulte Informações principais.

Informações essenciais

Essas propriedades capturam as informações principais da chamada:

  • id (número inteiro): um identificador exclusivo para cada sessão de chamada. Essa é a chave primária que distingue uma chamada de outra.

  • call_uuid (string ou nulo): um identificador exclusivo que correlaciona uma chamada entre as instâncias de origem e de recebimento em interações de roteamento de chamadas dinâmico (DCR, na sigla em inglês). As duas partes de uma chamada de DCR compartilham o mesmo valor de call_uuid, permitindo que os clientes conectem dados entre ambientes. O campo é nulo ou vazio para qualquer chamada que não seja uma interação de DCR e para chamadas que ocorreram antes que a CCAI Platform adicionasse o campo.

  • lang (string): o código de idioma ISO 639 da chamada (por exemplo, "en" para inglês ou "es" para espanhol). Esse código ajuda você a realizar análises e relatórios específicos de cada idioma.

  • call_type (string): o tipo de chamada, usando o vocabulário de tipo legado. Os valores incluem "Voice Inbound (App)", "Voice Inbound (Web)", "Voice Inbound (IVR)", "Voice Inbound (IVR via App)", "Voice Inbound (API)", "Voice Inbound (Direct)", "Voice Inbound (Extension)", "Voice Scheduled (App)", "Voice Scheduled (Web)", "Voice Scheduled (API)", "Voice Callback", "Voice Callback (Web)", "Voice Outbound", "Voice Outbound (API)", "Voice Outbound (Direct)", "Voice Outbound (UCaaS)", "Voice Internal", "Voice Campaign (Acqueon)", "Voice Campaign (<your brand name>)" e "Agent Scheduled Call".

  • session_type (string): uma cópia de call_type (mesmos valores) que a plataforma CCAI mantém para compatibilidade com versões anteriores. Consulte Controle de versões e descontinuações: duplicatas legadas.

  • session_type_v2 (string): o tipo de chamada, usando o vocabulário de tipo atual. Ele refina os valores de call_type com distinções de entrada mais detalhadas (por exemplo, "Voice Inbound (Mobile)" e "Voice Inbound (IVR via Mobile)" em vez de "Voice Inbound (App)" e "Voice Inbound (IVR via App)"). Os valores incluem "Voice Inbound (Mobile)", "Voice Inbound (Web)", "Voice Inbound (IVR)", "Voice Inbound (IVR via Mobile)", "Voice Inbound (API)", "Voice Inbound (Direct)", "Voice Inbound (Extension)", "Voice Scheduled (Mobile)", "Voice Scheduled (Web)", "Voice Scheduled (API)", "Voice Callback", "Voice Callback (Web)", "Voice Outbound", "Voice Outbound (API)", "Voice Outbound (Direct)", "Voice Outbound (UCaaS)", "Voice Internal", "Voice Campaign (Acqueon)", "Voice Campaign (<your brand name>)" e "Agent Scheduled Call".

  • status (string): o status da chamada, que acompanha o progresso dela durante o ciclo de vida. Valores possíveis, agrupados por fase do ciclo de vida:

    • Pré-conexão: "scheduled", "selecting", "queued", "assigned", "connecting", "switching", "requeued", "requeued_detection_missed".

    • Conectado: "connected".

    • Agente virtual: "va_assigned", "va_connected".

    • Campanha: "preview_pending", "preview_ready", "preview_waiting", "predictive_waiting", "progressive_waiting", "campaign_dialing", "campaign_connecting", "campaign_connected".

    • Somente ação: "action_only", "action_only_finished".

    • Correio de voz: "voicemail", "voicemail_received", "voicemail_read", "voicemail_forwarded".

    • Terminal: "finished", "failed", "recovered", "deflected".

  • created_at (string, data e hora): o carimbo de data/hora preciso de quando a CCAI Platform criou o registro de chamada.

  • queued_at (string, data/hora ou nulo): o carimbo de data/hora de quando a chamada entrou na fila ou nulo se a chamada não entrou na fila.

  • assigned_at (string, data/hora ou nulo): o carimbo de data/hora de quando a CCAI Platform atribuiu a chamada a um agente ou nulo se a CCAI Platform não atribuiu a chamada.

  • connected_at (string, data/hora ou nulo): o carimbo de data/hora de quando a chamada foi conectada.

  • ends_at (string, data e hora ou nulo): o carimbo de data/hora de quando a chamada terminou.

  • scheduled_at (string, data e hora ou nulo): o carimbo de data/hora de quando a CCAI Platform programou a chamada ou nulo se a chamada foi imediata.

  • updated_at (string, data/hora): o carimbo de data/hora de quando a CCAI Platform atualizou os dados da chamada pela última vez.

  • wait_duration (número inteiro ou nulo): o tempo total que o consumidor passou na fila durante toda a chamada, em segundos, ou nulo se a CCAI Platform não registrou nenhum tempo de fila. Para ver o tempo de fila detalhado por segmento individual, consulte a matriz queue_durations (Durações da fila). Consulte Controle de versões e descontinuações: nomenclatura do campo de tempo de espera.

  • call_duration (número inteiro ou nulo): a duração total da chamada, em segundos.

  • hold_duration (número inteiro ou nulo): o tempo total que o consumidor passou em espera, em segundos, ou nulo se não houve tempo de espera.

  • rating (número inteiro ou nulo): a classificação de satisfação do cliente (CSAT) que o consumidor enviou ou nulo se o consumidor não enviou uma classificação.

  • has_feedback (booleano): uma flag que indica se o consumidor enviou feedback após a chamada.

  • voip_provider (string): o provedor de VoIP da chamada. Observação: este campo foi descontinuado e sempre retorna "deprecated".

  • out_ticket_id (string ou nulo): o ID do tíquete que a plataforma CCAI criou no sistema de CRM externo.

  • out_ticket_url (string, URI ou nulo): o URL do tíquete do CRM.

  • is_out_ticket_account (booleano ou nulo): indica se o tíquete de CRM representa um cliente (verdadeiro) ou uma interação de chamada (falso).

  • verified (booleano): indica se a ação inteligente de verificação verificou a interação.

  • recording_url (string, URI ou nulo): o URL da gravação da chamada ou nulo se nenhuma gravação estiver disponível.

  • recording_permission (string ou nulo): o status da permissão de gravação do consumidor. Valores possíveis: "not_asked", "granted", "denied".

  • voicemail_reason (string): o motivo pelo qual uma mensagem foi deixada no correio de voz ou "not_voicemail" quando a chamada não foi para o correio de voz. Valores possíveis: "not_voicemail", "temporary_redirection", "after_hour_deflection", "over_capacity_deflection", "no_input" e "no_agent".

  • disconnected_by (string ou nulo): indica qual parte encerrou a chamada. Valores possíveis: disconnected_by_unknown, disconnected_by_agent, disconnected_by_end_user, disconnected_by_virtual_agent, disconnected_by_system.

  • fail_reason (string ou nulo): o motivo da falha de uma chamada ou "nothing" para chamadas que não falharam. Valores possíveis, agrupados pela parte ou pelo subsistema a que a falha é atribuída:

    • Sem falha: nothing

    • Geral: unknown, expired, transfer_expired, canceled_outside_fulfillment_hours

    • Usuário final: eu_canceled, eu_rejected, eu_abandoned, eu_in_menu_abandoned, eu_repeated_voicemail, eu_repeated_callback, eu_dcr_abandoned_on_receiving, eu_busy, eu_wrong_number, eu_no_answer, eu_noti_failed, eu_phone_denied

    • Agente: ag_canceled, ag_ignored, ag_declined, ag_mic_no_device, ag_mic_denied, ag_invalid_outbound_num, ag_called_blocked_num

    • Conexão: conn_decline

    • VoIP: voip_twilio_error, voip_tokbox_error, voip_invalid_token, voip_conn_general, voip_conn_timeout, voip_conn_signal, voip_conn_codec, voip_nexmo_error, voip_telnyx_error

    • Áudio: audio_not_received_by_carrier, audio_device_unable_to_start

    • Estado travado ou não resolvível: stuck_due_to_api_error, group_deleted_no_substitute, menu_deleted, direct_pstn_call_to_fallback_number

    • Campanha: campaign_paused, campaign_queue_reassigned, campaign_no_incoming_contacts, campaign_call_canceled

    • Encerrado à força: force_ended, force_failed_call_stuck

  • fail_details (string ou nulo): detalhes adicionais legíveis por humanos que acompanham fail_reason, quando disponíveis.

  • adapter_fail_code (número inteiro ou nulo): código numérico correspondente a fail_reason no nível da chamada. Nulo quando a chamada não falha. A mesma enumeração é usada em adapter_fail_code por participante no §17.

  • adapter_fail_message (string ou nulo): mensagem legível por humanos correspondente a adapter_fail_code. Nulo quando a chamada não falha.

  • support_number (string ou nulo): o número de telefone que o consumidor discou para entrar em contato com o contact center, no formato E.164. Preenchido para chamadas originadas de URA. Pode ser nulo para outros canais.

  • queue_priority_level (número inteiro; presente apenas quando a prioridade da fila está ativada na sua conta): a prioridade da fila atribuída à chamada.

Informações do agente e do agente virtual

Estas seções explicam quem ou o que lidou com a chamada:

  • agent_info (objeto): esse campo pode conter informações sobre um agente humano ou virtual. Ele usa a palavra-chave oneOf para especificar que pode ser um de dois tipos.

    • agent (objeto): informações sobre o agente humano:

      • id (número inteiro): o ID exclusivo do agente.

      • agent_number (string ou nulo): um identificador atribuído ao agente.

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

      • name (string): o nome completo do agente.

      • last_name (string): o sobrenome do agente.

      • first_name (string): o nome do agente.

      • avatar_url (string, uri): o URL da imagem do avatar do agente.

    • virtual_agent (objeto): informações sobre o agente virtual:

      • id (número inteiro): o ID exclusivo do agente virtual.

      • name (string): o nome do agente virtual.

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

      • va_alias (string ou nulo): o alias de exibição do agente virtual, se você tiver definido um. Sempre presente no payload; nulo quando nenhum alias é definido.

  • selected_menu (objeto ou nulo): informações sobre o menu que o consumidor selecionou durante a chamada.

    • id (número inteiro): o ID exclusivo do cardápio.

    • name (string): o nome do menu.

    • parent_id (número inteiro ou nulo): o ID do menu da família, se houver.

    • position (número inteiro): a posição do menu em relação a outros menus no mesmo nível.

    • deleted (booleano): se o cardápio foi excluído.

    • menu_type (string): o tipo de menu (como ivr_menu ou sms_menu).

    • hidden (booleano): se o menu está visível e disponível para uso.

  • menu_path (objeto ou nulo): descreve o caminho hierárquico dos menus que o consumidor acessou.

    • items_count (número inteiro): o número de menus no caminho.

    • name (string): uma string separada por barras de nomes de menu (por exemplo, "Suporte/Faturamento").

    • materialized_path (string): uma string de IDs de menu separados por barra.

  • automation_redirection (objeto; presente apenas quando o primeiro registro de desvio da chamada está associado a um grupo de redirecionamento): detalhes sobre o redirecionamento de fila com base em porcentagem que afetou o roteamento dessa chamada.

    • percent_redirection (booleano): se você ativou o redirecionamento com base em porcentagem no menu de origem.

    • redirection_group (matriz): matriz de um elemento que contém os detalhes do grupo de redirecionamento:

      • group_label (string): rótulo legível por humanos para o grupo de redirecionamento (por exemplo, "Grupo de redirecionamento 1").

      • destination (objeto ou nulo): o destino do redirecionamento que você configurou no grupo.

      • after_hours (booleano ou nulo): se você ativou as opções de desvio fora do horário de atendimento no grupo.

      • ah_destination (objeto ou nulo): o destino de redirecionamento fora do horário de atendimento que você configurou no grupo.

Detalhes do usuário final

  • end_user (objeto ou nulo): informações sobre o consumidor:

    • id (número inteiro ou nulo): o ID interno do consumidor.

    • identifier (string ou nulo): um identificador externo para o consumidor.

    • out_contact_id (string ou nulo): o ID do consumidor no CRM.

Dados personalizados e fornecidos pelo SDK

  • customer_flag (objeto; presente apenas quando o site transmitiu dados de autenticação personalizados): atributos de dados personalizados relacionados à autenticação que o app ou site do consumidor transmitiu no início da sessão. O payload inclui apenas o subconjunto que você designa como parâmetros de autenticação.

  • api_dap_request (objeto; presente apenas quando você ativa os parâmetros de dados e os inclui nos metadados): um snapshot dos valores de parâmetro da chamada. As chaves e os tipos de valor dependem da configuração do parâmetro de dados.

  • form_responses (matriz; presente apenas quando o consumidor enviou pelo menos uma resposta de formulário): respostas que os formulários do SDK durante a chamada coletaram durante a sessão. Cada entrada contém:

    • id (string ou número inteiro): identificador da resposta do formulário.

    • title (string): título do formulário mostrado ao consumidor.

    • smart_action_id (número inteiro ou nulo): identificador da ação inteligente que acionou o formulário, se houver.

    • questions (matriz): os pares de perguntas e respostas coletados.

Anexos

  • photos (matriz): fotos que o consumidor enviou durante a chamada.

    • id (número inteiro): identificador exclusivo da foto.

    • photo_type (string): tipo ou origem da foto (como "photo").

    • url (string, uri): URL da foto armazenada.

    • smart_action_type (string ou nulo): a ação inteligente que produziu a foto, se houver.

    • transfer_id (número inteiro ou nulo): o ID do evento de transferência da foto, se o consumidor tiver feito o upload dela após uma transferência.

  • videos (matriz): vídeos que o consumidor enviou durante a chamada.

    • id (número inteiro): identificador exclusivo do vídeo.

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

    • smart_action_type (string ou nulo): a ação inteligente que produziu o vídeo, se houver.

    • transfer_id (número inteiro ou nulo): o ID do evento de transferência do vídeo, se o consumidor o enviou após uma transferência.

Desvio de chamadas

  • deflection (string): indica se e como a chamada foi desviada (por exemplo, "no_deflection", "over_cap_phone" ou "after_hours_voicemail").

  • deflection_details (matriz): fornece um registro detalhado de desvios durante a chamada. O campo de deflexão em cada entrada usa a enumeração definida em Definições: deflexão. Cada entrada inclui:

    • id (número inteiro): identificador exclusivo do registro de desvio.

    • call_id (número inteiro): identificador exclusivo da chamada.

    • transfer_id (número inteiro ou nulo): identificador exclusivo da transferência associada ao desvio, se aplicável.

    • deflection (string; consulte Definições: desvio para valores permitidos): o tipo de desvio.

    • created_at (string, data e hora): carimbo de data/hora de quando o desvio ocorreu.

    • from_menu_path (objeto ou nulo): caminho do menu em que o desvio começou.

    • to_menu_path (objeto ou nulo): caminho do menu para o qual a CCAI Platform desviou a chamada.

    • to_sip_uri (string; presente apenas quando a plataforma CCAI desviou a chamada para um destino SIP): URI SIP para o qual a plataforma CCAI desviou a chamada, se aplicável.

    • to_sip_headers (objeto; presente apenas quando a plataforma CCAI desviou a chamada para um destino SIP): cabeçalhos SIP com os quais a plataforma CCAI desviou a chamada, se aplicável.

Transferências

  • transfers (matriz): uma entrada por evento de transferência durante a chamada. Registra transferências assistidas e cegas entre agentes, agentes virtuais e menus.

    • id (número inteiro): identificador exclusivo da transferência.

    • status (string): status atual da transferência (por exemplo, transferindo, conectado ou com falha).

    • fail_reason (string): motivo da falha na transferência ou "nothing" se não houver falha.

    • created_at (string, data e hora): quando a transferência começou.

    • assigned_at (string, data/hora ou nulo): quando a plataforma CCAI atribuiu a transferência à parte receptora.

    • connected_at (string, data e hora ou nulo): quando a transferência foi conectada.

    • updated_at (string, data e hora): quando a CCAI Platform atualizou o registro de transferência pela última vez.

    • call_duration (número inteiro): duração da chamada do segmento transferido, em segundos.

    • wait_duration (número inteiro): tempo que o consumidor esperou durante a transferência, em segundos.

    • deflection (string): tipo de desvio associado à transferência, se houver.

    • answer_type_path (string ou nulo): caminho que descreve como a chamada transferida foi resolvida.

    • from_menu_path / to_menu_path (objeto ou nulo): caminho do menu antes e depois da transferência; mesmo formato que menu_path em Definições.

    • from_agent / to_agent (objeto ou nulo): agente humano em cada lado da transferência; mesmo formato do objeto agent em Definições.

    • from_virtual_agent / to_virtual_agent (objeto ou nulo): agente virtual em cada lado da transferência; mesmo formato do objeto virtual_agent em Definições.

    • from_queue_priority_level / to_queue_priority_level (número inteiro ou nulo): prioridade da fila antes e depois da transferência. Presente apenas quando você ativa a prioridade de fila na sua conta.

Duração do atendimento de chamadas

  • handle_durations (matriz): uma matriz de objetos, cada um representando um segmento da chamada processada por um agente. Isso ajuda a analisar o tempo de atendimento do agente.

    • id (número inteiro): identificador exclusivo da duração do atendimento.

    • agent_id (número inteiro): ID do agente.

    • acw_duration (número inteiro): duração do trabalho após a ligação.

    • bcw_duration (número inteiro): duração do trabalho antes da chamada.

    • call_duration (número inteiro): duração da chamada durante esse segmento.

    • menu_path_id (número inteiro ou nulo): ID do caminho do menu.

    • menu_path (string): nome do caminho do menu.

    • lang (string): idioma usado.

    • barged (booleano): se o supervisor entrou na chamada.

    • transfer (booleano): se uma transferência ocorreu.

    • transfer_id (número inteiro ou nulo): ID da transferência.

    • transfer_cold (booleano ou nulo): se a transferência foi cega.

    • started_at (string, data e hora): carimbo de data/hora de início.

    • ended_at (string, data/hora ou nulo): carimbo de data/hora de término.

    • scheduled_at (string, data/hora ou nulo): carimbo de data/hora programado.

    • hold_duration (número inteiro ou nulo): duração da retenção durante esse segmento.

    • assigned_connection_duration (número inteiro): duração que o consumidor esperou enquanto o agente se conectava durante essa fase.

    • session_breakthrough (objeto; presente apenas quando a chamada foi atendida apesar do status de indisponível do agente): detalhes sobre a atribuição da chamada atendida apesar do status de indisponível do agente, se aplicável.

Durações da fila

  • queue_durations (matriz): uma matriz de objetos, cada um representando um segmento da chamada em que o consumidor estava em uma fila. Isso permite analisar os tempos de espera e os níveis de serviço.

    • id (número inteiro): identificador exclusivo da duração da fila.

    • agent_id (número inteiro): ID do agente.

    • ended_at (string, data e hora): carimbo de data/hora de término.

    • lang (string): idioma usado.

    • menu_path_id (número inteiro): ID do caminho do menu.

    • menu_path (string): nome do caminho do menu.

    • queue_duration (número inteiro): duração do segmento da fila.

    • started_at (string, data e hora): carimbo de data/hora de início.

    • transfer_cold (booleano): se a chamada foi transferência cega.

    • transfer (booleano): se uma transferência ocorreu.

    • transfer_id (número inteiro ou nulo): ID da transferência.

    • service_level_abandon_time_threshold (número inteiro): limite de tempo para abandono do nível de serviço.

    • service_level_event (string): status do evento no nível de serviço ("excluded", "in_sla", "not_in_sla").

    • service_level_target_percent (número inteiro): porcentagem de meta para conformidade com o nível de serviço.

    • service_level_target_time (número inteiro): tempo desejado para conformidade com o nível de serviço.

Encaminhamentos de agente virtual para humano

  • escalations (matriz): cada entrada representa um encaminhamento de um agente virtual para um agente humano.

    • id (número inteiro): identificador exclusivo do encaminhamento.

    • status (string): status atual do encaminhamento. Valores possíveis: escalating, "escalated", "canceled", "deflecting" e "deflected".

    • reason (string): motivo do encaminhamento da sessão.

    • created_at (string, data e hora): quando o encaminhamento começou.

    • escalated_at (string, data e hora ou nulo): quando o encaminhamento foi concluído.

    • from_virtual_agent (objeto ou nulo): agente virtual que encaminhou a chamada. Mesmo formato do objeto virtual_agent em Definições.

    • to_agent (objeto ou nulo): agente humano para quem a chamada foi encaminhada. Mesmo formato do objeto agent em Definições.

    • from_menu_path / to_menu_path (objeto ou nulo): caminho do menu antes e depois do encaminhamento.

Encaminhamentos desviados pelo agente virtual

  • virtual_agent_deflected_escalations (matriz): detalhes de encaminhamentos desviados de agentes virtuais.

    • id (número inteiro): identificador exclusivo.

    • deflection (string): tipo de desvio registrado para o encaminhamento desviado. Esse é um vocabulário menor do que o campo de desvio no nível da chamada descrito em Definições: desvio. Ele abrange apenas os resultados que um encaminhamento de agente virtual pode registrar. Valores possíveis:

      • Capacidade excedida: over_cap, over_cap_phone, over_cap_voicemail, over_cap_callback, over_cap_message, over_cap_queue, over_cap_sip, over_cap_extension, over_cap_phone_with_extension

      • Fora do horário comercial: after_hours, after_hours_phone, after_hours_voicemail, after_hours_message, after_hours_message_only, after_hours_queue, after_hours_sip, after_hours_extension, after_hours_phone_with_extension

      • Redirecionamento temporário: temp_redirection, temp_redirection_phone, temp_redirection_voicemail, temp_redirection_message, temp_redirection_queue, temp_redirection_sip, temp_redirection_extension, temp_redirection_phone_with_extension

      • Pré-sessão de URA: ivr_presession_deflection

      • Iniciada pelo agente virtual: va_redirection_phone, va_redirection_sip, va_third_party_phone, va_third_party_sip

      Os valores over_cap, after_hours e temp_redirection sem sufixo são registrados quando a chamada é encerrada antes que um resultado de desvio seja alcançado.

    • escalation_id (número inteiro): identificador do evento de escalonamento.

    • escalation_reason (string): motivo do encaminhamento para um supervisor.

    • escalated_at (string, data e hora): carimbo de data/hora do encaminhamento.

    • menu_path_id (número inteiro): ID do caminho do menu.

    • menu_path (string): caminho do menu.

    • lang (string): idioma.

    • virtual_agent (objeto): detalhes do agente virtual. Consulte Definições.

Duração do processamento do agente virtual

  • virtual_agent_handle_durations (matriz): segmentos de tempo em que um agente virtual atendeu à chamada.

    • id (número inteiro): identificador exclusivo.

    • virtual_agent (objeto): detalhes do agente virtual. Consulte Definições.

    • call_duration (número inteiro): duração do segmento.

    • escalation_reason (string): motivo do encaminhamento para um supervisor.

    • finish_reason (string): motivo pelo qual a interação foi concluída.

    • sentiment (número inteiro): sentimento do consumidor.

    • response_count (número inteiro): contagem de respostas do agente virtual.

    • fallback_response_count (número inteiro): contagem de respostas substitutas.

    • initiated_by (string): como a sessão do agente virtual começou.

    • menu_path_id (número inteiro): ID do caminho do menu.

    • menu_path (string): caminho do menu.

    • lang (string): idioma.

    • transfer (booleano): se a chamada foi transferida.

    • transfer_id (número inteiro ou nulo): identificador do evento de transferência.

    • started_at (string, data e hora): carimbo de data/hora de início.

    • ended_at (string, data/hora ou nulo): carimbo de data/hora de término.

Duração do processamento do consumidor

  • consumer_handle_durations (matriz): durações em que o consumidor esteve na chamada.

    • id (número inteiro): identificador exclusivo.

    • call_duration (número inteiro): duração do segmento do consumidor.

    • hold_duration (número inteiro ou nulo): duração da guarda de documentos do consumidor.

    • started_at (string, data e hora): carimbo de data/hora de início.

    • ended_at (string, data e hora): carimbo de data/hora de término.

Duração dos eventos do consumidor

  • consumer_event_durations (matriz): detalhes de eventos de chamada do consumidor (como CSAT ou pagamento).

    • id (número inteiro): identificador exclusivo.

    • duration (número inteiro): duração do evento.

    • type (string): tipo de evento.

    • event (string): resultado do evento.

    • menu_path_id (número inteiro): ID do caminho do menu.

    • menu_path (string): caminho do menu.

    • lang (string): idioma.

    • started_at (string, data e hora): carimbo de data/hora de início.

    • ended_at (string, data e hora): carimbo de data/hora de término.

Duração do consumidor no menu

  • consumer_in_menu_durations (matriz): durações das interações do consumidor nos menus.

    • id (número inteiro): identificador exclusivo.

    • duration (número inteiro): duração no menu.

    • event (string): resultado da interação com o menu.

    • menu_path_id (número inteiro): ID do caminho do menu.

    • menu_path (string): caminho do menu.

    • lang (string): idioma.

    • started_at (string, data e hora): carimbo de data/hora de início.

    • ended_at (string, data e hora): carimbo de data/hora de término.

Participantes

  • participants (matriz): informações sobre cada participante da chamada (por exemplo, o consumidor, o agente ou o agente virtual).

    • id (número inteiro): identificador exclusivo do participante.

    • type (string): tipo de participante ("end_user", "agent", "virtual_agent" etc.).

    • entry_type (string): como o participante entrou na chamada.

    • user_id (número inteiro ou nulo): ID do usuário se o participante for um agente.

    • end_user_id (número inteiro ou nulo): identificador do consumidor se o participante for o consumidor.

    • virtual_agent_id (número inteiro ou nulo): ID do agente virtual se o participante for um agente virtual.

    • virtual_agent_params (objeto; presente apenas quando você configura metadados personalizados do agente virtual para inclusão): metadados personalizados que o agente virtual usa.

    • status (string): status do participante ("waiting", "connected", "finished" etc.).

    • fail_reason (string): motivo da falha, se houver.

    • connected_at (string, data e hora ou nulo): carimbo de data/hora de quando o participante se conectou.

    • phone_number (string; presente apenas em participantes consumidores): número de telefone do participante.

    • call_id (número inteiro): identificador da chamada.

    • call_duration (número inteiro ou nulo): duração da chamada para o participante.

    • hold_duration (número inteiro ou nulo): duração da espera do participante.

    • ended_at (string, data/hora ou nulo): carimbo de data/hora de quando o envolvimento do participante terminou.

    • adapter_fail_code (número inteiro ou nulo): código numérico correspondente ao motivo da falha.

    • adapter_fail_message (string ou nulo): descrição legível por humanos de fail_reason, se houver.

    • agent_assist (objeto; presente apenas em participantes do agente quando você configura o Agent Assist): configurações ativas do Agent Assist para esse participante.

    • virtual_agent (objeto; presente apenas em participantes de agente virtual): detalhes do agente virtual que atua como esse participante, diferente do agent_info de nível superior e de virtual_agent_params.

    • caller_id (string; presente apenas quando você ativa o ID de chamadas do cabeçalho SIP na sua conta e apenas em participantes consumidores): identificador de chamadas que a plataforma CCAI extrai dos cabeçalhos SIP de entrada para esse participante consumidor.

    • sip_headers (objeto ou nulo): cabeçalhos SIP associados a esse participante. Sempre presente no payload. É nulo quando a plataforma CCAI não captura cabeçalhos.

    • location (string ou nulo; presente apenas em participantes do agente): o local do agente.

    • location_id (número inteiro ou nulo; presente apenas em participantes do agente): o ID do local.

    • email (string, e-mail; presente apenas em participantes agentes): o endereço de e-mail do agente.

    • first_name (string ou nulo; presente apenas em participantes do agente): o nome do agente.

    • last_name (string ou nulo; presente apenas em participantes agentes): o sobrenome do agente.

    • middle_name (string ou nulo; presente apenas em participantes do agente): o nome do meio do agente.

    • teams (matriz; presente apenas em participantes do agente): matriz de objetos { id, name } para as equipes do agente.

Gravações

  • recordings (matriz): informações sobre a gravação de áudio da chamada.

    • id (número inteiro): identificador exclusivo da gravação.

    • call_id (número inteiro): identificador da chamada.

    • conference_sid (string ou nulo): identificador de chamada do provedor de VoIP.

    • duration (número inteiro ou nulo): duração da gravação.

    • recording_type (string): tipo de gravação.

    • redaction_times (matriz): segmentos de tempo editados.

      • start (string, data e hora): quando o intervalo de edição começou.

      • end (string, data e hora): quando o intervalo de edição terminou.

      • duration (número inteiro): duração da edição, em segundos.

      • start_agent_id (número inteiro ou nulo): o agente que iniciou o encobrimento.

      • end_agent_id (número inteiro ou nulo): o agente que encerrou a edição.

    • started_at (string, data e hora): carimbo de data/hora de início da gravação.

  • post_processed_recordings (matriz; presente apenas quando você ativa a gravação pós-processada na sua conta): gravações de áudio que o pós-processamento produz (como conversão de formato ou edição).

    • id (número inteiro): identificador exclusivo da gravação pós-processada.

    • call_id (número inteiro): identificador da chamada.

    • duration (número inteiro): duração da gravação, em segundos.

    • started_at (string, data e hora): carimbo de data/hora de início da gravação.

    • recording_file_name (string): nome do arquivo do recurso de áudio pós-processado.

    • recording_url (string, uri): URL do arquivo de áudio pós-processado.

    • agent_id (número inteiro ou string): identificador do agente associado ao segmento.

    • virtual_agent_id (número inteiro ou string): identificador do agente virtual associado ao segmento, se houver.

    • conversation_id (string): identificador que correlaciona essa gravação com o registro da conversa.

  • segments (matriz; presente apenas quando você ativa as gravações de insights pós-processados na sua conta): segmentos de áudio por participante (e gravação de tela opcional) que o sistema produz para pipelines de insights downstream.

    • id (número inteiro): identificador exclusivo do segmento.

    • call_id (número inteiro): identificador da chamada.

    • duration (número inteiro): duração do segmento, em segundos.

    • started_at (string, data e hora): carimbo de data/hora de início do segmento.

    • audio_file_name (string): nome de arquivo do recurso de áudio do trecho.

    • audio_url (string, URI): URL do arquivo de áudio do segmento.

    • agent_id (número inteiro ou string): identificador do agente associado ao segmento.

    • virtual_agent_id (número inteiro ou string): identificador do agente virtual associado ao segmento, se houver.

    • participant_id (número inteiro ou string): identificador do participante a que o segmento pertence.

    • conversation_id (string): identificador que correlaciona esse segmento ao registro de conversa.

    • screen_recording_url (string, URI ou nulo): URL do recurso de gravação de tela correspondente. Presente apenas quando você ativa a gravação de tela na sua conta.

    • screen_recording_file_name (string ou nulo): nome de arquivo da gravação de tela. Presente na mesma condição que screen_recording_url.

Oferecer eventos

  • offer_type (string ou nulo): como a plataforma CCAI ofereceu a chamada ao agente.

  • offer_events (matriz): eventos em que a plataforma CCAI ofereceu a chamada aos agentes.

    • casting_time (string, data e hora): horário em que a CCAI Platform ofereceu a chamada.

    • group (string): grupo para o qual a CCAI Platform ofereceu a chamada.

Outros detalhes

  • answer_type (string ou nulo): como a chamada foi resolvida ("manual" ou "auto").

  • outbound_number (string ou nulo): número de telefone de saída usado.

  • wait_time_sms (matriz; presente apenas quando ocorreram interações de SMS de tempo de espera nessa chamada): interações de SMS que a plataforma CCAI enviou ao consumidor sobre o tempo de espera esperado. Cada entrada contém:

    • transfer_id (número inteiro ou nulo): identificador do evento de transferência, se associado a uma transferência.

    • status (string): status do SMS. Valores possíveis: not_triggered, triggered, triggered_allowed, triggered_denied, triggered_no_selection, triggered_sent, triggered_failed.

    • received (booleano): se o consumidor recebeu o SMS.

  • in_call_sms (matriz; presente apenas quando ocorreram interações de SMS durante a chamada): interações de SMS durante a chamada. Cada entrada contém:

    • transfer_id (número inteiro ou nulo): identificador do evento de transferência, se associado a uma transferência.

    • preset_sent (booleano): se a plataforma CCAI enviou uma mensagem predefinida.

    • custom_sent (booleano): se o agente enviou uma mensagem personalizada (texto livre).

    • received (booleano): se a CCAI Platform recebeu um SMS do consumidor.

  • dispositions (matriz; presente apenas quando você ativa códigos ou notas de finalização na sua conta): códigos e notas de finalização que os agentes registraram. Cada entrada inclui campos renderizados dinamicamente com base na sua configuração de finalização:

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

    • transfer_id (número inteiro ou nulo): identificador do evento de transferência, se registrado após uma transferência.

    • participant_id (número inteiro): identificador do participante.

    • note (string): observação do agente em texto livre.

    • original_note (string): versão original (pré-edição) da nota.

    • code (string): codinome de disposição.

    • ujet_code_id (número inteiro ou string vazia): o ID da plataforma CCAI do código de disposição, uma chave estável para o código (o nome de exibição do código pode mudar). String vazia quando indisponível.

    • list (string): nome da lista a que o código pertence.

    • list_path (string): caminho separado por barras da lista do código.

    • ujet_list_id (número inteiro ou string vazia): o ID da CCAI Platform da lista a que o código de disposição pertence, uma chave estável para a lista. String vazia quando indisponível.

    • custom_list_id (string ou número inteiro): identificador da lista definido pelo cliente, se mapeado.

    • custom_code_id (string ou número inteiro): identificador de código definido pelo cliente, se mapeado.

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

  • feedback (string ou nulo): feedback do consumidor.

  • smart_action_text (string ou nulo): texto de qualquer ação inteligente realizada.

  • custom_data_secured (objeto ou nulo): dados personalizados assinados com segurança.

  • custom_data_not_secured (objeto ou nulo): dados personalizados assinados de forma não segura.

  • in_queue_wait_time_va (matriz; presente apenas quando você ativa o rastreamento de tempo de espera na fila para agentes virtuais na sua conta e apenas quando ocorre pelo menos um encaminhamento de agente virtual preservado): intervalos de tempo em que o consumidor esperou na fila enquanto a plataforma CCAI preservava um agente virtual para ele após o encaminhamento. Cada entrada contém:

    • start (string, data e hora): quando a espera na fila começou.

    • end (string, data/hora ou nulo): quando a espera na fila terminou. Nulo se não foi concluída.

    • duration (número inteiro ou nulo): duração da espera em segundos. É nulo quando end é nulo.

  • auto_session_summaries (matriz; presente apenas quando você ativa o resumo de conversas na sua conta e a plataforma CCAI gera um resumo): resumos de sessão gerados com IA que a plataforma CCAI salva no registro do CRM. Cada entrada contém:

    • user_id (número inteiro): identificador do participante do agente ao qual o resumo está associado.

    • participant_id (número inteiro): identificador do participante.

    • session_summary (string): o texto do resumo.

    • session_summary_sections (matriz ou objeto): o resumo em seções estruturadas, se disponível.

  • sip_headers (objeto; presente apenas quando você ativa a captura de cabeçalho SIP na sua conta e a configura para inclusão nos metadados de sessão): cabeçalhos SIP de entrada que a CCAI Platform capturou para a chamada. As chaves e os valores refletem os cabeçalhos SIP recebidos do provedor de telefonia upstream.

Definições

Esta seção define cada subesquema uma vez. Os grupos de propriedades que fazem referência aos subesquemas se vinculam a essas definições em vez de redefinir as formas inline.

Descreve um caminho de menu hierárquico que a chamada percorreu. Consulte Navegação do menu para ver a lista completa de campos.

Referenciado em: o campo menu_path de nível superior; cada transfers[].from_menu_path e transfers[].to_menu_path; cada escalations[].from_menu_path e escalations[].to_menu_path; cada deflection_details[].from_menu_path e deflection_details[].to_menu_path.

agent (objeto)

Descreve um agente humano. Esse objeto é uma das duas variantes do discriminador agent_info de nível superior (consulte Raiz do esquema). Consulte Informações do agente e do agente virtual para ver a lista completa de campos.

Referenciado em: o campo agent_info quando um agente humano processou a chamada por último; cada transfers[].from_agent e transfers[].to_agent; cada escalations[].to_agent.

virtual_agent (objeto)

Descreve um agente virtual. Esse objeto é uma das duas variantes do discriminador agent_info de nível superior (consulte Raiz do esquema). Consulte Informações do agente e do agente virtual para ver a lista completa de campos.

Referenciado em: o campo agent_info quando um agente virtual processou a chamada pela última vez; cada transfers[].from_virtual_agent e transfers[].to_virtual_agent; cada escalations[].from_virtual_agent; cada virtual_agent_handle_durations[].virtual_agent; cada virtual_agent_deflected_escalations[].virtual_agent.

deflection (string, enum)

O estado de desvio de uma chamada ou segmento de chamada. Os valores seguem um padrão de nomenclatura &lt;trigger&gt;_&lt;destination&gt;, em que o prefixo identifica a condição que acionou o desvio (por exemplo, capacidade excedida, fora do horário de atendimento ou redirecionamento temporário) e o sufixo identifica o destino ou tratamento (por exemplo, correio de voz, fila, telefone ou mensagem).

Sufixos de destino comuns:

  • _phone: encaminha a chamada para um número de telefone externo.

  • _voicemail: direciona a chamada para o correio de voz.

  • _message: reproduz uma mensagem informativa.

  • _message_only: reproduz uma mensagem e encerra a chamada sem mais encaminhamentos.

  • _callback: oferece uma chamada de retorno agendada.

  • _wait: mantém o autor da chamada em espera.

  • _queue: coloca a chamada em uma fila diferente.

  • _sip: encaminha a chamada para um destino SIP.

  • _extension: encaminha a chamada para um ramal.

  • _phone_with_extension: encaminha a chamada para um destino telefônico com um ramal.

Valores permitidos, agrupados por família de gatilhos:

  • Sem desvio: no_deflection, deflecting.

  • Capacidade excedida: quando a fila ultrapassou o limite de capacidade: over_cap_phone, over_cap_voicemail, over_cap_callback, over_cap_wait, over_cap_queue, over_cap_message, over_cap_ewt_only, over_cap_sip, over_cap_extension, over_cap_phone_with_extension.

  • Desvio abandonado: quando uma transferência ou chamada é concluída antes que o desvio pendente seja resolvido: deflection_abandoned.

  • Fora do horário de funcionamento: quando a chamada chegou fora do horário de funcionamento configurado no menu: after_hours_voicemail, after_hours_phone, after_hours_message_only, after_hours_queue, after_hours_message, after_hours_sip, after_hours_extension, after_hours_phone_with_extension.

  • Redirecionamento temporário: quando você configura um redirecionamento temporário no menu: temp_redirection_phone, temp_redirection_message, temp_redirection_voicemail, temp_redirection_queue, temp_redirection_sip, temp_redirection_extension, temp_redirection_phone_with_extension.

  • Pré-sessão de IVR: ivr_presession_deflection.

  • Iniciada pelo agente virtual: quando um agente virtual redirecionou ou transferiu a chamada: va_redirection_phone, va_redirection_sip, va_third_party_phone, va_third_party_sip.

  • Chamada interna fora do horário comercial: internal_call_after_hours_message, internal_call_after_hours_queue, internal_call_after_hours_phone, internal_call_after_hours_extension, internal_call_after_hours_sip, internal_call_after_hours_voicemail.

  • Capacidade excedida de chamada interna: internal_call_over_capacity_message, internal_call_over_capacity_queue, internal_call_over_capacity_phone, internal_call_over_capacity_extension, internal_call_over_capacity_sip, internal_call_over_capacity_voicemail, internal_call_over_capacity_wait.

  • Redirecionamento automático de chamadas internas: internal_call_automatic_redirection_message, internal_call_automatic_redirection_queue, internal_call_automatic_redirection_phone, internal_call_automatic_redirection_extension, internal_call_automatic_redirection_sip, internal_call_automatic_redirection_voicemail.

  • Transferência de chamadas fora do horário de atendimento: call_transfer_after_hours_message, call_transfer_after_hours_queue, call_transfer_after_hours_phone, call_transfer_after_hours_extension, call_transfer_after_hours_sip, call_transfer_after_hours_voicemail.

  • Capacidade excedida de transferência de chamadas: call_transfer_over_capacity_message, call_transfer_over_capacity_queue, call_transfer_over_capacity_phone, call_transfer_over_capacity_extension, call_transfer_over_capacity_sip, call_transfer_over_capacity_voicemail, call_transfer_over_capacity_wait.

  • Redirecionamento automático de transferência de chamada: call_transfer_automatic_redirection_message, call_transfer_automatic_redirection_queue, call_transfer_automatic_redirection_phone, call_transfer_automatic_redirection_extension, call_transfer_automatic_redirection_sip, call_transfer_automatic_redirection_voicemail.

  • Desligamento de emergência: quando um administrador acionou um desligamento de emergência: emergency_shutdown, emergency_shutdown_message, emergency_shutdown_after_hours, emergency_shutdown_over_capacity.

  • Roteamento dinâmico de chamadas (DCR): dcr_transferred, dcr_missed, dcr_redirected, dcr_finished.

Referenciado em: cada deflection_details[].deflection, que usa esse vocabulário na íntegra. Dois outros campos usam um subconjunto dele:

  • O campo deflection de nível superior usa todos os valores, exceto over_cap_ewt_only e temp_redirection_url.

  • Cada transfers[].deflection usa um subconjunto menor com escopo de transferência: no_deflection, deflecting, deflection_abandoned, os dez valores over_cap_*, os oito valores after_hours_*, os sete valores temp_redirection_* diferentes de temp_redirection_url, ivr_presession_deflection, va_redirection_phone e va_redirection_sip. As famílias internal_call_*, call_transfer_*, emergency_shutdown_*, dcr_* e va_third_party_* nunca aparecem em uma transferência.

Controle de versões e suspensões de uso

O esquema de metadados de sessão de chamada é compatível com versões anteriores. A CCAI Platform pode adicionar novos campos e matrizes a qualquer momento. As integrações precisam ignorar chaves não reconhecidas para garantir a funcionalidade contínua. Os campos desta seção foram descontinuados, são legados ou foram substituídos. Eles permanecem no payload para compatibilidade com versões anteriores, mas as novas integrações precisam seguir as orientações de cada campo.

Campos descontinuados

  • voip_provider (string): descontinuado. Sempre retorna a string literal "deprecated". A plataforma CCAI não mostra mais informações do provedor para integrações por meio deste documento. Não há um campo de substituição. Se a integração precisar identificar o provedor de telefonia upstream, entre em contato com sua equipe de conta.

Duplicatas legadas

  • session_type (string): alias legado de call_type. Sempre retorna o mesmo valor que call_type e usa o mesmo vocabulário de tipo enumerado legado. A CCAI Platform mantém esse campo para compatibilidade com versões anteriores de integrações que usam session_type. As novas integrações precisam analisar call_type diretamente ou, para distinções de entrada mais refinadas, session_type_v2 (consulte Evolução do vocabulário abaixo).

Evolução do vocabulário

call_type e session_type_v2 descrevem o mesmo tipo de chamada usando dois vocabulários diferentes. A plataforma CCAI emite os dois campos em cada registro. Eles não são duplicados:

  • call_type usa o vocabulário de tipo enumerado legado. Valores como Voice Inbound (App) e Voice Inbound (IVR via App) abrangem todas as origens de SDK para dispositivos móveis e no app em um único rótulo. call_type não foi descontinuado. A plataforma da CCAI vai continuar emitindo esse campo, mas o vocabulário dele não vai receber novos valores detalhados.

  • session_type_v2 usa o vocabulário de tipo enumerado atual. Ele introduz distinções de entrada mais refinadas, como Voice Inbound (Mobile) e Voice Inbound (IVR via Mobile), para os tipos de chamada que têm valores específicos da v2. Para tipos de chamada que não têm um valor específico da v2, session_type_v2 retorna a mesma string que call_type.

As novas integrações precisam analisar session_type_v2. Os valores de cada campo estão listados em Informações principais.

Nomenclatura do campo de tempo de espera

O documento de metadados da sessão de chamada informa o tempo de espera na fila em dois escopos, com dois nomes de campo:

  • Total da chamada: o campo wait_duration de nível superior contém o tempo total que o consumidor passou na fila durante toda a chamada.

  • Por segmento: cada entrada na matriz queue_durations de nível superior (Durações da fila) tem o próprio campo queue_duration, que contém o tempo de fila para esse segmento individual.

Os dois nomes se referem ao mesmo tipo de medição (tempo gasto na fila) em escopos diferentes. O total de chamadas wait_duration reflete o tempo geral de fila do consumidor, enquanto os valores queue_duration por segmento descrevem cada segmento de fila. Este documento não emite um campo queue_duration de nível superior separado. Os valores por segmento estão disponíveis apenas em queue_durations.