Analisar uma conversa usando a API

As conversas podem ser visualizadas no Customer Experience Insights depois que um objeto de conversa correspondente é criado. Este guia prático mostra o processo de análise de uma conversa usando a API REST. Se preferir, você também pode realizar essas ações usando o console do CX Insights.

Pré-requisitos

1. Ative as APIs Cloud Storage e Insights no seu projeto do Google Cloud .
2. Importe seus dados de conversa.

Conversa do Chat

1. Importe a transcrição da conversa como um objeto no bucket do Cloud Storage.

2. Anote o caminho do objeto no formato gs://<bucket>/<object>.

O arquivo de transcrição do chat precisa ser fornecido como um arquivo formatado em JSON que corresponda ao formato de dados de conversa da CCAI.

Conversa por voz

1. Importe todos os arquivos de um bucket do Cloud Storage. Os arquivos de áudio e transcrição precisam ser importados como objetos no seu bucket do Cloud Storage.

2. Anote os dois caminhos de objeto, com o formato gs://<bucket>/<object>.

Os arquivos de transcrição precisam ser o resultado retornado de uma transcrição da API Cloud Speech-to-Text. Especificamente, eles precisam corresponder à resposta retornada do reconhecimento de áudio, que é idêntica para reconhecimento síncrono e assíncrono em todas as versões da API Speech-to-Text. Outros formatos de transcrição não são compatíveis e vão resultar em um erro durante a análise de conversa.

Observação :apenas áudio com dois canais é aceito. Caso contrário, um erro vai ocorrer durante a análise da conversa.

Analisar uma conversa

Depois que um objeto Conversation é criado no CX Insights, ele precisa ser analisado para gerar resultados úteis. Uma única conversa pode ser analisada várias vezes, e cada análise separada cria um novo objeto Analysis.

Uma análise executa uma série de anotadores nos dados de conversa e retorna os resultados na resposta. Por padrão, a análise executa todos os anotadores disponíveis. Se quiser, configure a análise para executar somente os anotadores especificados.

Uma análise é uma operação de longa duração. Chamar o método CreateAnalysis cria um objeto Operation que representa o processo de longa duração. Depois que a operação for concluída, o objeto Operation vai conter o resultado. Você pode consultar o objeto Operation para verificar a conclusão.

Observação: se o campo languageCode não estiver definido, o CX Insights vai inferir automaticamente. Somente o inglês (todos os dialetos) é aceito para análises.

Criar uma nova análise

Permissões exigidas para a tarefa

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

• contactcenterinsights.analyses.create

REST

Consulte o endpoint da API conversations.analyses:create 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 Google Cloud .
• CONVERSATION_ID: o ID da conversa que você quer analisar. Esse valor foi retornado na resposta `createConversation`.

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/CONVERSATION_ID/analyses

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.

Execute o seguinte comando:

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

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.

Execute o seguinte comando:

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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID"
}

Python

Para autenticar no CX Insights, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

from google.cloud import contact_center_insights_v1


def create_analysis(conversation_name: str) -> contact_center_insights_v1.Analysis:
    """Creates an analysis.

    Args:
        conversation_name:
            The parent resource of the analysis.
            Format is 'projects/{project_id}/locations/{location_id}/conversations/{conversation_id}'.
            For example, 'projects/my-project/locations/us-central1/conversations/123456789'.

    Returns:
        An analysis.
    """
    # Construct an analysis.
    analysis = contact_center_insights_v1.Analysis()

    # Call the Insights client to create an analysis.
    insights_client = contact_center_insights_v1.ContactCenterInsightsClient()
    analysis_operation = insights_client.create_analysis(
        parent=conversation_name, analysis=analysis
    )
    analysis = analysis_operation.result(timeout=86400)
    print(f"Created {analysis.name}")
    return analysis

Java

Para autenticar no CX Insights, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import com.google.cloud.contactcenterinsights.v1.Analysis;
import com.google.cloud.contactcenterinsights.v1.ContactCenterInsightsClient;
import java.io.IOException;

public class CreateAnalysis {

  public static void main(String[] args) throws Exception, IOException {
    // TODO(developer): Replace this variable before running the sample.
    String conversationName =
        "projects/my_project_id/locations/us-central1/conversations/my_conversation_id";

    createAnalysis(conversationName);
  }

  public static Analysis createAnalysis(String conversationName) throws Exception, IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ContactCenterInsightsClient client = ContactCenterInsightsClient.create()) {
      // Construct an analysis.
      Analysis analysis = Analysis.newBuilder().build();

      // Call the Insights client to create an analysis.
      Analysis response = client.createAnalysisAsync(conversationName, analysis).get();
      System.out.printf("Created %s%n", response.getName());
      return response;
    }
  }
}

Node.js

Para autenticar no CX Insights, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const conversationName = 'projects/my_project_id/locations/us-central1/conversations/my_conversation_id';

// Imports the Contact Center Insights client.
const {
  ContactCenterInsightsClient,
} = require('@google-cloud/contact-center-insights');

// Instantiates a client.
const client = new ContactCenterInsightsClient();

async function createAnalysis() {
  const [operation] = await client.createAnalysis({
    parent: conversationName,
  });

  // Wait for the operation to complete.
  const [analysis] = await operation.promise();
  console.info(`Created ${analysis.name}`);
}
createAnalysis();

(Opcional) Configurar uma análise

Permissões exigidas para a tarefa

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

• contactcenterinsights.analyses.create

REST

Consulte o endpoint da API conversations.analyses:create para ver todos os detalhes. Inclua os anotadores que você quer executar no objeto annotatorSelector e defina-os como true. Os anotadores não incluídos vão usar false por padrão. Se você não especificar nenhum anotador no objeto annotatorSelector, todos serão executados.

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

• PROJECT_ID: o ID do projeto Google Cloud .
• PHRASE_MATCHER(s): os nomes de recursos totalmente qualificados dos comparadores de frases que você quer usar para o anotador de comparadores de frases. Se deixado em branco, todos os comparadores de frases ativos serão executados.
• ISSUE_MODEL(s): os nomes de recursos totalmente qualificados dos modelos de problema que você quer usar para o anotador de modelo de problema. Só funciona se run_issue_model_annotator for verdadeiro. Se deixado em branco, todos os modelos de problemas implantados serão executados. No momento, limitado a um modelo implantado.

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/CONVERSATION_ID/analyses

Corpo JSON da solicitação:

{
  "annotatorSelector": {
    "run_interruption_annotator": {true/false},
    "run_silence_annotator": {true/false},
    "run_phrase_matcher_annotator": {true/false},
    "phrase_matchers": PHRASE_MATCHER(s),
    "run_sentiment_annotator": {true/false},
    "run_entity_annotator": {true/false},
    "run_intent_annotator": {true/false},
    "run_issue_model_annotator": {true/false}
    "issue_models": ISSUE_MODEL(s)
  }
}

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/CONVERSATION_ID/analyses"

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/CONVERSATION_ID/analyses" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID"
}

Pesquisar a operação

A criação de uma análise retorna 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.