Usar a API para importar conversas

Saiba como importar arquivos de áudio e transcrição com os metadados usando a API. É possível importar um único arquivo usando a API UploadConversation ou importar todos os arquivos de um bucket do Cloud Storage em massa usando a API IngestConversations.

Os dois comandos de solicitação UploadConversation e IngestConversations oferecem suporte às seguintes funções:

Comando de solicitação	Número de arquivos	Speech-to-Text	Encobrimento	Ingestão de metadados	Análise automática
UploadConversation	1	✔	✔	✔	Com regras de análise ou a porcentagem de análise de conversas de upload nas [configurações](/gemini-enterprise-cx/insights/reference/rest/v1alpha1/Settings#analysisconfig) do projeto
IngestConversations	Todos os arquivos em um bucket	✔	✔	✔	Apenas com regras de análise

Pré-requisitos

1. Ative as APIs Cloud Storage, Speech-to-Text, Proteção de Dados Sensíveis e Customer Experience Insights no Google Cloud projeto que você usa para o Dialogflow.
2. Salve os dados de conversa (arquivos de áudio e transcrição de canal duplo) em um bucket do Cloud Storage usando a classe de armazenamento padrão.
   1. Siga as instruções do início rápido do Cloud Storage para criar um bucket.
   2. Defina o local do bucket como o local mais próximo de você.
   3. Observe as seguintes informações necessárias ao fornecer dados de conversa:
      • Nome do bucket
      • ID do local, formato: us-west1
      • Caminho do objeto, formato: gs://<bucket>/<object>
3. Conceda aos agentes de serviço do Speech-to-Text e do Customer Experience Insights acesso aos objetos no bucket do Cloud Storage. Consulte esta página de solução de problemas para receber ajuda com as contas de serviço.

4. Se você optar por importar metadados de conversa, verifique se os arquivos de metadados estão no próprio bucket e se os nomes dos arquivos de metadados correspondem ao nome do arquivo de conversa.

   Por exemplo, uma conversa com o URI do Cloud Storage gs://transcript-bucket-name/conversation.mp3 precisa ter um arquivo de metadados correspondente, como gs://metadata-bucket-name/conversation.json.

Observação: ao contrário da API UploadConversation, a API IngestConversations não oferece suporte à importação de transcrições com áudio ou à vinculação de áudio com transcrições. Se você tiver áudio e transcrições de conversas, salve-os em buckets separados.

Dados de conversa

Os dados de conversa consistem em transcrições de voz ou chat e áudio.

Transcrições

As transcrições de chat precisam ser fornecidas em arquivos formatados em JSON, em que cada arquivo contém dados de uma única conversa. Os arquivos de texto formatados em JSON incluem o formato de dados de conversa.

As transcrições de voz podem ser fornecidas no formato de dados de conversa ou como o resultado de reconhecimento de fala retornado de uma transcrição da API Speech-to-Text. A resposta é idêntica para reconhecimento síncrono e assíncrono em todas as versões da API Speech-to-Text.

Áudio

O Customer Experience Insights usa o reconhecimento em lote da Cloud Speech-to-Text para transcrever áudio. O CX Insights configura as definições de transcrição da Speech-to-Text com recursos de reconhecedor. É possível criar um reconhecedor personalizado na solicitação ou, se você não fornecer um reconhecedor nas Configurações ou na solicitação, o CX Insights criará um ccai-insights-recognizer padrão no seu projeto.

O reconhecedor do CX Insights transcreve a fala em inglês usando o modelo de telefonia, e o idioma padrão é en-US. Para conferir uma lista completa do suporte da Speech-to-Text por região, idioma, modelo e recurso de reconhecimento, consulte os documentos de suporte de idiomas da Speech-to-Text .

**Observação** :o CX Insights exige a presença de deslocamentos de tempo de palavras, que são um tipo de recurso de reconhecimento da Speech-to-Text.

Antes da primeira importação de áudio para o CX Insights, avalie se você quer:

• Usar uma configuração de transcrição personalizada da Speech-to-Text.
• Analisar as conversas (opcionalmente) encobradas.

É possível configurar essas ações para serem executadas por padrão em cada solicitação UploadConversation ou IngestConversation definindo os campos adequados no recurso de configurações do projeto. As configurações de fala e encobrimento também podem ser substituídas por solicitação. Se você não especificar nenhuma configuração de fala, o CX Insights usará as configurações de fala padrão e não encobrirá as transcrições.

**Observação** :as operações de ingestão de áudio vão ignorar todos os arquivos JSON no bucket do Cloud Storage que você fornecer.

Encobrimento

A Proteção de dados sensíveis não encobre transcrições, a menos que você forneça explicitamente as configurações de encobrimento nas configurações do projeto Settings, na UploadConversationRequest ou na IngestConversationsRequest. A Proteção de dados sensíveis oferece suporte a modelos de inspeção e modelos de desidentificação para encobrimento.

Observação: para garantir que você não importe informações de identificação pessoal para o CX Insights, higienize seus dados antes de importá-los.

Definir configurações do projeto

Permissões exigidas para a tarefa

Para realizar essa tarefa, você precisa ter as seguintes permissões:

• contactcenterinsights.settings.update

O encobrimento e a fala podem ser configurados para solicitações UploadConversation e IngestConversations definindo os parâmetros de configurações do projeto correspondentes. Essas configurações também podem ser definidas individualmente por solicitação, o que substitui as configurações do projeto. A analysis_percentage configurada em uma regra de análise substitui a upload_conversation_analysis_percentage configurada nas configurações do projeto.

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/settings?updateMask=redaction_config,speech_config,analysis_config.upload_conversation_analysis_percentage"

Observação: Se você tiver outros campos definidos, poderá substituir o updateMask por redaction_config, speech_config, ou analysis_config upload_conversation_analysis_percentage para modificar apenas esses campos.

Metadados

Importe metadados em um único arquivo ou como uma importação em massa.

Incluir metadados diretamente na solicitação

Somente para importações de arquivo único, os metadados de qualidade podem ser incluídos diretamente no comando curl para UploadConversationsRequest.

curl --request POST \
  'https://contactcenterinsights.googleapis.com/v1/projects/project-id/locations/location-id/conversations:upload' \
   --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json' \
   --data '{
           "conversation":{
            "qualityMetadata":{
               "agentInfo":[{"agentId":"agent-id","displayName":"agent-name"}]
             },
            "dataSource":{"gcsSource":{"transcriptUri":"transcript-uri"}}}
          }'
  

Importar metadados de arquivos do Cloud Storage

Forneça arquivos de metadados de conversa como arquivos formatados em JSON. Para importações em massa, forneça um bucket especificado no campo gcs_source.metadata_bucket_uri da IngestConversationsRequest. Para importações únicas, forneça um caminho de objeto no campo data_source.metadata_uri da UploadConversationRequest.

Observação: os nomes dos arquivos de metadados fornecidos em um bucket para importação em massa precisam corresponder ao nome do objeto de conversa correspondente. Por exemplo, gs://conversations/conversation.mp3 será correspondido a gs://metadata/conversation.json.

O CX Insights preenche os metadados de qualidade da conversa encontrados no arquivo, mas também é possível criar metadados personalizados.

Por exemplo, para especificar um ID de conversa personalizado para cada conversa no conjunto de dados, especifique metadados personalizados no objeto de conversa no Cloud Storage. Defina a chave como ccai_insights_conversation_id. O valor é o ID de conversa personalizado. Os IDs de conversa personalizados também podem ser fornecidos no arquivo de metadados.

Se você fornecer metadados personalizados no campo custom_metadata_keys de um IngestConversationsRequest, o CX Insights vai armazenar esses metadados personalizados nos rótulos de conversa. Ele oferece suporte a até 100 rótulos.

Consulte o exemplo a seguir de um arquivo de metadados válido que contém o Conversation.quality_metadata recurso, bem como um ID de conversa personalizado e a hora de início da conversa:

{
  "customer_satisfaction_rating": 5,
  "agent_info": [
    {
      "agent_id": "123456",
      "display_name": "Agent Name",
      "team": "Agent Team",
      "disposition_code": "resolved"
    }
  ],
  "custom_key": "custom value"
  "conversation_id": "custom-conversation-id"
  "start_time": "%Y-%m-%d%ET%H:%M:%E*S%Ez"
}

Importar um único arquivo de áudio

Permissões exigidas para a tarefa

Para realizar essa tarefa, você precisa ter as seguintes permissões:

• contactcenterinsights.conversations.upload

A UploadConversation API cria uma operação de longa duração que transcreve e, opcionalmente, encobre suas conversas. Um arquivo de áudio será transcrito se a conversa contiver apenas um audio_uri no DataSource. Caso contrário, o transcript_uri fornecido será lido e usado.

Solicitar corpo JSON:

{ 
  "conversation": { 
    "data_source": { 
      "gcs_source": { "audio_uri": AUDIO_URI }
    }
  },
  "redaction_config": {
    "deidentify_template": DEIDENTIFY_TEMPLATE,
    "inspect_template": INSPECT_TEMPLATE
  },
  "speech_config": {
    "speech_recognizer": RECOGNIZER_NAME
  }
}

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/conversations:upload"

Importação em massa

Permissões exigidas para a tarefa

Para realizar essa tarefa, você precisa ter as seguintes permissões:

• contactcenterinsights.conversations.create

Observação: as conversas já ingeridas no CX Insights serão ignoradas em tentativas de importação em massa subsequentes. O conteúdo do arquivo não é verificado para comparação de duplicação.

Observação: o CX Insights permite apenas uma operação de importação em massa.

REST

Consulte o conversations:ingest endpoint de API para ver todos os detalhes.

Antes de usar os dados da solicitação abaixo, faça estas substituições:

• PROJECT_ID: pelo ID do projeto do Google Cloud Platform.
• GCS_BUCKET_URI: o URI do Cloud Storage que aponta para o bucket que contém as transcrições de conversa. Pode conter um prefixo. Por exemplo, gs://BUCKET_NAME ou gs://BUCKET_NAME/PREFIX. Caracteres curinga não são aceitos.
• MEDIUM: definido como PHONE_CALL ou CHAT, dependendo do tipo de dados. Se não for especificado, o valor padrão será PHONE_CALL.
• AGENT_ID: opcional. ID do agente para todo o bucket.

Observação:todos os exemplos estão usando a instância global do Customer Experience Insights. Consulte Regionalização para instruções sobre como usar instâncias regionais.

Método HTTP e URL:

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations:ingest

Solicitar corpo JSON:

{
  "gcsSource":  {
    "bucketUri": "GCS_BUCKET_URI",
    "bucketObjectType": "AUDIO"
  },
  "transcriptObjectConfig": { "medium": "PHONE_CALL" },
  "conversationConfig": {
    "agentId": "AGENT_ID",
    "agentChannel": "AGENT_CHANNEL",
    "customerChannel": "CUSTOMER_CHANNEL"
  }
}

Or

{
  "gcsSource":  {
    "bucketUri": "GCS_BUCKET_URI",
    "bucketObjectType": "TRANSCRIPT"
  },
  "transcriptObjectConfig": { "medium": "MEDIUM" },
  "conversationConfig": {"agentId": "AGENT_ID"}
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations:ingest"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations:ingest" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.contactcenterinsights.v1main.IngestConversationsMetadata",
    "createTime": "...",
    "request": {
      "parent": "projects/PROJECT_ID/locations/us-central1",
      "gcsSource": {
        "bucketUri": "GCS_BUCKET_URI",
        "bucketObjectType": "BUCKET_OBJECT_TYPE"
      },
      "transcriptObjectConfig": {
        "medium": "MEDIUM"
      },
      "conversationConfig": {
        "agentId": "AGENT_ID"
      }
    }
  }
}

Consultar a operação

As solicitações UploadConversation e IngestConversation retornam uma operação de longa duração. Os métodos de longa duração são assíncronos, e a operação pode não ser concluída quando o método retornar uma resposta. É possível consultar a operação para verificar o status dela. Consulte a página de operações de longa duração para conferir detalhes e exemplos de código.

Cotas da Speech-to-Text

O Customer Experience Insights usa duas APIs Speech-to-Text diferentes: BatchRecognize e GetOperation. O Customer Experience Insights faz uma solicitação BatchRecognize para iniciar a transcrição da Speech-to-Text e uma solicitação GetOperation para monitorar se a transcrição foi concluída. Para iniciar as operações BatchRecognize, uma solicitação BatchRecognize é feita para usar uma cota por minuto e por região. Para monitorar as operações, uma solicitação GetOperation é feita para usar uma cota por minuto e por região.

Para uma única chamada UploadConversation, o Customer Experience Insights consome uma BatchRecognize, mas possivelmente mais solicitações GetOperation, dependendo da duração da tarefa. Para uma importação em massa, o Customer Experience Insights consome 100 solicitações de cada tipo.