Menerima peristiwa

Agen Anda menerima peristiwa webhook dari platform RBM, yang memberi tahu Anda tentang interaksi pengguna dan pembaruan tingkat platform.

Peristiwa ini dikategorikan berdasarkan asalnya:

  • Peristiwa pengguna: Notifikasi yang dikirim dari perangkat pengguna ke agen Anda, yang menandakan interaksi dengan agen Anda atau pesannya.
  • Peristiwa platform: Notifikasi tentang perubahan status peluncuran agen dan masa berlaku pesan yang dikirim oleh platform RBM.

Untuk mengetahui detail tentang peristiwa status yang dikirim agen Anda ke perangkat pengguna, lihat Mengirim peristiwa.

Peristiwa pengguna

Peristiwa pengguna adalah notifikasi dari perangkat pengguna yang melaporkan status pesan atau perubahan langganan (yaitu, pengguna telah berhenti berlangganan atau berlangganan kembali di Google Message).

Untuk opsi pemformatan dan nilai lengkap, lihat referensi UserEvent.

Pengguna menerima pesan agen

Peristiwa ini menunjukkan bahwa pesan telah berhasil dikirim ke perangkat pengguna.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "DELIVERED",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

Pengguna membaca pesan agen

Peristiwa ini menunjukkan bahwa pesan telah dibuka atau dibaca.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "READ",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

Pengguna mulai mengetik

Peristiwa ini menunjukkan bahwa pengguna sedang mengetik respons.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "IS_TYPING",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

Pengguna mengirim pesan teks

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "text": "Hi",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

Pengguna mengirim file

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "userFile": {
    "payload": {
      "mimeType": "image/gif",
      "fileSizeBytes": 127806,
      "fileUri": "https://storage.googleapis.com/copper_test/77ddb795-24ad-4607-96ae-b08b4d86406a/d2dcc67ab888d34ee272899c020b13402856f81597228322079eb007e8c9",
      "fileName": "4_animated.gif"
    }
  },
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

Pengguna mengetuk balasan yang disarankan

Saat pengguna mengetuk saran balasan, agen Anda akan menerima peristiwa dengan data dan teks postback balasan.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234",
    "text": "Hello there!"
  }
}

Pengguna mengetuk tindakan yang disarankan

Saat pengguna mengetuk tindakan yang disarankan, agen Anda akan menerima peristiwa dengan data postback tindakan.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234"
  }
}

Pengguna berhenti berlangganan percakapan

Peristiwa ini menunjukkan bahwa pengguna telah berhenti berlangganan untuk tidak menerima pesan yang tidak penting, seperti promosi, dari agen Anda dan bisnis yang diwakilinya. Pengguna memicu peristiwa ini dengan berhenti berlangganan percakapan RBM di Google Message.

Berikut adalah contoh payload JSON:

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "UNSUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

Cara kerja berhenti berlangganan

  • Opsi Berhenti berlangganan selalu tersedia di dalam menu chat. Untuk agen promosi dan multi-penggunaan, opsi ini juga muncul langsung di chat setelah sejumlah pesan yang belum dibaca (aturan khusus bervariasi menurut negara).

  • Memilih Berhenti berlangganan akan memicu dua tindakan serentak: Google Message mengirimkan kata kunci khusus negara (misalnya, "STOP") ke agen Anda, dan platform RBM mengirimkan peristiwa UNSUBSCRIBE ke webhook Anda.

    Kata kunci ditentukan oleh kode negara dua huruf dari nomor telepon pengguna. Tabel berikut mencantumkan kata kunci untuk setiap negara yang didukung.

    Negara (kode negara) Kata kunci berhenti berlangganan
    Amerika Serikat (US), India (IN), Inggris Raya (GB), Jerman (DE) BERHENTI
    Spanyol (ES), Meksiko (MX) BAJA
    Prancis (FR) BERHENTI
    Brasil (BR) parar

  • Setelah pengguna berhenti berlangganan, percakapan akan tetap ada di kotak masuknya kecuali jika dilaporkan sebagai spam, yang dalam hal ini percakapan akan dipindahkan ke folder Spam & diblokir.

  • Untuk mengidentifikasi pelanggaran kebijakan dan aturan bisnis, Google memantau pola pesan setelah pengguna berhenti berlangganan.

Aturan bisnis

  • Sebagai partner RBM yang mengelola percakapan ini, Anda bertanggung jawab untuk mematuhi permintaan pengguna untuk berhenti berlangganan.
  • Jika Anda tidak dapat membatalkan langganan dalam rangkaian pesan, Anda harus segera mengirim pesan konfirmasi dengan link langsung ke situs atau aplikasi tempat pengguna dapat mengelola preferensi langganan mereka.
  • Setelah pengguna berhenti berlangganan, pengiriman pesan yang tidak penting dilarang.
  • Pesan penting masih diizinkan. Hal ini mencakup:
    • Autentikasi, seperti sandi sekali pakai (OTP)
    • Notifikasi tentang layanan tertentu yang telah diminta dan disetujui pengguna
    • Konfirmasi permintaan berhenti berlangganan pengguna, dengan informasi untuk mengelola lebih lanjut preferensi komunikasi mereka

Contoh

Jika pengguna berhenti berlangganan dari agen maskapai yang kasus penggunaannya adalah multi-penggunaan, Anda harus berhenti mengirim pesan pemasaran. Namun, Anda dapat mengirimkan info terbaru penerbangan jika pengguna telah memberikan izin eksplisit untuk menerima info terbaru penerbangan tertentu tersebut.

Alasan berhenti berlangganan

Saat pengguna berhenti berlangganan dari agen Anda, mereka dapat memilih alasan dari opsi berikut:

  • Spam
  • Belum pernah mendaftar
  • Terlalu banyak pesan
  • Tidak tertarik lagi
  • Lainnya

Alasan berhenti berlangganan ditampilkan di ringkasan Analytics untuk membantu partner memahami alasan pengguna berhenti berlangganan.

Pengguna berlangganan ulang percakapan

Peristiwa ini menunjukkan bahwa pengguna ingin menerima pesan dari agen Anda lagi, termasuk konten yang tidak penting seperti promosi. Pengguna dapat memicu peristiwa ini dengan berlangganan ulang ke percakapan yang sebelumnya mereka batalkan langganannya di Google Message.

Berikut adalah contoh payload JSON:

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "SUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

Cara kerja berlangganan ulang

  • Opsi Berlangganan, yang tersedia dari menu chat dan link dalam chat, memungkinkan pengguna berlangganan lagi percakapan yang telah mereka batalkan langganannya.

  • Memilih Berlangganan akan memicu dua tindakan secara bersamaan: Google Message mengirimkan kata kunci khusus negara (misalnya, "MULAI") ke agen Anda, dan platform RBM mengirimkan peristiwa SUBSCRIBE ke webhook Anda. Kata kunci tertentu ditentukan oleh kode negara dua huruf dari nomor telepon pengguna. Tabel berikut mencantumkan kata kunci untuk setiap negara yang didukung.

    Negara (kode negara) Kata kunci langganan
    Amerika Serikat (US), India (IN), Inggris Raya (GB), Jerman (DE) MULAI
    Spanyol (ES), Meksiko (MX) ALTA
    Prancis (FR) Démarrer
    Brasil (BR) começar

Aturan bisnis

  • Sebagai partner RBM yang mengelola percakapan ini, Anda bertanggung jawab untuk mematuhi permintaan pengguna untuk berlangganan ulang.
  • Pendaftaran ulang berlaku untuk semua jenis pesan, termasuk konten tidak penting seperti promosi.
  • Jika pengguna mengirim pesan ke bisnis Anda setelah berhenti berlangganan, hal ini dapat dianggap sebagai permintaan untuk berlangganan kembali.
  • Jika pengguna berlangganan kembali di luar saluran pesan (misalnya, di situs Anda), Anda sebagai partner RBM bertanggung jawab untuk memperbarui statusnya dan melanjutkan pengiriman pesan sesuai dengan status tersebut.

Peristiwa platform

Platform RBM mengirimkan peristiwa platform untuk memberi tahu agen Anda tentang perubahan pada status peluncuran agen atau masa berlaku pesan.

Status peluncuran agen telah berubah

Platform RBM mengirimkan AgentLaunchEvent untuk setiap perubahan pada status peluncuran agen Anda. Misalnya, saat status agen Anda berubah dari PENDING menjadi LAUNCHED. Peristiwa dikirim sebagai pesan Pub/Sub. Untuk membedakannya dari peristiwa lain, periksa jalur message.attributes.type untuk nilai agent_launch_event.

Konfigurasi webhook

Anda dapat menggunakan webhook tingkat partner atau tingkat agen untuk menerima notifikasi ini.

Prasyarat

  • Konfigurasi webhook untuk pesan RBM (ini adalah persyaratan untuk menerima pesan pengguna dan acara pengguna).
  • Untuk membedakan peristiwa pengguna dan peristiwa status peluncuran agen, periksa jalur message.attributes.type untuk nilai agent_launch_event.

Struktur payload peristiwa

AgentLaunchEvent dikirimkan sebagai pesan Pub/Sub. Berikut contohnya:

{
  "message": {
    "attributes": {
      "business_id": "rbm-chatbot-id@rbm.goog",
      "event_type": "REJECTED",
      "product": "RBM",
      "project_number": "3338881441851",
      "type": "agent_launch_event"
    },
    "data": "....BASE64-encoded-JSON-with-notification...",
    "messageId": "14150481888479752",
    "message_id": "14150481888479752",
    "publishTime": "2025-03-05T18:50:21.88Z",
    "publish_time": "2025-03-05T18:50:21.88Z"
  },
  "subscription": "projects/rbm-partner-gcp/subscriptions/rbm-sub"
}

Kolom AgentLaunchEvent.LaunchState di payload peristiwa menunjukkan status peluncuran baru agen. Berikut adalah kemungkinan nilainya:

Nilai Status peluncuran agen Detail
UNLAUNCHED Belum diluncurkan Pengeditan diizinkan.
PENDING Tertunda Permintaan telah dikirim ke operator untuk ditinjau.
LAUNCHED Diluncurkan Pesan diizinkan di operator tertentu.
REJECTED Ditolak di operator tertentu Alasan penolakan ditentukan dalam komentar.
SUSPENDED Ditangguhkan di operator tertentu Alasan penangguhan ditentukan dalam komentar.

Kolom data berisi objek JSON berenkode Base64 dengan detail status peluncuran. Berikut adalah contoh JSON yang didekode:

    {
      "eventId": "rbm-chatbot-id/0a7ed168-676e-4a56-b422-b23434",
      "agentId": "rbm-chatbot-id@rbm.goog",
      "botDisplayName": "RBM Welcome Bot 7 - RBM Chatbot name",
      "brandId": "bd38fbff-392a-437b-a6f2-7f2e43745b56",
      "brandDisplayName": "Chatbots brand",
      "regionId": "/v1/regions/fi-rcs",
      "oldLaunchState": "PENDING",
      "newLaunchState": "REJECTED",
      "actingParty": "rbm-support@google.com",
      "comment": "Carrier has rejected the launch: policy violation",
      "sendTime": "2025-03-05T18:50:19.386436Z"
    }

Tabel berikut menunjukkan status peluncuran agen dan tindakan yang memicunya:

Status peluncuran lama Status peluncuran baru Pemicu perubahan
PENDING LAUNCHED Menunggu persetujuan agen.
PENDING REJECTED Agen tertunda ditolak.
LAUNCHED SUSPENDED Agen yang diluncurkan ditangguhkan.
SUSPENDED LAUNCHED Agen yang ditangguhkan diaktifkan kembali.
SUSPENDED TERMINATED Agen yang ditangguhkan dihentikan.
TERMINATED LAUNCHED Agen yang dihentikan diluncurkan.

Pesan sudah tidak berlaku; pencabutan berhasil

Peristiwa ini menunjukkan bahwa time to live (TTL) pesan telah berakhir dan pesan berhasil dibatalkan. Ini adalah pemicu yang baik untuk strategi pesan pengganti Anda.

Untuk opsi pemformatan dan nilai lengkap, lihat referensi ServerEvent.

{
  "phoneNumber": "[phone number]" ,
  "messageId": "[RCS message ID]",
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

Pesan telah berakhir; pencabutan gagal

Peristiwa ini menunjukkan bahwa TTL pesan telah berakhir, tetapi pesan tidak berhasil dicabut.

Untuk opsi pemformatan dan nilai lengkap, lihat referensi ServerEvent.

{
  "phoneNumber": "[phone number]",
  "messageId": "[RCS message ID]",
  "agentId": "[bot ID]",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

Pengiriman pesan tidak dijamin.

  • Jika pesan dikirim, Anda akan menerima peristiwa DELIVERED di webhook.
  • Jika pesan tidak terkirim, gunakan revoke API untuk mengirim permintaan pencabutan.

Jika pesan bersifat mendesak, seperti OTP atau peringatan penipuan, sebaiknya kirim pesan melalui saluran alternatif seperti SMS meskipun hal ini akan menyebabkan pesan duplikat bagi pengguna.

Sebelumnya
Mengirim peristiwa
Berikutnya
Pemeriksaan kemampuan