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 de instruções orienta você no 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 console.

Pré-requisitos

1. Ative as APIs Cloud Storage e Insights no seu Google Cloud projeto.
2. Importe os dados da conversa.

Conversa do chat

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

2. Anote o caminho do objeto, com o 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 do 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 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 aceitos e resultarão em um erro durante a análise da conversa.

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

Analisar uma conversa

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

Uma análise executa uma série de anotadores nos dados da conversa e retorna os resultados na resposta. Por padrão, a análise executa todos os anotadores disponíveis. Opcionalmente, você pode configurar a análise para executar apenas 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 é concluída, o objeto Operation contém 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 realizar essa tarefa, você precisa ter as seguintes permissões:

• contactcenterinsights.analyses.create

REST

Consulte o conversations.analyses:create endpoint de API para detalhes completos.

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

• PROJECT_ID: o Google Cloud ID do projeto.
• CONVERSATION_ID: o ID da conversa que você quer analisar. Esse valor foi retornado na resposta `createConversation`.

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/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. Se quiser 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. Se quiser 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. Se quiser 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() {
  try {
    const [operation] = await client.createAnalysis({
      parent: conversationName,
    });

    // Wait for the operation to complete.
    const [analysis] = await operation.promise();
    console.info(`Created ${analysis.name}`);
  } catch (err) {
    console.error(`createAnalysis failed: ${JSON.stringify(err, null, 2)}`);
    process.exitCode = 1;
  }
}
createAnalysis();

(Opcional) Configurar uma análise

Permissões exigidas para a tarefa

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

• contactcenterinsights.analyses.create

REST

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

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

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

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

Consultar 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. Você pode consultar a operação para verificar o status dela. Consulte a página Operações de longa duração para detalhes e exemplos de código.