Analiza una conversación con la API

Las conversaciones se pueden ver en Customer Experience Insights después de que se crea un objeto de conversación correspondiente. En esta guía práctica, se explica el proceso para analizar una conversación con la API de REST. Si lo prefieres, también puedes realizar estas acciones con la consola de CX Insights.

Requisitos previos

1. Habilita las APIs de Cloud Storage y Insights en tu proyecto de Google Cloud .
2. Importa tus datos de conversaciones.

Conversación por chat

1. Importa la transcripción del chat de la conversación como un objeto en tu bucket de Cloud Storage.

2. Toma nota de la ruta del objeto, con el formato gs://<bucket>/<object>.

El archivo de transcripción del chat debe proporcionarse como un archivo con formato JSON que coincida con el formato de datos de conversación de la CCAI.

Conversación de voz

1. Importa todos los archivos desde un bucket de Cloud Storage. Los archivos de audio y de transcripción se deben importar como objetos en tu bucket de Cloud Storage.

2. Toma nota de las dos rutas de objetos, con el formato gs://<bucket>/<object>.

Los archivos de transcripción deben ser el resultado devuelto de una transcripción de la API de Cloud Speech-to-Text. Específicamente, deben coincidir con la respuesta que se devuelve del reconocimiento de audio, que es idéntica para el reconocimiento síncrono y el reconocimiento asíncrono en todas las versiones de la API de Speech-to-Text. Otros formatos de transcripción no son compatibles y generarán un error durante el análisis de la conversación.

Nota: Solo se admite el audio con dos canales. De lo contrario, se produce un error durante el análisis de la conversación.

Analiza una conversación

Una vez que se crea un objeto Conversation en CX Insights, se debe analizar para producir resultados útiles. Una misma conversación se puede analizar muchas veces, y cada análisis independiente crea un nuevo objeto Analysis.

Un análisis ejecuta una serie de anotadores en tus datos de conversación y muestra los resultados en la respuesta. De forma predeterminada, el análisis ejecutará todos los anotadores disponibles. De manera opcional, puedes configurar el análisis para que ejecute solo los anotadores especificados.

Un análisis es una operación de larga duración. Llamar al método CreateAnalysis crea un objeto Operation que representa el proceso de larga duración. Una vez que se completa la operación, el objeto Operation contiene el resultado. Puedes sondear el objeto Operation para verificar si se completó.

Nota: Si no se configura el campo languageCode, CX Insights lo inferirá automáticamente. Solo se admite el inglés (todos los dialectos) para los análisis.

Cómo crear un análisis nuevo

Permisos necesarios para esta tarea

Para realizar esta tarea, debes tener los siguientes permisos:

• contactcenterinsights.analyses.create

REST

Consulta el extremo de la API de conversations.analyses:create para obtener todos los detalles.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• PROJECT_ID: Es el ID del proyecto de Google Cloud .
• CONVERSATION_ID: Es el ID de la conversación que deseas analizar. Este valor se devolvió en la respuesta de `createConversation`.

Nota: Todos los ejemplos usan la instancia global de Customer Experience Insights. Consulta Regionalización para obtener instrucciones sobre el uso de instancias regionales.

Método HTTP y URL:

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

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente 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)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente 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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Python

Para autenticarte en CX Insights, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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 autenticarte en CX Insights, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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 autenticarte en CX Insights, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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();

Configura un análisis (opcional)

Permisos necesarios para esta tarea

Para realizar esta tarea, debes tener los siguientes permisos:

• contactcenterinsights.analyses.create

REST

Consulta el extremo de la API de conversations.analyses:create para obtener todos los detalles. Incluye los anotadores que quieras ejecutar en el objeto annotatorSelector y configúralos como true. Los anotadores que no se incluyan se establecerán de forma predeterminada en false. Si no especificas ningún anotador en el objeto annotatorSelector, se ejecutarán todos los anotadores.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• PROJECT_ID: Es el ID del proyecto de Google Cloud .
• PHRASE_MATCHER(s): Son los nombres de recursos completamente calificados del correlacionador de frases de los correlacionadores de frases que deseas usar para el anotador de correlacionador de frases. Si se deja en blanco, se ejecutarán todos los comparadores de frases activos.
• ISSUE_MODEL(s): Son los nombres de recursos completamente calificados de los modelos de problemas que deseas usar para el anotador de modelos de problemas. Solo funciona si run_issue_model_annotator es verdadero. Si se deja vacío, se ejecutarán todos los modelos de problemas implementados. Actualmente, se limita a 1 modelo implementado.

Nota: Todos los ejemplos usan la instancia global de Customer Experience Insights. Consulta Regionalización para obtener instrucciones sobre el uso de instancias regionales.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

{
  "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 tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Sondea la operación

La creación de un análisis devuelve una operación de larga duración. Los métodos de larga duración son asíncronos, y es posible que la operación no se complete cuando el método muestre una respuesta. Puedes sondear la operación para verificar su estado. Consulta la página de operaciones de larga duración para obtener detalles y muestras de código.