Konsep dan pemecahan masalah

Halaman ini menjelaskan konfigurasi spesifik yang diperlukan untuk integrasi serta pemecahan masalah untuk 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 kumpulan aturan firewall yang lebih ketat, Anda dapat membatasi pensinyalan SIP hanya ke satu atau beberapa server SIP GTP regional:

• Region AS: us.telephony.goog (74.125.88.132)
• Region Uni Eropa: eu.telephony.goog (74.125.88.133)
• Region Asia Pasifik: ap.telephony.goog (74.125.88.134)
• Region 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). Namun, rentang port ini dapat diperluas di 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 di versi firmware.

Vendor dan model	Versi firmware
AudioCodes VE SBC	v7.60A.100.022 (SIPREC, SIP)
Avaya Session Border Controller for Enterprise	v10.2.1.1-104-25336 (SIPREC, SIP)
Oracle E-SBC Acme Packet 4600	SCZ9.3.0 GA (Build 46) (SIPREC, SIP)
Ribbon Swe Core SBC	v12.01.07R000 (SIPREC, SIP)
Cisco Unified Border Element (CUBE)	v17.15.4 (SIPREC, SIP)

Catatan: Tabel ini mewakili versi firmware minimum yang didukung dan telah disertifikasi untuk berfungsi dengan integrasi SIP. Versi firmware baru yang merupakan bagian dari rangkaian patch firmware utama yang sama juga telah disertifikasi.

Protokol pensinyalan dan media SBC yang didukung

Protokol Pensinyalan	SIP melalui TLS
Media	SRTP
Enkripsi Media	SDES
Cipher Suite Media yang Didukung	AES_CM_128_HMAC_SHA1_80, AEAD_AES_256_GCM
Codec Media yang Didukung	G.711 µ-law (PCMU), G.711 A-law (PCMA), Opus

Header SIP

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

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

1. Google Cloud Project ID adalah project yang Anda gunakan saat menyiapkan Google Cloud project.
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 umumnya adalah menggunakan nilai Call-ID di SIP INVITE dan menambahkan awalan dengan huruf agar sesuai dengan ekspresi reguler seperti yang ditentukan sebelumnya. Misalnya, jika nilai Call-ID adalah 297363723_79131759_799783510, menambahkan awalan nilai Call-ID dengan "CID-" akan membuatnya sesuai dengan ekspresi reguler [a-zA-Z][a-zA-Z0-9_-]*.

Header SIP Call-Info

Sisipkan header SIP kustom yang disebut 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

Header SIP UUI

Jika setelan 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 yang 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 dan ditetapkan sebagai parameter sesi, Anda dapat melakukannya dengan meneruskan daftar pasangan nilai kunci yang dipisahkan titik koma yang dienkode hex, diikuti dengan ;encoding=hex;purpose=Goog-Session-Param. Tindakan 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 yang dienkode hex dari key1=value1;key2=value2.

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

yang akan menghasilkan parameter sesi berikut yang dibuat.

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

Jika SBC Anda mendukung pengiriman beberapa header UUI, Anda dapat mengirim string nilai kunci individual per header UUI dan string tersebut akan tersedia sebagai nilai individual 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 "purpose" yang berbeda. Nilai ini ditambahkan ke Conversation.telephonyConnectionInfo objek. Perhatikan bahwa data ini tidak tersedia untuk agen Dialogflow CX saat runtime.

Header x-SIP

Header SIP yang dimulai dengan x- dapat diteruskan ke agen dan ditetapkan sebagai parameter sesi. Header SIP tersedia dalam parameter sesi x-headers. Awalan x- dihapus dari nama header dalam parameter sesi.

Misalnya, jika SIP INVITE berisi header berikut:

x-billing-id: 12345

Parameter sesi x-headers akan berisi:

{
    "x-headers": {
        "billing-id": "12345"
    }
}

Untuk mengakses nilai:

$session.params.x-headers.billing-id

Meneruskan informasi agen manusia

Jika perlu meneruskan informasi khusus untuk agen manusia, Anda dapat menetapkan atribut label media Session Description Protocol (SDP), untuk agen manusia, streaming Real-time Transport Protocol (RTP) 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 sip_recording_media_label kolom di pesan Message.attributes pubsub.

Peringatan: Karena alasan kepatuhan, jangan teruskan data pengguna PII apa pun di header SIP. Header SIP hanya boleh digunakan untuk meneruskan pasangan nilai kunci non-PII.

Mengonfigurasi peran peserta dan urutan streaming media

Secara default, streaming media pertama dikaitkan dengan peran peserta END_USER dan streaming 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 streaming media pertama harus memiliki peran HUMAN_AGENT dan streaming 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 menetapkan parameter tambahan pada percakapan tertentu, gunakan panggilan MatchIntentRequest RPC. Anda dapat menetapkan query_params.parameters ke pasangan nilai kunci yang diperlukan dan query_input.text ke sesuatu seperti 'Setting parameters'.

Lakukan panggilan API setelah respons 200 OK untuk SIP INVITE awal, yang menunjukkan bahwa percakapan telah dibuat. ID sesi untuk MatchIntentRequest adalah ID percakapan yang sama yang diberikan di header Call-Info di 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 Refer-To SIP REFER keluar. Payload Live agent handoff Anda akan terlihat mirip dengan contoh kode berikut.

{
    "sip-refer": true
}

Jika data perlu diteruskan dari Dialogflow CX, header UUI dan header x dapat digunakan untuk meneruskan string data. Jika Anda ingin melakukan SIP REFER dan meneruskan 2 pasangan nilai kunci di header UUI dan 2 header x, Anda dapat menggunakan payload Live agent handoff yang mirip dengan contoh kode berikut.

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

Tindakan ini akan menghasilkan SIP REFER dengan header UUI dan x berikut.

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

Menggunakan SIP INVITE untuk melakukan konferensi panggilan dengan endpoint SIP lain

Untuk melakukan konferensi panggilan dari pelanggan akhir ke agen manusia yang dapat diakses menggunakan endpoint SIP, gunakan metode SIP INVITE. Tindakan ini akan mempertahankan Google di jalur media dan memungkinkan penggunaan fitur Agent Assist. Tetapkan kolom Telephony transfer call ke nomor yang ditetapkan di kolom To SIP INVITE keluar.

Jika data perlu diteruskan dari Dialogflow CX, header UUI dan header x dapat digunakan untuk meneruskan string data. Jika Anda ingin melakukan SIP INVITE dan meneruskan 2 pasangan nilai kunci di header UUI dan 2 header x, Anda dapat menggunakan payload Live agent handoff yang mirip dengan contoh kode berikut.

{
    "uui-headers": [
        "key1=value1;key2=value2"
    ],
    "x-headers": {
        "header1": "value1",
        "header2": "value2"
    }
}

Tindakan ini akan menghasilkan SIP INVITE dengan header UUI dan x berikut.

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

Meneruskan data dalam SIP BYE

Membuka End Session akan memicu SIP BYE. Jika Anda ingin meneruskan data dari Dialogflow CX, header UUI atau header x dapat digunakan untuk meneruskan string data. Anda akan merutekan panggilan ke halaman yang menentukan payload Live agent handoff yang mirip dengan contoh kode berikut sebelum bertransisi ke End Session.

{
    "uui-headers": [
        "key1=value1;key2=value2"
    ],
    "x-headers": {
        "header1": "value1",
        "header2": "value2"
    }
}

Tindakan ini akan menghasilkan SIP BYE dengan header UUI dan x berikut.

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

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 Dialogflow CX menerima pesan SIP BYE, peristiwa kustom sys.remote-call-disconnected akan dipicu. Jika membuat pengendali dengan nama peristiwa tertentu ini, Anda dapat menggunakannya untuk memicu panggilan alat dengan playbook atau panggilan webhook dalam alur.

Hanya mengizinkan panggilan dari SBC

Untuk menolak panggilan dari PSTN dan hanya menghubungkan panggilan yang berasal dari SBC Anda, perbarui PhoneNumber objek untuk menentukan pesan allowedSipTrunks. Jika integrasi menggunakan trunk SIP, Anda dapat menentukan daftar ID trunk SIP tertentu. Jika pesan dibuat dengan daftar kosong, trunk SIP apa pun akan diizinkan. Jika interkoneksi pribadi dibuat, berikan ID operator yang disediakan oleh tim Telepon Google.

Pemecahan masalah

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

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

Rekaman paket jaringan

Rekaman paket jaringan harus menampilkan hal berikut:

1. Handshake TCP 3 arah lengkap (SYN, SYN-ACK, ACK) antara SBC Anda ke server SIP GTP yang 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 regional. Lihat Persyaratan jaringan konektivitas telepon.
   • Komunikasi tidak dikirim melalui port TCP 5672.

2. Handshake koneksi TLS lengkap dengan hal berikut:

   • 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 seperti yang ditunjukkan oleh "Encrypted Handshake Message".
   • Bukti "Application Data" yang dikirim melalui saluran TLS.

   Jika koneksi TLS gagal dibuat, kemungkinan masalahnya adalah:

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

3. SIP debug trace harus menampilkan hal berikut:

   • Header SIP Call-Info pelanggan disisipkan 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 ([phone]).

   • 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 mengirim streaming pengguna akhir terlebih dahulu, diikuti oleh 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 header SIP atau konfigurasi SDP media SIP.
   • Kode respons error SIP 600 (Error SIP 603 Declined) kemungkinan menunjukkan masalah terkait kuota. Lihat halaman Kuota & batas untuk mengetahui detail tentang cara meminta peningkatan.