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 mengimpor semua file secara massal 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 [setelan](/contact-center/insights/docs/reference/rest/v1alpha1/Settings#analysisconfig) project
IngestConversations	Semua file dalam bucket	✔	✔	✔	Hanya dengan aturan analisis

Prasyarat

Aktifkan Cloud Storage, Speech-to-Text, Cloud Data Loss Prevention, dan Customer Experience Insights API di Google Cloud project yang Anda gunakan untuk Dialogflow.
Simpan data percakapan Anda (file audio dan transkrip dua saluran) di bucket Cloud Storage menggunakan kelas penyimpanan standar.
1. Ikuti petunjuk Mulai cepat Cloud Storage untuk membuat bucket.
2. Tetapkan lokasi bucket ke lokasi yang paling dekat 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>
Beri agen layanan Speech-to-Text dan Customer Experience Insights akses ke objek di bucket Cloud Storage Anda. Lihat halaman pemecahan masalah ini untuk mendapatkan bantuan terkait akun layanan.
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 URI Cloud Storage 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 diberikan dalam file berformat JSON, dengan setiap file berisi data untuk satu percakapan. File teks berformat JSON Anda mencakup format data percakapan.

Transkrip suara dapat diberikan 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 untuk mentranskripsikan audio. CX Insights mengonfigurasi setelan transkripsi Speech-to-Text dengan resource Recognizer. Anda dapat membuat pengenal kustom dalam permintaan, atau jika Anda tidak memberikan pengenal baik di Setelan maupun dalam permintaan, CX Insights akan membuat ccai-insights-recognizer default di project Anda.

Pengenal CX Insights mentranskripsikan ucapan dalam 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.

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

Gunakan konfigurasi transkripsi Speech-to-Text kustom.
Menganalisis percakapan yang (opsional) disamarkan.

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

Penyuntingan

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

Konfigurasikan setelan project

Izin yang diperlukan untuk langkah ini

Untuk melakukan tugas ini, Anda harus memiliki izin berikut:

contactcenterinsights.settings.update

Penyensoran 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 menggantikan setelan project. analysis_percentage yang dikonfigurasi dalam aturan analisis menggantikan 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

Mengimpor metadata dalam satu file atau sebagai impor massal.

Sertakan metadata langsung dalam permintaan

Khusus untuk impor file tunggal, 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

Berikan file metadata percakapan sebagai file berformat JSON. Untuk impor massal, berikan bucket yang ditentukan di kolom gcs_source.metadata_bucket_uri pada 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. API ini 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

Izin yang diperlukan untuk langkah ini

Untuk melakukan tugas ini, Anda harus memiliki izin berikut:

contactcenterinsights.conversations.upload

UploadConversation API membuat operasi yang berjalan lama yang mentranskripsikan dan secara opsional menyamarkan percakapan Anda. File audio akan ditranskripsikan jika percakapan hanya berisi audio_uri dalam 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

Izin yang diperlukan untuk langkah ini

Untuk melakukan tugas ini, Anda harus memiliki izin berikut:

contactcenterinsights.conversations.create

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: ditetapkan 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:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

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/us-central1/conversations:ingest"

PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

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

$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

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 kodenya.

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.

Menggunakan API untuk mengimpor percakapan Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Prasyarat

Data percakapan

Transkrip

Audio

Penyuntingan

Konfigurasikan setelan project

Izin yang diperlukan untuk langkah ini

Metadata

Sertakan metadata langsung dalam permintaan

Mengimpor metadata dari file Cloud Storage

Mengimpor satu file audio

Izin yang diperlukan untuk langkah ini

Impor massal

Izin yang diperlukan untuk langkah ini

REST

curl (Linux, macOS, atau Cloud Shell)

PowerShell (Windows)

Polling operasi

Kuota Speech-to-Text

Menggunakan API untuk mengimpor percakapan