Setelah mendaftar ke Business Message, Anda dapat menerima pesan atas nama agen pengujian. Anda dapat menerima pesan untuk merek yang Anda kelola setelah Anda membuat, memverifikasi, dan meluncurkan agen untuk merek tersebut.
Saat pelanggan mengirim pesan ke agen yang Anda kelola, Business Messages mengirimkan payload JSON ke webhook Anda yang berisi berbagai ID, konten pesan, dan informasi lokasi.
Gunakan halaman log Business Developer Communications Developer untuk men-debug masalah pengiriman pesan.
Menangani pesan masuk
Cara agen Anda menangani dan merespons pesan dari pengguna sangat bergantung pada logika bisnis Anda. Namun, secara umum, langkah-langkah untuk merespons pesan pengguna konsisten.
Menyatakan penerimaan pesan
Untuk mengonfirmasi pesan yang diterima oleh webhook Anda, tampilkan respons HTTP yang valid untuk pesan yang dikirim ke webhook Anda.
Jika pesan gagal dikirim karena waktu tunggu pengiriman, jangkauan webhook, pengalihan, atau izin, Google akan menyimpan dan meneruskan pesan, dengan beberapa percobaan ulang, selama 7 hari atau hingga webhook Anda berhasil menerima pesan.
Memverifikasi bahwa pesan berasal dari Google
Anda harus memverifikasi bahwa Google mengirim pesan sebelum memproses konten pesan.
Untuk memverifikasi bahwa Google telah mengirim pesan yang Anda terima,
- Uraikan header
X-Goog-Signaturepesan. Ini adalah salinan payload isi pesan berenkode base64. Dengan menggunakan token klien (yang ditampilkan saat Anda mengonfigurasi webhook) sebagai kunci, buat HMAC SHA512 byte payload pesan dan enkripsikan hasilnya ke base64.
Bandingkan hash
X-Goog-Signaturedengan hash yang Anda buat.- Jika hash tersebut cocok, Anda telah mengonfirmasi bahwa Google mengirim pesan.
- Jika hash-nya tidak cocok, periksa proses hashing pada pesan yang diketahui dengan baik. Jika proses hashing Anda berfungsi dengan benar dan Anda menerima pesan yang diyakini menipu Anda, hubungi kami (Anda harus login dengan akun Google Message Bisnis).
Lihat contoh verifikasi pesan dalam repositori GitHub untuk Echo Bot di Java, Node.js, dan Python.
Identifikasi lokal
Pengguna berkomunikasi dari banyak lokasi dan dalam banyak bahasa. Business Messages mewakili preferensi bahasa pengguna dengan kolom resolvedLocale dan userDeviceLocale, yang didasarkan pada setelan lokal perangkat mereka.
Lihat Pelokalan dan
lokal.
Jika memungkinkan, arahkan pesan dan tulis respons berdasarkan preferensi bahasa pengguna.
Merutekan pesan berdasarkan konteksnya
Konteks pesan menginformasikan jenis informasi yang mungkin dicari pengguna.
Misalnya, jika mengirim pesan dengan nilai
placeId, mereka akan mengirim pesan ke lokasi tertentu (yang diidentifikasi oleh placeId) dan
kemungkinan untuk mengajukan pertanyaan khusus lokasi. Demikian pula, jika pesan memiliki nilai nearPlaceId, yang mengidentifikasi lokasi di dekat pengguna, pengguna tersebut mungkin ingin mengetahui informasi khusus lokasi, tetapi agen harus mengonfirmasi lokasi yang ingin diajak chat oleh pengguna sebelum memulai percakapan.
Dengan informasi konteks pesan, arahkan pesan ke lokasi yang paling sesuai untuk merespons:
- Jika pesan berada dalam percakapan baru dan merupakan pertanyaan umum, Anda dapat menjawabnya dengan otomatisasi.
- Jika otomatisasi tidak dapat menangani pertanyaan ini, arahkan ke agen langsung.
- Jika lokal pesan tidak cocok dengan lokal default agen Anda, arahkan pesan ke agen langsung yang dapat mendukung lokal tersebut.
- Jika pertanyaan berhubungan dengan lokasi tertentu, arahkan pertanyaan kepada seseorang yang memiliki informasi tentang lokasi tersebut.
- Jika pesan berada dalam percakapan yang sedang berlangsung, arahkan pesan tersebut ke agen langsung yang berpartisipasi dalam percakapan.
Identifikasi jenis pesan yang dikirim pengguna
Pengguna dapat mengirim tiga jenis pesan:
- Pesan teks adalah respons bentuk bebas.
- Pesan Image mencakup URL yang ditandatangani untuk gambar yang diupload pengguna.
- Pesan Saran mencakup data postback dan teks tindakan yang disarankan atau balasan yang disarankan yang diketuk pengguna.
Memproses konten pesan
Jika agen Anda menggunakan otomatisasi, konten pesan pengguna harus memandu logika agen Anda dan respons berikutnya dalam percakapan.
Cara termudah untuk mengidentifikasi intent pengguna adalah dengan data postback dari balasan yang disarankan atau tindakan yang disarankan. Terlepas dari teks yang terkait dengan saran, data postback dapat dibaca mesin.
Jika pengguna mengirim SMS, agen Anda mungkin mengurai respons untuk kata kunci yang didukung atau menggunakan pemahaman bahasa yang alami (seperti dengan integrasi Dialogflow untuk memproses pesan pengguna dan mengidentifikasi jalur ke depan.
Jika tidak tahu cara merespons pesan pengguna, agen Anda akan merespons dengan status error dan mencoba melanjutkan percakapan dengan meminta informasi tambahan kepada pengguna, dengan meminta input dengan cara yang berbeda, atau dengan menyerahkan percakapan kepada agen langsung.
Merespons pengguna
Setelah mengidentifikasi respons yang tepat, baik melalui otomatisasi atau agen langsung, agen akan mengirim pesan dan melanjutkan percakapan dengan pengguna.
Saat menulis respons, pertimbangkan lokalitas pengguna. Anda juga dapat menyesuaikan respons dengan mengambil nilai dari objek userInfo di setiap pesan yang Anda terima.
Jenis pesan
Kode berikut menunjukkan cara agen Anda menerima pesan.
Untuk informasi pemformatan dan nilai, lihat
UserMessage.
Teks
Cara paling umum bagi pengguna untuk merespons adalah dengan teks biasa. Pesan teks memiliki format berikut.
{
"agent": "brands/BRAND_ID/agents/AGENT_ID",
"conversationId": "CONVERSATION_ID",
"customAgentId": "CUSTOM_AGENT_ID",
"requestId": "REQUEST_ID",
"message": {
"messageId": "MESSAGE_ID",
"name": "conversations/CONVERSATION_ID/messages/MESSAGE_ID",
"text": "MESSAGE_TEXT",
"createTime": "MESSAGE_CREATE_TIME",
},
"dialogflowResponse": {
"autoResponded": "BOOLEAN",
"faqResponse": {
"userQuestion": "USER_QUESTION",
"answers": [{
"faqQuestion": "FAQ_QUESTION",
"faqAnswer": "FAQ_ANSWER",
"matchConfidenceLevel": "CONFIDENCE_LEVEL",
"matchConfidence": "CONFIDENCE_NUMERIC",
}],
},
},
"context": {
"entryPoint": "CONVERSATION_ENTRYPOINT",
"placeId": "LOCATION_PLACE_ID",
"resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
"userInfo": {
"displayName": "USER_NAME",
"userDeviceLocale": "USER_LOCALE",
},
},
"sendTime": "SEND_TIME",
}
Untuk opsi pemformatan dan nilai, lihat
Message.
Image
Selain mengirim SMS, pengguna dapat mengirim gambar ke agen Anda sebagai pesan.
Business Messages menyimpan gambar yang dibagikan, selama 7 hari, di URL bertanda tangan dan menyertakan URL tersebut di kolom text payload pesan.
Jika agen Anda menyertakan otomatisasi, pastikan otomatisasi mengetahui cara merespons jika pengguna membagikan gambar. Untuk agen langsung, pastikan bahwa gambar diteruskan atau URL dalam pesan dapat diklik.
...
"message": {
"text": "https://storage.googleapis.com/business-messages-us/936640919331/jzsu6cdguNGsBhmGJGuLs1DS?x-goog-algorithm\u003dGOOG4-RSA-SHA256\u0026x-goog-credential\u003duranium%40rcs-uranium.iam.gserviceaccount.com%2F20190826%2Fauto%2Fstorage%2Fgoog4_request\u0026x-goog-date\u003d20190826T201038Z\u0026x-goog-expires\u003d604800\u0026x-goog-signedheaders\u003dhost\u0026x-goog-signature\u003d89dbf7a74d21ab42ad25be071b37840a544a43d68e67270382054e1442d375b0b53d15496dbba12896b9d88a6501cac03b5cfca45d789da3e0cae75b050a89d8f54c1ffb27e467bd6ba1d146b7d42e30504c295c5c372a46e44728f554ba74b7b99bd9c6d3ed45f18588ed1b04522af1a47330cff73a711a6a8c65bb15e3289f480486f6695127e1014727cac949e284a7f74afd8220840159c589d48dddef1cc97b248dfc34802570448242eac4d7190b1b10a008404a330b4ff6f9656fa84e87f9a18ab59dc9b91e54ad11ffdc0ad1dc9d1ccc7855c0d263d93fce6f999971ec79879f922b582cf3bb196a1fedc3eefa226bb412e49af7dfd91cc072608e98"
}
...
Untuk opsi pemformatan dan nilai, lihat
Message.
Saran
Balasan yang disarankan dan tindakan yang disarankan memungkinkan pengguna merespons atau melakukan tindakan dengan sekali ketuk. Saat pengguna mengetuk saran, agen akan menerima payload dengan teks saran dan data postback.
Pesan saran memiliki format berikut.
{
"agent": "brands/BRAND_ID/agents/AGENT_ID",
"conversationId": "CONVERSATION_ID",
"customAgentId": "CUSTOM_AGENT_ID",
"requestId": "REQUEST_ID",
"suggestionResponse": {
"message": "conversations/CONVERSATION_ID/messages/MESSAGE_ID",
"postbackData": "POSTBACK_DATA",
"createTime": "RESPONSE_CREATE_TIME",
"text": "SUGGESTION_TEXT",
"suggestionType": "SUGGESTION_TYPE",
}
"context": {
"entryPoint": "CONVERSATION_ENTRYPOINT",
"placeId": "LOCATION_PLACE_ID",
"resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
"userInfo": {
"displayName": "USER_NAME",
"userDeviceLocale": "USER_LOCALE",
},
},
"sendTime": "SEND_TIME",
}
Untuk opsi pemformatan dan nilai, lihat
SuggestionResponse.
Permintaan autentikasi
Saran permintaan Authentication memungkinkan pengguna login dengan penyedia OAuth untuk memberikan detail identitas kepada agen atau mengizinkan agen melakukan tindakan atas nama pengguna. Lihat Mengautentikasi dengan OAuth.
Jika pengguna berhasil login dengan penyedia OAuth yang ditetapkan, agen akan menerima payload dengan kode otorisasi. Jika pengguna tidak berhasil login, agen akan menerima payload dengan detail error.
Pesan permintaan autentikasi memiliki format berikut.
{
"agent": "brands/BRAND_ID/agents/AGENT_ID",
"conversationId": "CONVERSATION_ID",
"customAgentId": "CUSTOM_AGENT_ID",
"requestId": "REQUEST_ID",
"authenticationResponse": {
"code": "AUTHORIZATION_CODE",
"redirect_uri": "REDIRECT_URI",
"errorDetails": {
"error": "ERROR",
"errorDescription": "ERROR_DESCRIPTION",
},
}
"context": {
"entryPoint": "CONVERSATION_ENTRYPOINT",
"placeId": "LOCATION_PLACE_ID",
"resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
"userInfo": {
"displayName": "USER_NAME",
"userDeviceLocale": "USER_LOCALE",
},
},
"sendTime": "SEND_TIME",
}
Untuk opsi pemformatan dan nilai, lihat
AuthenticationResponse.
Konteks pesan
Setiap pesan berisi informasi konteks tentang asal pesan tersebut.
...
"context": {
"customContext": "CUSTOM_CONTEXT",
"entryPoint": "CONVERSATION_ENTRYPOINT",
"placeId": "LOCATION_PLACE_ID",
"nearPlaceId": "NEARBY_LOCATION_PLACE_ID",
"deflectedPhoneNumber": "DEFLECTED_PHONE_NUMBER",
"resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
"userInfo": {
"displayName": "USER_NAME",
"userDeviceLocale": "USER_LOCALE",
},
"widget": {
"url": "WEBSITE_URL",
"widgetContext": "WIDGET_CONTEXT",
},
},
...
| Kolom | Deskripsi |
|---|---|
customContext |
Data konteks yang ditentukan oleh partner. |
entryPoint |
Platform pesan yang digunakan untuk memulai percakapan, seperti yang ditentukan oleh EntryPoint. |
placeId |
ID unik dari database Google Places untuk lokasi yang dikirimi pesan oleh pengguna. Ini hanya muncul dalam pesan dari titik entri khusus lokasi. |
nearPlaceId |
ID unik dari database Google Places untuk lokasi
pertama dalam Paket Lokal. Konfirmasikan lokasi tempat pengguna ingin melakukan chat
saat Anda menerima nilai nearPlaceId. |
deflectedPhoneNumber |
Nomor telepon yang dideteksi oleh Business Messages mencegah pengguna menelepon saat percakapan dimulai. |
resolvedLocale |
Kecocokan terbaik yang dihitung dari lokal pengguna (dilaporkan dalam Nilai lokal adalah tag bahasa IETF BCP 47 yang terbentuk dengan baik. |
userInfo.displayName |
Nama pengguna yang mengirim pesan. Jika pengguna memilih tidak membagikan identitas, kolom ini akan kosong. |
userInfo.userDeviceLocale |
Lokalitas pengguna, yang dilaporkan oleh perangkat mereka, sebagai tag bahasa IETF BCP 47 yang terbentuk dengan baik. |
widget.url |
URL situs tempat platform percakapan diluncurkan. |
widget.widgetContext |
Nilai atribut data-bm-widget-context widget yang digunakan untuk memulai percakapan. |
Histori percakapan
Google tidak menyediakan histori percakapan. Kelola percakapan historis Anda sendiri, dengan mematuhi kebijakan privasi dan praktik terbaik Anda, sehingga Anda dapat mengirimkan respons yang tepat untuk pesan berikutnya dari pengguna.