Analyser une conversation à l'aide de l'API

Vous pouvez consulter les conversations dans Customer Experience Insights une fois qu'un objet de conversation correspondant a été créé. Ce guide d'utilisation vous explique comment analyser une conversation à l'aide de l'API REST. Si vous préférez, vous pouvez également effectuer ces actions à l'aide de la console CX Insights.

Prérequis

1. Activez les API Cloud Storage et Insights sur votre Google Cloud projet.
2. Importez vos données de conversation.

Conversation par chat

1. Importez la transcription de la conversation par chat en tant qu'objet dans votre bucket Cloud Storage.

2. Notez le chemin d'accès à l'objet au format gs://<bucket>/<object>.

Le fichier de transcription du chat doit être fourni au format JSON et correspondre au format des données de conversation CCAI.

Conversation vocale

1. Importez tous les fichiers d'un bucket Cloud Storage. Les fichiers audio et de transcription doivent être importés en tant qu'objets dans votre bucket Cloud Storage.

2. Notez les deux chemins d'accès aux objets au format gs://<bucket>/<object>.

Les fichiers de transcription doivent être le résultat renvoyé par une transcription de l'API Cloud Speech-to-Text. Plus précisément, ils doivent correspondre à la réponse renvoyée par la reconnaissance audio, qui est identique pour la reconnaissance synchrone et la reconnaissance asynchrone dans toutes les versions de l'API Speech-to-Text. Les autres formats de transcription ne sont pas compatibles et entraîneront une erreur lors de l'analyse de la conversation.

Remarque : Seul l'audio à deux canaux est compatible. Dans le cas contraire, une erreur se produit lors de l'analyse de la conversation.

Analyser une conversation

Une fois qu'un objet Conversation est créé dans CX Insights, il doit être analysé pour produire des résultats utiles. Une même conversation peut être analysée plusieurs fois, et chaque analyse distincte crée un objet Analysis.

Une analyse exécute une série d'annotateurs sur vos données de conversation et renvoie les résultats dans la réponse. Par défaut, l'analyse exécute tous les annotateurs disponibles. Vous pouvez également configurer l'analyse pour n'exécuter que les annotateurs spécifiés.

Une analyse est une opération de longue durée. L'appel de la méthode CreateAnalysis crée un objet Operation qui représente le processus de longue durée. Une fois l'opération terminée, l'objet Operation contient le résultat. Vous pouvez interroger l'objet Operation pour vérifier qu'il est terminé.

Remarque : Si le languageCode champ n'est pas défini, CX Insights l'infère automatiquement. Seul l'anglais (tous les dialectes) est accepté pour les analyses.

Créer une analyse

Autorisations requises pour cette tâche

Pour effectuer cette tâche, vous devez disposer des autorisations suivantes :

• contactcenterinsights.analyses.create

REST

Pour en savoir plus, consultez le conversations.analyses:create point de terminaison de l'API.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

• PROJECT_ID: ID de votre Google Cloud projet.
• CONVERSATION_ID : ID de la conversation que vous souhaitez analyser. Cette valeur a été renvoyée dans la réponse `createConversation`.

Remarque : Tous les exemples utilisent l'instance globale de Customer Experience Insights. Pour savoir comment utiliser des instances régionales, consultez Régionalisation.

Méthode HTTP et URL :

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

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Exécutez la commande suivante :

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)

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

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

Python

Pour vous authentifier auprès de CX Insights, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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

Pour vous authentifier auprès de CX Insights, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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

Pour vous authentifier auprès de CX Insights, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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();

(Facultatif) Configurer une analyse

Autorisations requises pour cette tâche

Pour effectuer cette tâche, vous devez disposer des autorisations suivantes :

• contactcenterinsights.analyses.create

REST

Pour en savoir plus, consultez le conversations.analyses:create point de terminaison de l'API. Incluez tous les annotateurs que vous souhaitez exécuter dans l'objet annotatorSelector et définissez-les sur true. Tous les annotateurs non inclus seront définis par défaut sur false. Si vous ne spécifiez aucun annotateur dans l'objet annotatorSelector, tous les annotateurs seront exécutés.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

• PROJECT_ID: ID de votre Google Cloud projet.
• PHRASE_MATCHER(s) : noms complets des ressources de correspondance d'expressions que vous souhaitez utiliser pour l'annotateur de correspondance d'expressions. Si vous ne renseignez pas ce champ, toutes les correspondances d'expressions actives seront exécutées.
• ISSUE_MODEL(s) : noms complets des ressources des modèles de problèmes que vous souhaitez utiliser pour l'annotateur de modèle de problèmes. Ne fonctionne que si run_issue_model_annotator est défini sur "true". Si vous ne renseignez pas ce champ, tous les modèles de problèmes déployés seront exécutés. Actuellement limité à un modèle déployé.

Remarque : Tous les exemples utilisent l'instance globale de Customer Experience Insights. Pour savoir comment utiliser des instances régionales, consultez Régionalisation.

Méthode HTTP et URL :

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

Corps JSON de la requête :

{
  "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)
  }
}

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, et exécutez la commande suivante :

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)

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, et exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

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

Interroger l'opération

La création d'une analyse renvoie une opération de longue durée. Les méthodes de longue durée sont asynchrones, et l'opération peut ne pas être terminée lorsque la méthode renvoie une réponse. Vous pouvez interroger l'opération pour vérifier son état. Pour en savoir plus et obtenir des exemples de code, consultez la page Opérations de longue durée.