Usa la API para importar conversaciones

Obtén información para importar archivos de audio y transcripción con sus metadatos mediante 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 conversación de carga en [configuración](/gemini-enterprise-cx/insights/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, Sensitive Data Protection y Customer Experience Insights en el Google Cloud proyecto que usas para Dialogflow.
2. Guarda los datos de tus conversaciones (archivos de audio y transcripción de dos canales) 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 bucket, selecciona la opción más cercana a donde te encuentres.
   3. Ten en cuenta la siguiente información que necesitas cuando proporcionas 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 eliges importar metadatos de conversaciones, asegúrate de que los archivos de metadatos estén en su propio bucket y que los nombres de los archivos de metadatos coincidan con los nombres de los archivos de conversación 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 y transcripciones de conversaciones, asegúrate de guardarlos en buckets separados.

Datos de conversaciones

Los datos de conversaciones 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. Los archivos de texto con formato JSON incluyen el formato de datos de conversaciones.

Las transcripciones de voz se pueden proporcionar en el formato de datos de conversaciones o como el resultado de reconocimiento de voz que muestra 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 configuración de transcripción de Speech-to-Text con recursos de Recognizer. Puedes crear un reconocedor personalizado en la solicitud o, si no proporcionas un reconocedor en Configuración o en la solicitud, CX Insights crea 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 los documentos de 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 tu primera importación de audio a CX Insights, evalúa si deseas hacer lo siguiente:

• Usar una configuración de transcripción de Speech-to-Text personalizada
• Analizar las conversaciones ocultas (opcional)

Puedes configurar estas acciones para que se ejecuten de forma predeterminada en cada solicitud de UploadConversation o IngestConversation si configuras los campos adecuados en el recurso de 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á la configuración de voz predeterminada y no ocultará las transcripciones.

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

Ocultamiento

Sensitive Data Protection no oculta las transcripciones, a menos que proporciones de forma explícita las configuraciones de ocultamiento en la configuración del proyecto Settings, UploadConversationRequest o IngestConversationsRequest. Sensitive Data Protection 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 desinfectar 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

El ocultamiento y la voz se pueden configurar para las solicitudes de UploadConversation y IngestConversations si se configuran los parámetros correspondientes de la configuración del proyecto. Estas configuraciones 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 como una importación masiva.

Incluye metadatos directamente en la solicitud

Solo para 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 desde 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 del 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 propaga 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 dentro del archivo de metadatos.

Si proporcionas metadatos personalizados en el campo custom_metadata_keys de un IngestConversationsRequest, CX Insights almacena esos metadatos personalizados en las etiquetas de conversación. Admite hasta 100 etiquetas.

Consulta el siguiente ejemplo de un archivo de metadatos válido que contiene el Conversation.quality_metadata recurso, 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"
}

Importa un solo archivo de audio

Permisos necesarios para esta tarea

Para realizar esta tarea, debes tener los siguientes permisos:

• contactcenterinsights.conversations.upload

La UploadConversation API crea una operación de larga duración que transcribe y, de manera opcional, oculta tus conversaciones. Se transcribirá un archivo de audio si la conversación contiene solo 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 transfirieron a CX Insights se omitirán en los intentos posteriores de importación masiva. El contenido del archivo no se analiza para la comparación de duplicación.

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

REST

Consulta el extremo de la conversations:ingest API para obtener más 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 conversaciones. 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: En todos los ejemplos, se usa 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 de 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 complete cuando el método muestra 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 ejemplos 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 BatchRecognize para 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 de GetOperation para usar una cuota por minuto y por región.

Para una sola llamada de UploadConversation, Customer Experience Insights consume una solicitud de 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.