Menggunakan API untuk mengimpor percakapan

Pelajari cara mengimpor file audio dan transkrip beserta metadatanya menggunakan API. Anda dapat mengimpor satu file menggunakan UploadConversation API, atau Anda dapat mengimpor massal semua file dari bucket Cloud Storage menggunakan IngestConversations API.

Dua perintah permintaan UploadConversation dan IngestConversations mendukung fungsi berikut:

Perintah permintaan Jumlah file Speech-to-Text Penyuntingan Penyerapan metadata Analisis otomatis
UploadConversation 1 ✔ ✔ ✔ Dengan aturan analisis atau persentase analisis percakapan upload di project [setelan](/contact-center/insights/docs/reference/rest/v1alpha1/Settings#analysisconfig)
IngestConversations Semua file dalam bucket ✔ ✔ ✔ Hanya dengan aturan analisis

Prasyarat

  1. Aktifkan Cloud Storage, Speech-to-Text, Cloud Data Loss Prevention, dan Customer Experience Insights API di Google Cloud project yang Anda gunakan untuk Dialogflow.
  2. Simpan data percakapan Anda (file audio dan transkrip dua saluran) di bucket Cloud Storage menggunakan class penyimpanan standar.
    1. Ikuti petunjuk mulai cepat Cloud Storage untuk membuat bucket.
    2. Tetapkan lokasi bucket ke lokasi terdekat dengan lokasi Anda.
    3. Perhatikan informasi berikut yang Anda perlukan saat memberikan data percakapan:
      • Nama bucket
      • ID Lokasi, format: us-west1
      • Jalur objek, format: gs://<bucket>/<object>
  3. Berikan akses agen layanan Speech-to-Text dan Customer Experience Insights ke objek di bucket Cloud Storage Anda. Lihat halaman pemecahan masalah ini untuk mendapatkan bantuan terkait akun layanan.

  4. Jika Anda memilih untuk mengimpor metadata percakapan, pastikan file metadata berada di bucketnya sendiri dan nama file metadata cocok dengan nama file percakapan yang sesuai.

    Misalnya, percakapan dengan Cloud Storage URI gs://transcript-bucket-name/conversation.mp3, harus memiliki file metadata yang sesuai seperti gs://metadata-bucket-name/conversation.json.

Data percakapan

Data percakapan terdiri dari transkrip suara atau chat dan audio.

Transkrip

Transkrip chat harus disediakan dalam file berformat JSON, dengan setiap file berisi data untuk satu percakapan. File teks berformat JSON Anda menyertakan format data data percakapan.

Transkrip suara dapat disediakan dalam format data percakapan atau sebagai hasil pengenalan ucapan yang ditampilkan dari transkripsi Speech-to-Text API. Responsnya sama untuk pengenalan sinkron dan asinkron di semua versi Speech-to-Text API.

Audio

Customer Experience Insights menggunakan pengenalan batch Cloud Speech-to-Text batch recognition untuk mentranskripsikan audio. CX Insights mengonfigurasi setelan transkripsi Speech-to-Text dengan resource Recognizer. Anda dapat membuat recognizer kustom dalam permintaan, atau jika Anda tidak memberikan recognizer di Setelan atau dalam permintaan, CX Insights akan membuat ccai-insights-recognizer default di project Anda.

Recognizer CX Insights mentranskripsikan ucapan bahasa Inggris menggunakan model telepon, dan bahasa defaultnya adalah en-US. Untuk mengetahui daftar lengkap dukungan Speech-to-Text per region, bahasa, model, dan fitur pengenalan, lihat dokumen dukungan bahasa Speech-to-Text language support docs.

Sebelum impor audio pertama Anda ke CX Insights, nilai apakah Anda ingin:

  • Menggunakan konfigurasi transkripsi Speech-to-Text kustom.
  • Menganalisis percakapan yang (opsional) disunting.

Anda dapat mengonfigurasi tindakan ini agar berjalan secara default di setiap UploadConversation atau IngestConversation permintaan dengan menetapkan kolom yang tepat di resource Setelan project. Setelan ucapan dan penyuntingan juga dapat diganti per permintaan. Jika Anda tidak menentukan setelan ucapan apa pun, CX Insights akan menggunakan setelan ucapan default dan tidak akan menyunting transkrip.

Penyuntingan

Cloud Data Loss Prevention tidak menyunting transkrip kecuali jika Anda secara eksplisit memberikan konfigurasi penyuntingan di Setelan project, UploadConversationRequest, atau di IngestConversationsRequest. Cloud Data Loss Prevention mendukung template inspeksi dan template de-identifikasi untuk penyuntingan.

Konfigurasikan setelan project

Penyuntingan dan ucapan dapat dikonfigurasi untuk permintaan UploadConversation dan IngestConversations dengan menetapkan parameter setelan project yang sesuai. Konfigurasi ini juga dapat ditetapkan satu per satu per permintaan, yang akan mengganti setelan project. analysis_percentage yang dikonfigurasi dalam aturan analisis akan mengganti upload_conversation_analysis_percentage yang dikonfigurasi melalui setelan project.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

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"

Metadata

Impor metadata dalam satu file atau sebagai impor massal.

Menyertakan metadata langsung dalam permintaan

Hanya untuk impor satu file, metadata kualitas Anda dapat disertakan langsung dalam perintah curl untuk 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"}}}
          }'

Mengimpor metadata dari file Cloud Storage

Sediakan file metadata percakapan sebagai file berformat JSON. Untuk impor massal, berikan bucket yang ditentukan di kolom gcs_source.metadata_bucket_uri dari IngestConversationsRequest. Untuk impor tunggal, berikan jalur objek di kolom data_source.metadata_uri dari UploadConversationRequest.

CX Insights mengisi metadata kualitas percakapan yang ditemukan dalam file, tetapi Anda juga dapat membuat metadata kustom.

Misalnya, untuk menentukan ID percakapan kustom untuk setiap percakapan dalam set data Anda, tentukan metadata kustom pada objek percakapan dalam Cloud Storage. Tetapkan kunci ke ccai_insights_conversation_id. Nilainya adalah ID percakapan kustom Anda. ID percakapan kustom juga dapat diberikan dalam file metadata.

Jika Anda memberikan metadata kustom di kolom custom_metadata_keys dari IngestConversationsRequest, CX Insights akan menyimpan metadata kustom tersebut di label percakapan. CX Insights mendukung hingga 100 label.

Lihat contoh berikut dari file metadata yang valid yang berisi resource Conversation.quality_metadata, serta ID percakapan kustom dan waktu mulai percakapan:

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

Mengimpor satu file audio

API UploadConversation membuat operasi yang berjalan lama yang mentranskripsikan dan secara opsional menyunting percakapan Anda. File audio akan ditranskripsikan jika percakapan hanya berisi audio_uri di DataSource. Jika tidak, transcript_uri yang diberikan akan dibaca dan digunakan.

Meminta isi JSON:

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

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

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"

Impor massal

REST

Lihat endpoint API conversations:ingest untuk mengetahui detail selengkapnya.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: project ID Google Cloud Platform Anda.
  • GCS_BUCKET_URI: Cloud Storage URI yang mengarah ke bucket yang berisi transkrip percakapan. Dapat berisi awalan. Misalnya gs://BUCKET_NAME atau gs://BUCKET_NAME/PREFIX. Karakter pengganti tidak didukung.
  • MEDIUM: tetapkan ke PHONE_CALL atau CHAT, bergantung pada jenis data. Jika tidak ditentukan, nilai defaultnya adalah PHONE_CALL.
  • AGENT_ID: Opsional. ID Agen untuk seluruh bucket.

Metode HTTP dan URL: 

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

Meminta isi JSON: 

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:


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

Polling operasi

Permintaan UploadConversation dan IngestConversation menampilkan operasi yang berjalan lama. Metode yang berjalan lama bersifat asinkron, dan operasi mungkin belum selesai saat metode menampilkan respons. Anda dapat melakukan polling operasi untuk memeriksa statusnya. Lihat halaman operasi yang berjalan lama untuk mengetahui detail dan contoh kode.

Kuota Speech-to-Text

Customer Experience Insights menggunakan dua Speech-to-Text API yang berbeda: BatchRecognize dan GetOperation. Customer Experience Insights membuat permintaan BatchRecognize untuk memulai transkripsi Speech-to-Text dan permintaan GetOperation untuk memantau apakah transkripsi telah selesai atau belum. Untuk memulai operasi BatchRecognize, permintaan BatchRecognize dibuat untuk menggunakan kuota per menit per region. Untuk memantau operasi, permintaan GetOperation dibuat untuk menggunakan kuota per menit per region.

Untuk satu panggilan UploadConversation, Customer Experience Insights menggunakan satu BatchRecognize, tetapi mungkin lebih banyak permintaan GetOperation, bergantung pada durasi tugas. Untuk impor massal, Customer Experience Insights menggunakan 100 permintaan dari setiap jenis.