Usa la API para importar conversaciones

Aprende a importar archivos de audio y transcripciones con sus metadatos a través de la API. Puedes importar un solo archivo con la API de UploadConversation o importar de forma masiva todos los archivos de un bucket de Cloud Storage con la API de IngestConversations.

Los dos comandos de solicitud UploadConversation y IngestConversations admiten las siguientes funciones:

Comando de solicitud	Cantidad de archivos	Speech‑to‑Text	Ocultamiento	Transferencia de metadatos	Análisis automático
UploadConversation	1	✔	✔	✔	Con reglas de análisis o el porcentaje de análisis de conversaciones cargadas en la [configuración](/contact-center/insights/docs/reference/rest/v1alpha1/Settings#analysisconfig) del proyecto
IngestConversations	Todos los archivos de un bucket	✔	✔	✔	Solo con reglas de análisis

Requisitos previos

1. Habilita las APIs de Cloud Storage, Speech-to-Text, Cloud Data Loss Prevention y Customer Experience Insights en el proyecto Google Cloud que usas para Dialogflow.
2. Guarda los datos de tu conversación (archivos de audio y transcripción de doble canal) en un bucket de Cloud Storage con la clase de almacenamiento estándar.
   1. Sigue las instrucciones de la guía de inicio rápido de Cloud Storage para crear un bucket.
   2. Como ubicación de depósito, selecciona la opción más cercana a donde te encuentres.
   3. Ten en cuenta la siguiente información que necesitas cuando proporciones datos de conversaciones:
      • Nombre del bucket
      • ID de ubicación, formato: us-west1
      • Ruta de acceso del objeto, formato: gs://<bucket>/<object>
3. Otorga a los agentes de servicio de Speech-to-Text y Customer Experience Insights acceso a los objetos de tu bucket de Cloud Storage. Consulta esta página de solución de problemas para obtener ayuda con las cuentas de servicio.

4. Si optas por importar metadatos de conversaciones, asegúrate de que los archivos de metadatos estén en su propio bucket y de que los nombres de los archivos de metadatos coincidan con los nombres de los archivos de conversaciones correspondientes.

   Por ejemplo, una conversación con el URI de Cloud Storage gs://transcript-bucket-name/conversation.mp3 debe tener un archivo de metadatos correspondiente, como gs://metadata-bucket-name/conversation.json.

Nota: A diferencia de la API de UploadConversation, la API de IngestConversations no admite la importación de transcripciones junto con audio ni la vinculación de audio con transcripciones. Si tienes audio de conversaciones y transcripciones, asegúrate de guardarlos en buckets separados.

Datos de conversaciones

Los datos de conversación consisten en transcripciones de voz o chat y audio.

Transcripciones

Las transcripciones de chat deben proporcionarse en archivos con formato JSON, en los que cada archivo contiene datos de una sola conversación. Tus archivos de texto con formato JSON incluyen el formato de datos de conversación.

Las transcripciones de voz se pueden proporcionar en el formato de datos de conversación o como el resultado del reconocimiento de voz devuelto de una transcripción de la API de Speech-to-Text. La respuesta es idéntica para el reconocimiento síncrono y asíncrono en todas las versiones de la API de Speech-to-Text.

Audio

Customer Experience Insights usa el reconocimiento por lotes de Cloud Speech-to-Text para transcribir audio. CX Insights configura los parámetros de transcripción de Speech-to-Text con recursos Recognizer. Puedes crear un reconocedor personalizado en la solicitud o, si no proporcionas un reconocedor en Configuración ni en la solicitud, CX Insights creará un ccai-insights-recognizer predeterminado en tu proyecto.

El reconocedor de CX Insights transcribe el discurso en inglés con el modelo de telefonía, y el idioma predeterminado es en-US. Para obtener una lista completa de la compatibilidad de Speech-to-Text por región, idioma, modelo y función de reconocimiento, consulta la documentación sobre la compatibilidad de idiomas de Speech-to-Text.

Nota: CX Insights requiere la presencia de compensaciones de tiempo de palabras, que son un tipo de función de reconocimiento de Speech-to-Text.

Antes de importar tu primer audio a CX Insights, evalúa si deseas hacer lo siguiente:

• Usar una configuración de transcripción personalizada de Speech-to-Text
• Analiza las conversaciones (opcionalmente) ocultas.

Puedes configurar estas acciones para que se ejecuten de forma predeterminada en cada solicitud UploadConversation o IngestConversation configurando los campos adecuados en el recurso Configuración del proyecto. La configuración de voz y ocultamiento también se puede anular por solicitud. Si no especificas ningún parámetro de configuración de voz, CX Insights usará los parámetros de configuración de voz predeterminados y no ocultará los textos.

Nota: Las operaciones de transferencia de audio omitirán cualquier archivo JSON en el bucket de Cloud Storage que proporciones.

Ocultamiento

Cloud Data Loss Prevention no oculta transcripciones, a menos que proporciones de forma explícita configuraciones de ocultación en la configuración del proyecto, en UploadConversationRequest o en IngestConversationsRequest. Cloud Data Loss Prevention admite plantillas de inspección y plantillas de desidentificación para el ocultamiento.

Nota: Para asegurarte de no importar información de identificación personal a CX Insights, debes depurar tus datos antes de importarlos.

Define la configuración del proyecto

Permisos necesarios para esta tarea

Para realizar esta tarea, debes tener los siguientes permisos:

• contactcenterinsights.settings.update

La redacción y el habla se pueden configurar para las solicitudes de UploadConversation y IngestConversations estableciendo los parámetros de configuración del proyecto correspondientes. Estos parámetros de configuración también se pueden establecer de forma individual por solicitud, lo que anula la configuración del proyecto. El analysis_percentage configurado en una regla de análisis anula el upload_conversation_analysis_percentage configurado a través de la configuración del proyecto.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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"

Nota: Si tienes otros campos configurados, puedes reemplazar updateMask por redaction_config, speech_config o analysis_config upload_conversation_analysis_percentage para modificar solo esos campos.

Metadatos

Importa metadatos en un solo archivo o de forma masiva.

Incluye metadatos directamente en la solicitud

Solo para las importaciones de un solo archivo, tus metadatos de calidad se pueden incluir directamente en el comando curl para 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"}}}
          }'
  

Importa metadatos de archivos de Cloud Storage

Proporciona archivos de metadatos de conversaciones como archivos con formato JSON. Para las importaciones masivas, proporciona un bucket especificado en el campo gcs_source.metadata_bucket_uri de IngestConversationsRequest. Para las importaciones únicas, proporciona una ruta de acceso al objeto en el campo data_source.metadata_uri de UploadConversationRequest.

Nota: Se espera que los nombres de los archivos de metadatos proporcionados en un bucket para la importación masiva coincidan con el nombre del objeto de conversación correspondiente, por ejemplo, gs://conversations/conversation.mp3 coincidirá con gs://metadata/conversation.json.

CX Insights completa los metadatos de calidad de la conversación que se encuentran en el archivo, pero también puedes crear metadatos personalizados.

Por ejemplo, para especificar un ID de conversación personalizado para cada conversación en tu conjunto de datos, especifica metadatos personalizados en el objeto de conversación dentro de Cloud Storage. Establece la clave en ccai_insights_conversation_id. El valor es tu ID de conversación personalizado. También se pueden proporcionar IDs de conversación personalizados en el archivo de metadatos.

Si proporcionas metadatos personalizados en el campo custom_metadata_keys de un objeto IngestConversationsRequest, CX Insights los almacenará en las etiquetas de la conversación. Admite hasta 100 etiquetas.

Consulta el siguiente ejemplo de un archivo de metadatos válido que contiene el recurso Conversation.quality_metadata, así como un ID de conversación personalizado y la hora de inicio de la conversación:

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

Cómo importar un solo archivo de audio

Permisos necesarios para esta tarea

Para realizar esta tarea, debes tener los siguientes permisos:

• contactcenterinsights.conversations.upload

La API de UploadConversation crea una operación de larga duración que transcribe y, de manera opcional, oculta información sensible de tus conversaciones. Se transcribirá un archivo de audio si la conversación solo contiene un audio_uri en el DataSource. De lo contrario, se leerá y usará el transcript_uri proporcionado.

Cuerpo JSON de la solicitud:

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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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"

Importación masiva

Permisos necesarios para esta tarea

Para realizar esta tarea, debes tener los siguientes permisos:

• contactcenterinsights.conversations.create

Nota: Las conversaciones que ya se hayan transferido a CX Insights se omitirán en los intentos posteriores de importación masiva. El contenido de los archivos no se analiza para compararlo con otros y detectar duplicaciones.

Nota: CX Insights solo permite una operación de importación masiva.

REST

Consulta el extremo de la API de conversations:ingest para obtener todos los detalles.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• PROJECT_ID: Es el ID de tu proyecto de Google Cloud Platform.
• GCS_BUCKET_URI: Es el URI de Cloud Storage que apunta al bucket que contiene las transcripciones de la conversación. Puede contener un prefijo. Por ejemplo, gs://BUCKET_NAME o gs://BUCKET_NAME/PREFIX. Los comodines no son compatibles.
• MEDIUM: Se establece en PHONE_CALL o CHAT según el tipo de datos. Si no se especifica, el valor predeterminado es PHONE_CALL.
• AGENT_ID: Opcional Es el ID del agente para todo el bucket.

Nota: Todos los ejemplos usan la instancia global de Customer Experience Insights. Consulta Regionalización para obtener instrucciones sobre el uso de instancias regionales.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Sondea la operación

Las solicitudes UploadConversation y IngestConversation muestran una operación de larga duración. Los métodos de larga duración son asíncronos, y es posible que la operación aún no se haya completado cuando el método muestre una respuesta. Puedes sondear la operación para verificar su estado. Consulta la página de operaciones de larga duración para obtener detalles y muestras de código.

Cuotas de Speech-to-Text

Customer Experience Insights usa dos APIs de Speech-to-Text diferentes: BatchRecognize y GetOperation. Customer Experience Insights realiza una solicitud de BatchRecognizepara iniciar la transcripción de Speech-to-Text y una solicitud de GetOperation para supervisar si la transcripción finalizó o no. Para iniciar las operaciones de BatchRecognize, se realiza una solicitud de BatchRecognize para usar una cuota por minuto y por región. Para supervisar las operaciones, se realiza una solicitud GetOperation para usar una cuota por minuto y por región.

Para una sola llamada a UploadConversation, Customer Experience Insights consume un BatchRecognize, pero posiblemente más solicitudes de GetOperation, según la duración de la tarea. Para una importación masiva, Customer Experience Insights consume 100 solicitudes de cada tipo.