Menerima pesan

Setelah Anda mendaftar ke Business Message, Anda dapat menerima pesan atas nama agen pengujian. Anda dapat menerima pesan untuk merek yang Anda kelola setelah buat, verifikasi, dan luncurkan penting untuk brand tersebut.

Saat pelanggan mengirim pesan kepada agen yang Anda kelola, Business Messages mengirimkan payload JSON ke webhook Anda yang berisi berbagai ID, isi pesan, dan informasi lokasi.

Menggunakan Log Konsol Developer Business Communications halaman untuk melakukan debug pada masalah pengiriman pesan.

Menangani pesan masuk

Cara agen Anda menangani dan merespons pesan dari pengguna sangat bergantung pada pada logika bisnis Anda. Secara umum, bagaimanapun, langkah-langkah untuk menanggapi pertanyaan pengguna pesan yang konsisten.

Catatan: Jika ada kolom yang hilang dari payload pesan, agen Anda harus tetap memproses pesan sebaik mungkin.

Mengakui pesan

Untuk mengonfirmasi pesan yang diterima oleh webhook Anda, tampilkan respons HTTP yang valid ke pesan yang dikirim ke webhook Anda.

Jika pesan gagal dikirim karena waktu tunggu pengiriman habis, keterjangkauan webhook, pengalihan, atau masalah izin, Google menyimpan dan meneruskan pesan, dengan beberapa kali percobaan ulang, selama 7 hari atau hingga webhook Anda berhasil menerima untuk membuat pesan email baru.

Verifikasi bahwa pesan ini dari Google

Anda harus memverifikasi bahwa Google mengirim pesan sebelum memproses pesan tersebut konten.

Untuk memverifikasi bahwa Google mengirim pesan yang Anda terima,

1. Uraikan header X-Goog-Signature pesan. Ini adalah hash, salinan payload pesan berenkode base64.

2. Menggunakan token klien (yang ditampilkan saat Anda mengonfigurasi webhook) sebagai kunci, buat HMAC SHA512 dari byte payload pesan dan encoder-decoder menggunakan base64.

   Catatan: Jika Anda menerima kunci Partner saat mendaftar ke Business Pesan, menggunakannya sebagai kunci untuk HMAC SHA512, bukan klien sebelumnya yang benar. Jika Anda memperbarui webhook, gunakan token klien untuk pesan dengan konfigurasi webhook baru.

3. Bandingkan hash X-Goog-Signature dengan hash yang Anda buat.

   • Jika hash cocok, Anda telah mengonfirmasi bahwa Google yang mengirim pesan.
   • Jika {i>hash<i} tidak cocok, periksa proses {i>hashing<i} Anda pada untuk membuat pesan email baru. Jika proses {i>hashing<i} Anda bekerja dengan benar dan Anda menerima pesan yang Anda yakini dikirim kepada Anda secara curang, hubungi kami (Anda harus menandatangani dengan Akun Google Business Messages).

Lihat contoh verifikasi pesan di repositori GitHub untuk Echo Bots di Java, Node.js, dan Python.

Mengidentifikasi lokalitas

Pengguna berkomunikasi dari banyak lokasi dan dalam banyak bahasa. Business Messages mewakili pengguna preferensi bahasa dengan resolvedLocale dan userDeviceLocale kolom, yang didasarkan pada perangkatnya setelan lokalitas. Lihat Pelokalan dan lokalitas.

Bila memungkinkan, arahkan pesan dan tulis tanggapan berdasarkan pengguna bahasa preferensi Anda.

Merutekan pesan berdasarkan konteksnya

Konteks pesan menginformasikan jenis informasi yang mungkin dicari pengguna. Misalnya, jika pengguna mengirim pesan dengan placeId mereka mengirimkan pesan ke lokasi tertentu (yang diidentifikasi oleh placeId) dan cenderung mengajukan pertanyaan terkait lokasi tertentu. Demikian pula, jika pesan memiliki Nilai nearPlaceId, yang mengidentifikasi lokasi di dekat pengguna, kemungkinan pengguna ingin mengetahui informasi khusus lokasi, tetapi agen harus mengonfirmasi lokasi yang ingin diajak pengguna mengobrol sebelum memulai percakapan.

Dengan informasi konteks pesan, arahkan pesan ke lokasi yang terbaik sesuai untuk ditanggapi:

• Jika pesan ada dalam percakapan baru dan merupakan pertanyaan umum, Anda mungkin jawab melalui otomatisasi.
• Jika otomatisasi tidak dapat menangani pertanyaan tersebut, arahkan pertanyaan ke agen langsung.
• Jika lokalitas pesan tidak cocok dengan lokalitas default agen, rutekan pesan ke agen langsung yang dapat mendukung lokal tersebut.
• Jika pertanyaannya mengenai lokasi tertentu, arahkan pertanyaan itu kepada seseorang yang memiliki informasi tentang lokasi tersebut.
• Jika pesan berada dalam percakapan yang sedang berlangsung, arahkan pesan ke agen langsung yang berpartisipasi dalam percakapan.

Mengidentifikasi jenis pesan yang dikirim pengguna

Pengguna dapat mengirim tiga jenis pesan:

• Pesan teks adalah respons bentuk bebas.
• Pesan gambar menyertakan URL yang ditandatangani untuk gambar yang digunakan pengguna diupload.
• Pesan saran menyertakan data postback dan teks saran tindakan atau balasan yang disarankan yang diketuk pengguna.

Memproses konten pesan

Jika agen Anda menggunakan otomatisasi, isi pesan pengguna harus memandu Anda logika agen dan respons berikutnya dalam percakapan.

Cara termudah untuk mengidentifikasi niat pengguna adalah dengan data postback dari saran balasan atau tindakan yang disarankan. Terlepas dari teks yang terkait dengan saran tersebut, data postback dapat dibaca oleh mesin.

Jika pengguna mengirimkan pesan teks, agen Anda mungkin mengurai respons untuk kata kunci yang didukung atau gunakan natural language understanding (seperti Dialogflow integrasi untuk memproses pesan pengguna dan mengidentifikasi langkah ke depan.

Jika agen Anda tidak tahu cara membalas pesan pengguna, ia seharusnya merespons dengan status {i>error<i} dan mencoba melanjutkan percakapan dengan meminta informasi tambahan kepada pengguna, dengan cara meminta {i>input <i}di dengan cara berbeda, atau dengan menyerahkan percakapan kepada agen langsung.

Merespons pengguna

Setelah agen mengidentifikasi respons yang benar, baik melalui otomatisasi agen langsung, yakni mengirimkan pesan dan melanjutkan percakapan dengan pengguna.

Saat membuat respons, pertimbangkan bahasa pengguna. Anda juga dapat menyesuaikan respons dengan mengambil nilai dari objek userInfo di setiap pesan baru yang Anda terima.

Catatan: Jika Anda mengaktifkan respons otomatis di Dialogflow integrasi, Business Messages dan Dialogflow akan membalas pengguna atas nama Anda dengan memberikan jawaban terbaik respons yang cocok.

Jenis pesan

Kode berikut menunjukkan cara agen Anda menerima pesan.

Untuk informasi format dan nilai, lihat UserMessage

Teks

Cara paling umum bagi pengguna untuk merespons adalah dengan teks biasa. Pesan teks memiliki dalam 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

Gambar

Selain mengirim teks, pengguna dapat mengirim gambar ke agen Anda sebagai pesan. Business Messages menyimpan gambar yang dibagikan, selama 7 hari, di ditandatangani URL 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 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 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 OAuth untuk memberikan detail identitas kepada agen atau mengizinkan agen untuk melakukan tindakan terhadap nama Anda. Lihat Mengautentikasi dengan OAuth yang baru.

Jika pengguna berhasil login dengan penyedia OAuth yang ditentukan, maka agen menerima {i>payload<i} berisikan kode otorisasi. Jika pengguna tidak berhasil dalam login, agen akan menerima payload berisi 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 tempat pengguna memulai percakapan, seperti yang ditentukan oleh EntryPoint.
placeId	ID unik dari database Google Places untuk lokasi yang dikirimi pesan oleh pengguna. ID ini hanya muncul di pesan dari lokasi tertentu titik entri.
nearPlaceId	ID unik dari database Google Places untuk yang pertama dalam paket Lokal. Konfirmasi lokasi tempat pengguna ingin melakukan chat saat Anda menerima nilai nearPlaceId.
deflectedPhoneNumber	Nomor telepon yang mengalihkan pengguna dari panggilan Business Messages saat percakapan dimulai.
resolvedLocale	Kecocokan terbaik komputasi lokal pengguna (dilaporkan dalam userDeviceLocale) dan lokalitas yang didukung agen (ditentukan oleh setelan percakapan tertentu). Lihat Pelokalan dan Mulai percakapan. Nilai lokalitas berupa tag bahasa IETF BCP 47 yang tersusun dengan baik.
userInfo.displayName	Nama pengguna yang mengirim pesan. Jika pengguna memilih untuk tidak ikut berbagi identitas, kolom ini kosong.
userInfo.userDeviceLocale	Lokalitas pengguna, dilaporkan oleh perangkat mereka, sebagai format yang baik Tag bahasa IETF BCP 47.
widget.url	URL situs tempat platform percakapan diluncurkan.
widget.widgetContext	Nilai atribut data-bm-widget-context dari widget yang digunakan untuk memulai percakapan.

Histori percakapan

Google tidak memberikan histori percakapan. Simpan histori Anda sendiri percakapan, dengan cara yang sesuai dengan kebijakan privasi dan praktik terbaik Anda, sehingga Anda dapat mengirim tanggapan yang tepat untuk pesan mendatang dari pengguna.