Analyser une conversation à l'aide de l'API

Vous pouvez consulter les conversations dans Customer Experience Insights une fois l'objet de conversation correspondant créé. Ce guide d'utilisation vous explique comment analyser une conversation à l'aide de l'API REST. Si vous le 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 projet Google Cloud .
2. Importez vos données de conversation.

Conversation Chat

1. Importez la transcription de la conversation sous forme d'objet dans votre bucket Cloud Storage.

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

Le fichier de transcription de 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'objet 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, elles doivent correspondre à la réponse renvoyée par la reconnaissance audio, qui est identique pour la reconnaissance synchrone et asynchrone dans toutes les versions de l'API Speech-to-Text. Les autres formats de transcription ne sont pas acceptés et entraîneront une erreur lors de l'analyse de la conversation.

Remarque : Seuls les contenus audio à deux canaux sont acceptés. Sinon, 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. Chaque analyse distincte crée un nouvel 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 qu'elle n'exécute 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 s'il est terminé.

Remarque : Si le champ languageCode 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

Reportez-vous au point de terminaison conversations.analyses:create de l'API pour obtenir des informations complètes.

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

• PROJECT_ID : ID de votre projet Google Cloud .
• 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 Insights sur l'expérience client globale. Pour savoir comment utiliser les 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 les 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 les 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 les 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() {
  const [operation] = await client.createAnalysis({
    parent: conversationName,
  });

  // Wait for the operation to complete.
  const [analysis] = await operation.promise();
  console.info(`Created ${analysis.name}`);
}
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

Reportez-vous au point de terminaison conversations.analyses:create de l'API pour obtenir des informations complètes. Incluez tous les annotateurs que vous souhaitez exécuter dans l'objet annotatorSelector et définissez-les sur true. 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 projet Google Cloud .
• PHRASE_MATCHER(s) : noms de ressources complets des phrase matchers que vous souhaitez utiliser pour l'annotateur de phrase matcher. Si ce champ est vide, tous les expression régulières actives seront exécutées.
• ISSUE_MODEL(s) : noms de ressources complets des modèles de problèmes que vous souhaitez utiliser pour l'annotateur de modèles 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 Insights sur l'expérience client globale. Pour savoir comment utiliser les 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, puis 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, puis 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 risque de ne pas être terminée lorsque la méthode renverra 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.