Konsep dan pemecahan masalah

Halaman ini menjelaskan konfigurasi spesifik yang diperlukan untuk integrasi serta pemecahan masalah umum.

Persyaratan jaringan telepon

Jika jaringan Anda memfilter traffic keluar, jaringan tersebut harus mengizinkan traffic keluar untuk pensinyalan SIP dan streaming media.

Untuk pensinyalan SIP, seluruh rentang IP 74.125.88.128/25 (TCP) melalui port 5672 harus diizinkan. Untuk set aturan firewall yang lebih ketat, Anda dapat membatasi pensinyalan SIP hanya ke satu atau beberapa server SIP GTP yang teregionalisasi:

• Wilayah AS: us.telephony.goog (74.125.88.132)
• Wilayah Uni Eropa: eu.telephony.goog (74.125.88.133)
• Wilayah Asia Pasifik: ap.telephony.goog (74.125.88.134)
• Wilayah Amerika Selatan: sa.telephony.goog (74.125.88.135)

Untuk media RTP, Anda harus mengonfigurasi aturan firewall untuk mengizinkan traffic yang ditujukan ke rentang IP CIDR 74.125.39.0/24. Biasanya, port yang diperlukan untuk media hanya 16384-32767 (TCP+UDP), tetapi rentang port ini dapat diperluas pada masa mendatang.

Vendor atau model SBC yang didukung

Tabel berikut mencantumkan vendor atau model SBC dan versi firmware yang didukung. Petunjuk integrasi mendetail untuk setiap vendor ditautkan dalam versi firmware.

Protokol media dan pensinyalan SBC yang didukung

Header SIP

Saat Anda menyiapkan profil percakapan dan nomor telepon, Anda membuat profil percakapan CCAI dengan sipConfig.createConversationOnTheFly yang ditetapkan ke true. ID percakapan harus dibuat secara dinamis selama SIP INVITE menggunakan nilai header SIP dari Call-Info atau UUI.

Nilai header SIP mengarah ke endpoint Dialogflow dengan menentukan Google Cloud project ID dan conversation ID:

1. Project ID Google Cloud adalah project yang Anda gunakan saat menyiapkan project Google Cloud .
2. ID percakapan harus dibuat secara dinamis oleh SBC. ID percakapan harus sesuai dengan formula ekspresi reguler [a-zA-Z][a-zA-Z0-9_-]* dengan panjang karakter dalam rentang [3,64]. Untuk membuat ID percakapan secara dinamis, pola umum adalah menggunakan nilai Call-ID dalam SIP INVITE dan menambahkan awalan huruf agar sesuai dengan ekspresi reguler seperti yang ditentukan sebelumnya. Misalnya, jika nilai Call-ID adalah 297363723_79131759_799783510, menambahkan awalan "CID-" pada nilai Call-ID akan membuatnya mematuhi ekspresi reguler [a-zA-Z][a-zA-Z0-9_-]*.

Call-Info Header SIP

Sisipkan header SIP kustom bernama Call-Info di SIP INVITE untuk menetapkan ID percakapan secara unik:

Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/$PROJECT_ID/conversations/$CONVERSATION_ID>;purpose=Goog-ContactCenter-Conversation

Contoh:

Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510>;purpose=Goog-ContactCenter-Conversation

UUI Header SIP

Jika penyetelan header SIP kustom Call-Info tidak didukung, Anda dapat mengonfigurasi header SIP UUI (User-to-User) di SIP INVITE untuk meneruskan ID percakapan.

Gunakan data yang sama yang diminta di Call-Info dengan URL yang dienkode dalam hex dan tujuan ditetapkan ke Goog-ContactCenter-Conversation. Berikut adalah contoh header, dengan string hex saat didekode adalah http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510:

User-to-User: 687474703a2f2f6469616c6f67666c6f772e676f6f676c65617069732e636f6d2f763262657461312f70726f6a656374732f6763702d70726f6a6563742d69642d31323334352f636f6e766572736174696f6e732f4349442d3239373336333732335f37393133313735395f373939373833353130;encoding=hex;purpose=Goog-ContactCenter-Conversation

Jika data tambahan perlu diteruskan ke Agen Percakapan dan ditetapkan sebagai parameter sesi, Anda dapat melakukannya dengan meneruskan daftar pasangan nilai kunci yang dipisahkan titik koma dan dienkode hex, diikuti dengan ;encoding=hex;purpose=Goog-Session-Param. Hal ini akan menghasilkan parameter sesi yang dibuat dengan nama uui-headers yang berisi daftar string payload yang didekode.

Misalnya, jika string key1=value1;key2=value2 perlu diteruskan, header UUI berikut akan dikirim, dengan payload adalah nilai berenkode hex dari key1=value1;key2=value2.

User-to-User: 6B6579313D76616C7565313B6B6579323D76616C756532;encoding=hex;purpose=Goog-Session-Param

yang akan menghasilkan parameter sesi berikut.

{
    "uui-headers": ["key1=value1;key2=value2"]
}

Jika SBC Anda mendukung pengiriman beberapa header UUI, Anda dapat mengirimkan setiap string nilai kunci per header UUI dan string tersebut akan tersedia sebagai setiap nilai dalam parameter sesi uui-headers.

Cuplikan berikut mengambil nilai parameter, lalu membagi parameter beberapa kali untuk mengakses nilai yang sesuai untuk variabel key2 dalam string.

$sys.func.GET($sys.func.SPLIT($sys.func.GET($sys.func.SPLIT($session.params.uui-headers,";"),1),"="),1)

Contoh berikut menunjukkan fungsi yang dipanggil dari pemicu di blok kode Playbook, misalnya. @PlaybookStartHandler, yang dipanggil saat memasuki Playbook. Fungsi lain memanggil fungsi ini untuk mendapatkan nilai dari parameter uui-headers.

def _get_fromuui(attribute):
    try:
        uui_headers_src = history.playbook_input.action_parameters['uui-headers']
        # If uui_headers_src is a string, split by ';'
        if isinstance(uui_headers_src, str):
            headers = uui_headers_src.split(';')
        else:
            # If it's a list, join and split
            headers = ';'.join(uui_headers_src).split(';')
        for header in headers:
            header = header.strip()
            if header.lower().startswith(f"{attribute.lower()}="):
                return header[len(attribute) + 1:]
        return ""
    except Exception:
        return ""

Data tambahan dapat dikirim menggunakan header UUI terpisah yang memiliki nilai "tujuan" yang berbeda. Nilai ini ditambahkan ke objek Conversation.telephonyConnectionInfo. Perhatikan bahwa data ini tidak tersedia untuk agen Agen Percakapan (Dialogflow CX) saat runtime.

Meneruskan informasi agen manusia

Jika perlu meneruskan informasi khusus untuk agen manusia, Anda dapat menyetel atribut label media Session Description Protocol (SDP), untuk aliran Real-time Transport Protocol (RTP) agen manusia ke nilai data yang diperlukan. Contoh: none a=label:7382373482 Data ini akan diisi di kolom sip_recording_media_label dan tersedia di topik pubsub New message notification yang berisi transkrip. Cari kolom sip_recording_media_label dalam pesan Message.attributes pubsub.

Mengonfigurasi peran peserta dan urutan aliran media

Secara default, aliran media pertama dikaitkan dengan peran peserta END_USER dan aliran media berikutnya dikaitkan dengan peran peserta HUMAN_AGENT.

Jika Anda memerlukan perilaku yang berbeda (misalnya, dalam sistem panggilan keluar), URL yang diteruskan di header harus memiliki parameter peran yang ditambahkan.

Contoh: none http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510?roles=HUMAN_AGENT,END_USER

URL menentukan bahwa aliran media pertama harus memiliki peran HUMAN_AGENT dan aliran media kedua harus memiliki peran END_USER. Anda dapat menerapkan parameter peran dengan header SIP Call-Info atau UUI.

Menetapkan parameter tambahan pada percakapan tertentu

Untuk menyetel parameter tambahan pada percakapan tertentu, gunakan panggilan RPC MatchIntentRequest. Anda dapat menetapkan query_params.parameters ke pasangan nilai kunci yang diperlukan dan query_input.text ke sesuatu seperti 'Menetapkan parameter'.

Lakukan panggilan API setelah respons 200 OK untuk SIP INVITE awal, yang pada saat itu percakapan telah dibuat. ID sesi untuk MatchIntentRequest adalah ID percakapan yang sama yang diberikan di header Call-Info dalam INVITE.

Menggunakan SIP REFER untuk mentransfer panggilan ke endpoint SIP

Untuk mentransfer panggilan dari agen virtual ke endpoint SIP, gunakan metode SIP REFER. Sertakan payload di kolom Live agent handoff dan tetapkan kolom Telephony transfer call ke nomor yang ditetapkan di kolom SIP REFER Refer-To keluar. Payload Anda akan terlihat mirip dengan contoh kode berikut.

{
    "sip-refer": true
}

Jika data perlu diteruskan dari Agen Percakapan (Dialogflow CX), header UUI dapat digunakan untuk meneruskan string data. Jika ingin melakukan SIP REFER dan meneruskan 2 pasangan nilai kunci, Anda dapat menggunakan payload yang mirip dengan contoh kode berikut.

{
    "sip-refer": true,
    "uui-headers": [
        "key1=value1;key2=value2"
    ]
}

Tindakan ini akan menghasilkan SIP REFER dengan header UUI berikut.

User-to-User: <hex encoded "key1=value1;key2=value2">;encoding=hex;purpose=Goog-Session-Param

Pemecahan masalah

Tim Google mungkin meminta Anda memberikan artefak berikut untuk membantu pemecahan masalah ping OPTIONS SIP dan panggilan uji yang dilakukan:

1. Penangkapan paket jaringan
2. SIP debug trace yang menampilkan header lengkap dan SDP SIP:
   • Nilai Call-ID
   • Nilai Call-Info (jika ada)

Penangkapan paket jaringan

Perekaman paket jaringan akan menampilkan hal berikut:

1. Handshake TCP 3 arah yang lengkap (SYN, SYN-ACK, ACK) antara SBC Anda dan server SIP GTP dikomunikasikan melalui port TCP 5672. Jika koneksi TCP gagal dibuat, kemungkinan masalahnya adalah:

   • Jaringan Anda memblokir traffic keluar.
   • Komunikasi tidak dikirim ke salah satu server SIP GTP yang dilokalkan. Lihat Persyaratan jaringan konektivitas telepon.
   • Komunikasi tidak dikirim melalui port TCP 5672.

2. Handshake koneksi TLS yang lengkap dengan berikut ini:

   • TLS v1.2 atau yang lebih baru yang dimulai oleh SBC Anda.
   • SBC Anda memulai "Client Hello" dan GTP merespons dengan "Server Hello".
   • Proses autentikasi TLS bersama.
     • GTP merespons dengan sertifikat TLS servernya sendiri yang diautentikasi oleh SBC Anda.
     • SBC mengirimkan sertifikat TLS kliennya sendiri yang diautentikasi oleh GTP.
   • Saluran terenkripsi dibuat sebagaimana terbukti dengan "Pesan Handshake Terenkripsi".
   • Bukti "Data Aplikasi" dikirimkan melalui saluran TLS.

   Jika koneksi TLS gagal dibuat, kemungkinan masalahnya adalah:

   • Trunk SIP belum dibuat di sisi GTP.
   • FQDN yang dikonfigurasi SIP trunk tidak cocok dengan FQDN yang ditampilkan di sertifikat TLS (atribut CN atau SAN) dari SBC.
   • Versi TLS tidak didukung, hanya TLS versi 1.2 atau yang lebih baru yang didukung.
   • Rangkaian cipher yang diminta tidak didukung, lihat Konfigurasi TLS SBC.
   • Penyedia sertifikat TLS yang tidak tepercaya, lihat Konfigurasi TLS SBC.

3. SIP debug trace akan menampilkan hal berikut:

   • Header SIP Call-Info pelanggan dimasukkan dalam format ini: none Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/$PROJECT_ID/conversations/$CONVERSATION_ID>;purpose=Goog-ContactCenter-Conversation

     Contoh: none Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510>;purpose=Goog-ContactCenter-Conversation

   • Header SIP menampilkan nomor telepon dalam format E.164 (+16501234567).

   • Header SIP menampilkan alamat IP publik yang digunakan di URI permintaan dan kolom header SIP lainnya (misalnya, To, From, Via). Alamat IP pribadi akan ditolak.

   • Informasi koneksi SIP SDP (c= ... ) ditentukan dengan alamat IP publik. Alamat IP pribadi akan ditolak.

   • Pastikan prioritas media mengirimkan streaming pengguna akhir terlebih dahulu, diikuti dengan streaming media agen manusia kedua karena GTP memperlakukan streaming media pertama sebagai pengguna akhir secara default.

   Jika Anda menerima kode respons error SIP:

   • Kode respons error SIP 400 (misalnya, 488 Not Acceptable Here) kemungkinan menunjukkan bahwa GTP menolak konfigurasi header SIP atau SDP media SIP.
   • Kode respons error SIP 600 (Error Ditolak SIP 603) kemungkinan menunjukkan masalah terkait kuota. Lihat halaman Kuota & batas untuk mengetahui detail tentang cara meminta penambahan kuota.

Memicu tindakan saat pemanggil jarak jauh menutup telepon

BiDi API baru (use_bidi_streaming=True di ConversationProfile) mendukung pemicuan panggilan alat dalam playbook atau panggilan webhook dalam alur saat pemanggil jarak jauh menutup telepon.

Saat pemanggil jarak jauh menutup telepon dan Agen Percakapan (Dialogflow CX) menerima pesan SIP BYE, peristiwa kustom sys.remote-call-disconnected akan dipicu. Jika Anda membuat handler dengan nama peristiwa tertentu ini, Anda dapat menggunakannya untuk memicu panggilan alat dengan playbook atau panggilan webhook dalam alur.