Utiliser l'API pour importer des conversations

Découvrez comment importer des fichiers audio et de transcription avec leurs métadonnées à l'aide de l'API. Vous pouvez importer un seul fichier à l'aide de l'API UploadConversation, ou importer en bloc tous les fichiers d'un bucket Cloud Storage à l'aide de l'API IngestConversations.

Les deux commandes de requête UploadConversation et IngestConversations sont compatibles avec les fonctions suivantes :

Commande de requête	Nombre de fichiers	Speech-to-Text	Occultation	Ingestion de métadonnées	Analyse automatique
UploadConversation	1	✔	✔	✔	Avec des règles d'analyse ou le pourcentage d'analyse des conversations importées dans les [paramètres](/contact-center/insights/docs/reference/rest/v1alpha1/Settings#analysisconfig) du projet
IngestConversations	Tous les fichiers d'un bucket	✔	✔	✔	Avec des règles d'analyse uniquement

Prérequis

1. Activez les API Cloud Storage, Speech-to-Text, Cloud Data Loss Prevention et Customer Experience Insights sur le Google Cloud projet que vous utilisez pour Dialogflow.
2. Enregistrez vos données de conversation (fichiers audio et de transcription à deux canaux) dans un bucket Cloud Storage à l'aide de la classe de stockage standard.
   1. Suivez les instructions du guide de démarrage rapide de Cloud Storage pour créer un bucket.
   2. Définissez l'emplacement du bucket sur l'emplacement le plus proche du vôtre.
   3. Notez les informations suivantes dont vous aurez besoin lorsque vous fournirez des données de conversation :
      • Nom du bucket
      • ID d'emplacement, format : us-west1
      • Chemin de l'objet, format : gs://<bucket>/<object>
3. Autorisez les agents de service Speech-to-Text et Customer Experience Insights à accéder aux objets de votre bucket Cloud Storage. Pour obtenir de l'aide concernant les comptes de service, consultez cette page de dépannage.

4. Si vous choisissez d'importer des métadonnées de conversation, assurez-vous que les fichiers de métadonnées se trouvent dans leur propre bucket et que leurs noms correspondent à ceux des fichiers de conversation correspondants.

   Par exemple, une conversation avec l'URI Cloud Storage gs://transcript-bucket-name/conversation.mp3 doit avoir un fichier de métadonnées correspondant, tel que gs://metadata-bucket-name/conversation.json.

Remarque : Contrairement à l'API UploadConversation, l'API IngestConversations n'est pas compatible avec l'importation de transcriptions avec des fichiers audio ni avec l'association de fichiers audio à des transcriptions. Si vous disposez à la fois de fichiers audio et de transcriptions de conversation, veillez à les enregistrer dans des buckets distincts.

Données de conversation

Les données de conversation se composent de transcriptions vocales ou de chat, et de fichiers audio.

Transcriptions

Les transcriptions de chat doivent être fournies dans des fichiers au format JSON, chaque fichier contenant des données pour une seule conversation. Vos fichiers texte au format JSON incluent le format des données de conversation.

Les transcriptions vocales peuvent être fournies au format des données de conversation ou en tant que résultat de reconnaissance vocale renvoyé par une transcription de l'API Speech-to-Text. La réponse est identique pour la reconnaissance synchrone et asynchrone dans toutes les versions de l'API Speech-to-Text.

Audio

Customer Experience Insights utilise la reconnaissance par lots de Cloud Speech-to-Text pour transcrire l'audio. CX Insights configure les paramètres de transcription Speech-to-Text avec des ressources de reconnaissance. Vous pouvez créer un outil de reconnaissance personnalisé dans la requête. Si vous n'en fournissez pas dans les paramètres ou dans la requête, CX Insights crée un outil de reconnaissance ccai-insights-recognizer par défaut dans votre projet.

L'outil de reconnaissance CX Insights transcrit la parole en anglais à l'aide du modèle de téléphonie, et la langue par défaut est l'anglais américain (en-US). Pour obtenir la liste complète de la compatibilité de Speech-to-Text par région, langue, modèle et fonctionnalité de reconnaissance, consultez la documentation sur la compatibilité linguistique de Speech-to-Text language support docs.

**Remarque** : CX Insights nécessite la présence de décalages temporels des mots, qui sont un type de fonctionnalité de reconnaissance Speech-to-Text reconnaissance.

Avant votre première importation audio dans CX Insights, déterminez si vous souhaitez :

• utiliser une configuration de transcription Speech-to-Text personnalisée ;
• analyser les conversations (éventuellement) occultées.

Vous pouvez configurer ces actions pour qu'elles s'exécutent par défaut dans chaque UploadConversation ou IngestConversation requête en définissant les champs appropriés dans la ressource Paramètres du projet. Les paramètres de parole et d'occultation peuvent également être remplacés par requête. Si vous ne spécifiez aucun paramètre de parole, CX Insights utilise les paramètres de parole par défaut et n'occulte pas les transcriptions.

**Remarque** : Les opérations d'ingestion audio ignorent tous les fichiers JSON du bucket Cloud Storage que vous fournissez.

Occultation

Cloud Data Loss Prevention n'occulte pas les transcriptions, sauf si vous fournissez explicitement des configurations d'occultation dans les paramètres du projet, dans UploadConversationRequest ou dans IngestConversationsRequest. Cloud Data Loss Prevention est compatible avec les modèles d'inspection et les modèles de suppression d'identification pour l'occultation.

**Remarque** : Pour vous assurer de n'importer aucune information permettant d'identifier personnellement l'utilisateur dans CX Insights, vous devez assainir vos données vous-même avant de les importer.

Configurer les paramètres du projet

Autorisations requises pour cette tâche

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

• contactcenterinsights.settings.update

L'occultation et la parole peuvent être configurées pour les requêtes UploadConversation et IngestConversations en définissant les paramètres du projet correspondants. Ces configurations peuvent également être définies individuellement par requête, ce qui remplace les paramètres du projet. Le analysis_percentage configuré dans une règle d’analyse remplace le upload_conversation_analysis_percentage configuré via les paramètres du projet.

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/LOCATION_ID/settings?updateMask=redaction_config,speech_config,analysis_config.upload_conversation_analysis_percentage"

Remarque : Si vous avez défini d'autres champs, vous pouvez remplacer updateMask par redaction_config, speech_config, ou analysis_config upload_conversation_analysis_percentage pour ne modifier que ces champs.

Métadonnées

Importez des métadonnées dans un seul fichier ou en bloc.

Inclure des métadonnées directement dans la requête

Pour les importations de fichiers uniques uniquement, vos métadonnées de qualité peuvent être incluses directement dans la commande curl pour UploadConversationsRequest.

curl --request POST \
  'https://contactcenterinsights.googleapis.com/v1/projects/project-id/locations/location-id/conversations:upload' \
   --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json' \
   --data '{
           "conversation":{
            "qualityMetadata":{
               "agentInfo":[{"agentId":"agent-id","displayName":"agent-name"}]
             },
            "dataSource":{"gcsSource":{"transcriptUri":"transcript-uri"}}}
          }'
  

Importer des métadonnées à partir de fichiers Cloud Storage

Fournissez des fichiers de métadonnées de conversation au format JSON. Pour les importations groupées, fournissez un bucket spécifié dans le champ gcs_source.metadata_bucket_uri de IngestConversationsRequest. Pour les importations uniques, fournissez un chemin d'objet dans le champ data_source.metadata_uri de UploadConversationRequest.

Remarque : Les noms des fichiers de métadonnées fournis dans un bucket pour l'importation groupée doivent correspondre à ceux de l'objet de conversation correspondant. Par exemple, gs://conversations/conversation.mp3 sera associé à gs://metadata/conversation.json.

CX Insights remplit les métadonnées de qualité de la conversation trouvées dans le fichier, mais vous pouvez également créer des métadonnées personnalisées.

Par exemple, pour spécifier un ID de conversation personnalisé pour chaque conversation de votre ensemble de données, spécifiez des métadonnées personnalisées sur l'objet de conversation dans Cloud Storage. Définissez la clé sur ccai_insights_conversation_id. La valeur correspond à votre ID de conversation personnalisé. Des ID de conversation personnalisés peuvent également être fournis dans le fichier de métadonnées.

Si vous fournissez des métadonnées personnalisées dans le champ custom_metadata_keys d'une IngestConversationsRequest, CX Insights les stocke dans les libellés de conversation. Il est compatible avec un maximum de 100 libellés.

Voici un exemple de fichier de métadonnées valide contenant la ressource Conversation.quality_metadata, ainsi qu'un ID de conversation personnalisé et l'heure de début de la conversation :

{
  "customer_satisfaction_rating": 5,
  "agent_info": [
    {
      "agent_id": "123456",
      "display_name": "Agent Name",
      "team": "Agent Team",
      "disposition_code": "resolved"
    }
  ],
  "custom_key": "custom value"
  "conversation_id": "custom-conversation-id"
  "start_time": "%Y-%m-%d%ET%H:%M:%E*S%Ez"
}

Importer un seul fichier audio

Autorisations requises pour cette tâche

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

• contactcenterinsights.conversations.upload

L'UploadConversation API crée une opération de longue durée qui transcrit et, éventuellement, occulte vos conversations. Un fichier audio est transcrit si la conversation ne contient qu'un audio_uri dans le DataSource. Sinon, le transcript_uri fourni est lu et utilisé.

Corps JSON de la requête :

{ 
  "conversation": { 
    "data_source": { 
      "gcs_source": { "audio_uri": AUDIO_URI }
    }
  },
  "redaction_config": {
    "deidentify_template": DEIDENTIFY_TEMPLATE,
    "inspect_template": INSPECT_TEMPLATE
  },
  "speech_config": {
    "speech_recognizer": RECOGNIZER_NAME
  }
}

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/LOCATION_ID/conversations:upload"

Importation par lots

Autorisations requises pour cette tâche

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

• contactcenterinsights.conversations.create

Remarque : Les conversations déjà ingérées dans CX Insights sont ignorées lors des tentatives d’importation groupée ultérieures. Le contenu des fichiers n'est pas analysé pour la comparaison des doublons.

Remarque : CX Insights n'autorise qu'une seule opération d'importation groupée.

REST

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

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

• PROJECT_ID : ID de votre projet Google Cloud Platform.
• GCS_BUCKET_URI : URI Cloud Storage qui pointe vers le bucket contenant les transcriptions de conversation. Peut contenir un préfixe. Par exemple, gs://BUCKET_NAME ou gs://BUCKET_NAME/PREFIX. Les caractères génériques ne peuvent pas être utilisés.
• MEDIUM : défini sur PHONE_CALL ou CHAT selon le type de données. Si aucune valeur n'est spécifiée, la valeur par défaut est PHONE_CALL.
• AGENT_ID : facultatif. ID d'agent pour l'ensemble du bucket.

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

Méthode HTTP et URL :

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

Corps JSON de la requête :

{
  "gcsSource":  {
    "bucketUri": "GCS_BUCKET_URI",
    "bucketObjectType": "AUDIO"
  },
  "transcriptObjectConfig": { "medium": "PHONE_CALL" },
  "conversationConfig": {
    "agentId": "AGENT_ID",
    "agentChannel": "AGENT_CHANNEL",
    "customerChannel": "CUSTOMER_CHANNEL"
  }
}

Or

{
  "gcsSource":  {
    "bucketUri": "GCS_BUCKET_URI",
    "bucketObjectType": "TRANSCRIPT"
  },
  "transcriptObjectConfig": { "medium": "MEDIUM" },
  "conversationConfig": {"agentId": "AGENT_ID"}
}

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:ingest"

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:ingest" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.contactcenterinsights.v1main.IngestConversationsMetadata",
    "createTime": "...",
    "request": {
      "parent": "projects/PROJECT_ID/locations/us-central1",
      "gcsSource": {
        "bucketUri": "GCS_BUCKET_URI",
        "bucketObjectType": "BUCKET_OBJECT_TYPE"
      },
      "transcriptObjectConfig": {
        "medium": "MEDIUM"
      },
      "conversationConfig": {
        "agentId": "AGENT_ID"
      }
    }
  }
}

Interroger l'opération

Les requêtes UploadConversation et IngestConversation renvoient 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.

Quotas Speech-to-Text

Customer Experience Insights utilise deux API Speech-to-Text différentes : BatchRecognize et GetOperation. Customer Experience Insights envoie une requête BatchRecognize pour démarrer la transcription Speech-to-Text et une requête GetOperation pour vérifier si la transcription est terminée. Pour démarrer les opérations BatchRecognize, une requête BatchRecognize est envoyée afin d'utiliser un quota par minute et par région. Pour surveiller les opérations, une requête GetOperation est envoyée afin d'utiliser un quota par minute et par région.

Pour un seul appel UploadConversation, Customer Experience Insights consomme une requête BatchRecognize, mais peut-être plus de requêtes GetOperation, en fonction de la durée de la tâche. Pour une importation groupée, Customer Experience Insights consomme 100 requêtes de chaque type.