Utilizzare l'API per importare le conversazioni

Scopri come importare file audio e di trascrizione con i relativi metadati utilizzando l'API. Puoi importare un singolo file utilizzando l'API UploadConversation oppure importare in blocco tutti i file da un bucket Cloud Storage utilizzando l'API IngestConversations.

I due comandi di richiesta UploadConversation e IngestConversations supportano le seguenti funzioni:

Richiedi comando Numero di file Speech-to-Text Oscuramento Importazione dei metadati Analisi automatica
UploadConversation 1 ✔ ✔ ✔ Con le regole di analisi o la percentuale di analisi delle conversazioni caricate nel progetto [impostazioni](/contact-center/insights/docs/reference/rest/v1alpha1/Settings#analysisconfig)
IngestConversations Tutti i file in un bucket ✔ ✔ ✔ Solo con le regole di analisi

Prerequisiti

  1. Abilita le API Cloud Storage, Speech-to-Text, Cloud Data Loss Prevention e Customer Experience Insights nel progetto Google Cloud che utilizzi per Dialogflow.
  2. Salva i dati delle conversazioni (file audio e di trascrizione a due canali) in un bucket Cloud Storage utilizzando la classe di archiviazione standard.
    1. Segui le istruzioni della guida rapida di Cloud Storage per creare un bucket.
    2. Imposta la posizione del bucket su una posizione più vicina alla tua.
    3. Tieni presente le seguenti informazioni necessarie quando fornisci i dati delle conversazioni:
      • Nome bucket
      • ID località, formato: us-west1
      • Percorso oggetto, formato: gs://<bucket>/<object>
  3. Concedi agli agenti di servizio Speech-to-Text e Customer Experience Insights l'accesso agli oggetti nel bucket Cloud Storage. Per assistenza con i service account, consulta questa pagina per la risoluzione dei problemi.

  4. Se scegli di importare i metadati delle conversazioni, assicurati che i file di metadati si trovino nel proprio bucket e che i nomi dei file di metadati corrispondano a quelli delle conversazioni corrispondenti.

    Ad esempio, una conversazione con l'URI Cloud Storage gs://transcript-bucket-name/conversation.mp3 deve avere un file di metadati corrispondente, ad esempio gs://metadata-bucket-name/conversation.json.

Dati relativi alle conversazioni

I dati delle conversazioni sono costituiti da trascrizioni vocali o di chat e audio.

Trascrizioni

Le trascrizioni delle chat devono essere fornite in file in formato JSON, in cui ogni file contiene i dati di una singola conversazione. I file di testo in formato JSON includono il formato dei dati della conversazione.

Le trascrizioni vocali possono essere fornite nel formato dei dati della conversazione o come risultato del riconoscimento vocale restituito di una trascrizione dell'API Speech-to-Text. La risposta è identica per il riconoscimento sincrono e asincrono in tutte le versioni dell'API Speech-to-Text.

Audio

Customer Experience Insights utilizza il riconoscimento batch di Cloud Speech-to-Text per trascrivere l'audio. CX Insights configura le impostazioni di trascrizione di Speech-to-Text con le risorse Recognizer. Puoi creare un riconoscitore personalizzato nella richiesta oppure, se non fornisci un riconoscitore nelle Impostazioni o nella richiesta, CX Insights crea un ccai-insights-recognizer predefinito nel tuo progetto.

Il riconoscitore CX Insights trascrive il parlato in inglese utilizzando il modello di telefonia e la lingua predefinita è en-US. Per un elenco completo del supporto di Speech-to-Text per regione, lingua, modello e funzionalità di riconoscimento, consulta la documentazione sul supporto delle lingue di Speech-to-Text.

Prima della prima importazione audio in CX Insights, valuta se vuoi:

  • Utilizza una configurazione di trascrizione Speech-to-Text personalizzata.
  • Analizza le conversazioni (facoltativamente) oscurate.

Puoi configurare queste azioni in modo che vengano eseguite per impostazione predefinita in ogni richiesta UploadConversation o IngestConversation impostando i campi appropriati nella risorsa Settings del progetto. Le impostazioni di sintesi vocale e oscuramento possono anche essere sostituite per richiesta. Se non specifichi alcuna impostazione di sintesi vocale, CX Insights utilizzerà le impostazioni di sintesi vocale predefinite e non oscurerà le trascrizioni.

Oscuramento

Cloud Data Loss Prevention non oscura le trascrizioni, a meno che tu non fornisca esplicitamente le configurazioni di oscuramento nelle Impostazioni del progetto, in UploadConversationRequest o in IngestConversationsRequest. Cloud Data Loss Prevention supporta sia i modelli di ispezione sia i modelli di anonimizzazione per la redazione.

Configura le impostazioni del progetto

La redazione e la sintesi vocale possono essere configurate per le richieste UploadConversation e IngestConversations impostando i parametri delle impostazioni del progetto corrispondenti. Queste configurazioni possono essere impostate anche singolarmente per richiesta, il che esegue l'override delle impostazioni del progetto. Il analysis_percentage configurato in una regola di analisi sostituisce il upload_conversation_analysis_percentage configurato tramite le impostazioni del progetto.

Salva il corpo della richiesta in un file denominato request.json ed esegui il comando seguente:

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"

Metadati

Importa i metadati in un unico file o come importazione collettiva.

Includere i metadati direttamente nella richiesta

Solo per le importazioni di un singolo file, i metadati di qualità possono essere inclusi direttamente nel comando curl per 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"}}}
          }'

Importare metadati da file Cloud Storage

Fornisci i file di metadati delle conversazioni come file in formato JSON. Per le importazioni collettive, fornisci un bucket specificato nel campo gcs_source.metadata_bucket_uri di IngestConversationsRequest. Per le importazioni singole, fornisci un percorso dell'oggetto nel campo data_source.metadata_uri di UploadConversationRequest.

CX Insights compila i metadati sulla qualità della conversazione trovati nel file, ma puoi anche creare metadati personalizzati.

Ad esempio, per specificare un ID conversazione personalizzato per ogni conversazione nel set di dati, specifica metadati personalizzati nell'oggetto conversazione in Cloud Storage. Imposta la chiave su ccai_insights_conversation_id. Il valore è l'ID conversazione personalizzato. Gli ID conversazione personalizzati possono essere forniti anche all'interno del file di metadati.

Se fornisci metadati personalizzati nel campo custom_metadata_keys di un IngestConversationsRequest, CX Insights li memorizza nelle etichette della conversazione. Supporta fino a 100 etichette.

Vedi il seguente esempio di un file di metadati valido contenente la risorsa Conversation.quality_metadata, nonché un ID conversazione personalizzato e l'ora di inizio della conversazione:

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

Importare un singolo file audio

L'API UploadConversation crea un'operazione a lunga esecuzione che trascrive e, facoltativamente, redige le tue conversazioni. Un file audio verrà trascritto se la conversazione contiene solo un audio_uri in DataSource. In caso contrario, verrà letto e utilizzato il valore transcript_uri fornito.

Corpo JSON della richiesta:

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

Salva il corpo della richiesta in un file denominato request.json ed esegui il comando seguente:

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"

Importazione collettiva

REST

Per informazioni dettagliate, consulta l'endpoint API conversations:ingest.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud Platform.
  • GCS_BUCKET_URI: l'URI Cloud Storage che punta al bucket contenente le trascrizioni delle conversazioni. Potrebbe contenere un prefisso. Ad esempio gs://BUCKET_NAME o gs://BUCKET_NAME/PREFIX. I caratteri jolly non sono supportati.
  • MEDIUM: imposta su PHONE_CALL o CHAT a seconda del tipo di dati. Se non specificato, il valore predefinito è PHONE_CALL.
  • AGENT_ID: (Facoltativo) ID agente per l'intero bucket.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:


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

Esegui il sondaggio dell'operazione

Sia la richiesta UploadConversation che quella IngestConversation restituiscono un'operazione a lunga esecuzione. I metodi a esecuzione prolungata sono asincroni e l'operazione potrebbe non essere ancora completata quando il metodo restituisce una risposta. Puoi eseguire il polling dell'operazione per verificarne lo stato. Per dettagli ed esempi di codice, consulta la pagina delle operazioni di lunga durata.

Quote di Speech-to-Text

Customer Experience Insights utilizza due API Speech-to-Text diverse: BatchRecognize e GetOperation. Customer Experience Insights effettua una richiesta BatchRecognizeper avviare la trascrizione di Speech-to-Text e una richiesta GetOperationper monitorare se la trascrizione è terminata o meno. Per avviare le operazioni BatchRecognize, viene effettuata una richiesta BatchRecognize per utilizzare una quota al minuto per regione. Per monitorare le operazioni, viene inviata una richiesta GetOperation per utilizzare una quota al minuto per regione.

Per una singola chiamata UploadConversation, Customer Experience Insights utilizza un BatchRecognize, ma possibilmente più richieste GetOperation, a seconda della durata dell'attività. Per un'importazione collettiva, Customer Experience Insights utilizza 100 richieste di ogni tipo.