Usar a API para importar conversas

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

Os dois comandos de solicitação UploadConversation e IngestConversations são compatíveis com as 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 conversa de upload nas [configurações](/contact-center/insights/docs/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, Cloud Data Loss Prevention e Customer Experience Insights no projeto do Google Cloud que você usa para o Dialogflow.
2. Salve os dados da conversa (áudio de dois canais e arquivos de transcrição) em um bucket do Cloud Storage usando a classe de armazenamento padrão.
   1. Siga as instruções do guia de 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 seu bucket do Cloud Storage. Consulte esta página de solução de problemas para receber ajuda com contas de serviço.

4. Se você optar por importar metadados de conversas, verifique se os arquivos de metadados estão em um bucket próprio e se os nomes dos arquivos de metadados correspondem aos nomes dos arquivos de conversas.

   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 nem à 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. Seus 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 do reconhecimento de fala retornado de uma transcrição da API Speech-to-Text. A resposta é idêntica para o 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 opções de transcrição da Speech-to-Text com recursos Recognizer. É possível criar um reconhecedor personalizado na solicitação ou, se você não fornecer um reconhecedor em Configurações ou na solicitação, o CX Insights vai 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 de suporte do Speech-to-Text por região, idioma, modelo e recurso de reconhecimento, consulte a documentação de suporte a idiomas do 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 de importar o primeiro áudio para o CX Insights, avalie se você quer:

• Use uma configuração personalizada de transcrição do Speech-to-Text.
• Analise as conversas (opcionalmente) redigidas.

É 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 Configurações do projeto. As configurações de fala e redação também podem ser substituídas por solicitação. Se você não especificar nenhuma configuração de fala, o CX Insights vai usar as configurações padrão e não vai 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 Cloud Data Loss Prevention não edita transcrições, a menos que você forneça explicitamente configurações de edição nas Configurações do projeto, no UploadConversationRequest ou no IngestConversationsRequest. O Cloud Data Loss Prevention é compatível com modelos de inspeção e modelos de desidentificação para edição.

Observação: para não importar informações de identificação pessoal para o CX Insights, limpe os dados antes da importação.

Definir configurações do projeto

Permissões exigidas para a tarefa

Para executar essa tarefa, é necessário ter permissões:

• contactcenterinsights.settings.update

A redação e a fala podem ser configuradas para solicitações UploadConversation e IngestConversations definindo os parâmetros correspondentes nas configurações do projeto. Essas configurações também podem ser definidas individualmente por solicitação, substituindo as configurações do projeto. O analysis_percentage configurado em uma regra de análise substitui o upload_conversation_analysis_percentage configurado 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, substitua 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 em massa.

Incluir metadados diretamente na solicitação

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 no formato JSON. Para importações em massa, forneça um bucket especificado no campo gcs_source.metadata_bucket_uri do IngestConversationsRequest. Para importações únicas, forneça um caminho de objeto no campo data_source.metadata_uri do 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á associado a gs://metadata/conversation.json.

O CX Insights preenche os metadados de qualidade da conversa encontrados no arquivo, mas você também pode 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 da conversa personalizada. 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 da conversa. Ele aceita até 100 rótulos.

Confira o exemplo a seguir de um arquivo de metadados válido que contém o recurso Conversation.quality_metadata, além de um ID de conversa personalizado e o horário 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 executar essa tarefa, é necessário ter permissões:

• contactcenterinsights.conversations.upload

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

Corpo JSON da solicitação:

{ 
  "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 executar essa tarefa, é necessário ter permissões:

• contactcenterinsights.conversations.create

Observação: as conversas já ingeridas no CX Insights serão ignoradas nas 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 endpoint da API conversations:ingest para ver todos os detalhes.

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

• PROJECT_ID: é o ID do projeto do Google Cloud Platform.
• GCS_BUCKET_URI: o URI do Cloud Storage que aponta para o bucket com 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 usam 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

Corpo JSON da solicitação:

{
  "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 abaixo:

$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"
      }
    }
  }
}

Pesquisar 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 retorna uma resposta. É possível pesquisar a operação para verificar o status dela. Consulte a página de operações de longa duração para detalhes e exemplos de código.

Cotas do 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 ou não. Para iniciar 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 um 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.