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 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 les 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 projet Google Cloud 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 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 de lieu, format : us-west1
      • Chemin d'accès à l'objet, format : gs://<bucket>/<object>
  3. Donnez aux agents de service Speech-to-Text et Customer Experience Insights l'accès 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 les noms de fichiers de métadonnées 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.

Données de conversation

Les données de conversation se composent de transcriptions vocales ou de chat, et de données 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 de 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 lot de Cloud Speech-to-Text pour transcrire l'audio. CX Insights configure les paramètres de transcription Speech-to-Text avec des ressources Recognizer. Vous pouvez créer un outil de reconnaissance personnalisé dans la requête. Si vous n'en fournissez pas dans les paramètres ni dans la requête, CX Insights crée un ccai-insights-recognizer par défaut dans votre projet.

Le module de reconnaissance CX Insights transcrit la parole en anglais à l'aide du modèle de téléphonie. La langue par défaut est l'anglais américain (en-US). Pour obtenir la liste complète des fonctionnalités Speech-to-Text disponibles par région, langue, modèle et fonctionnalité de reconnaissance, consultez la documentation sur les langues acceptées.

Avant d'importer votre premier fichier audio dans CX Insights, déterminez si vous souhaitez :

  • Utilisez une configuration de transcription Speech-to-Text personnalisée.
  • Analysez les conversations (éventuellement masquées).

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

Occultation

Cloud Data Loss Prevention ne masque pas les transcriptions, sauf si vous fournissez explicitement des configurations de masquage 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 le masquage.

Configurer les paramètres du projet

La rédaction et la reconnaissance vocale peuvent être configurées pour les requêtes UploadConversation et IngestConversations en définissant les paramètres de projet correspondants. Ces configurations peuvent également être définies individuellement pour chaque 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é dans 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"

Métadonnées

Importez des métadonnées dans un fichier unique ou de manière groupée.

Inclure les 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 les 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.

CX Insights renseigne les métadonnées sur la qualité des conversations 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é. Vous pouvez également fournir des ID de conversation personnalisés dans le fichier de métadonnées.

Si vous fournissez des métadonnées personnalisées dans le champ custom_metadata_keys d'un IngestConversationsRequest, CX Insights les stocke dans les libellés de la conversation. Il accepte jusqu'à 100 étiquettes.

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

L'API UploadConversation crée une opération de longue durée qui transcrit et, si vous le souhaitez, masque vos conversations. Un fichier audio sera transcrit si la conversation ne contient qu'un audio_uri dans le DataSource. Sinon, le transcript_uri fourni sera 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

REST

Reportez-vous au point de terminaison conversations:ingest 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 Platform.
  • GCS_BUCKET_URI : URI Cloud Storage qui pointe vers le bucket contenant les transcriptions de conversations. 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.

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 :

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 il est possible que l'opération ne soit pas encore 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 lancer 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 pour 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 un BatchRecognize, mais peut-être plus de requêtes GetOperation, en fonction de la durée de la tâche. Pour une importation groupée, Insights sur l'expérience client consomme 100 requêtes de chaque type.