Acara

Peristiwa adalah notifikasi yang dapat dikirim dan diterima oleh agen Anda. Ada tiga jenis peristiwa:

• Buatan server: Dikirim ke agen Anda oleh platform RBM
• Buatan pengguna: Dikirim ke agen Anda oleh perangkat pengguna
• Buatan agen: Dikirim oleh agen Anda kepada pengguna

Peristiwa yang dibuat server

Platform RBM mengirimkan peristiwa untuk memberi tahu agen Anda tentang pembaruan tingkat server seperti masa berlaku pesan.

Untuk opsi pemformatan dan nilai, lihat ServerEvent.

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 setelah persetujuan operator, Anda akan menerima peristiwa AgentLaunchEvent untuk menunjukkan perubahan tersebut. Peristiwa ini dikirim untuk semua agen RBM, untuk semua perubahan status peluncuran operator.

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 peristiwa buatan pengguna).
• Untuk membedakan peristiwa buatan pengguna dan peristiwa status peluncuran agen, periksa jalur message.attributes.type untuk nilai agent_launch_event.

Struktur payload peristiwa

AgentLaunchEvent dikirim sebagai pesan Pub/Sub. Berikut contohnya:

{
  "message": {
    "attributes": {
      "business_id": "[e-mail]",
      "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": "[e-mail]",
      "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": "[e-mail]",
      "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

Pesan telah berakhir dan berhasil dibatalkan. Peristiwa ini akan menjadi pemicu yang baik untuk strategi pesan pengganti Anda.

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

Pesan sudah tidak berlaku; pencabutan gagal

Masa berlaku pesan telah berakhir, tetapi pesan tidak dicabut.

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

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 mengakibatkan pesan duplikat kepada pengguna.

Peristiwa buatan pengguna

Seperti halnya pesan pengguna dan pemeriksaan kemampuan, agen Anda menerima peristiwa pengguna sebagai JSON.

Untuk opsi pemformatan dan nilai, lihat UserEvent.

Pengguna menerima pesan agen

Peristiwa ini menunjukkan bahwa pesan telah dikirim.

{
  "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.

{
  "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 postback dan teks 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

Beta: Kami meluncurkan fitur Berhenti Berlangganan secara bertahap di Google Pesan, sehingga pengguna mungkin tidak langsung dapat mengaksesnya. Untuk mendapatkan akses sebelum peluncuran penuh, Anda dapat bergabung dengan program Beta Terbuka Pesan.

Penting: Untuk membantu developer beralih ke peristiwa webhook UNSUBSCRIBE dan SUBSCRIBE yang baru, Google Pesan juga mengirimkan pesan "STOP" dan "START" bersama dengan peristiwa webhook. Meskipun Anda dapat mengandalkan logika STOP/START yang ada untuk saat ini, sebaiknya perbarui logika Anda untuk menangani peristiwa UNSUBSCRIBE dan SUBSCRIBE, karena peristiwa ini akan menjadi wajib sesuai dengan spesifikasi GSMA.

Jika pengguna tidak ingin menerima pesan yang tidak penting dari bisnis, seperti promosi, mereka dapat berhenti berlangganan percakapan RBM di Google Message.

Peristiwa UNSUBSCRIBE menunjukkan bahwa pengguna telah berhenti berlangganan percakapan dengan agen Anda dan bisnis yang diwakilinya. Berikut adalah contoh payload JSON:

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

Cara kerjanya

• 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 secara bersamaan: Google Message mengirimkan kata kunci khusus negara (misalnya, "STOP") ke agen Anda, dan platform RBM mengirimkan peristiwa BERHENTI BERLANGGANAN 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 penerbangan 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:

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

Saat ini, alasan berhenti berlangganan tidak dibagikan kepada partner atau operator.

Pengguna berlangganan ulang percakapan

Beta: Kami meluncurkan fitur Berlangganan di Google Pesan secara bertahap, sehingga pengguna mungkin belum dapat mengaksesnya. Untuk mendapatkan akses sebelum peluncuran penuh, Anda dapat bergabung dengan program Beta Terbuka Pesan.

Penting: Untuk membantu developer beralih ke peristiwa webhook UNSUBSCRIBE dan SUBSCRIBE yang baru, Google Pesan juga mengirimkan pesan "STOP" dan "START" bersama dengan peristiwa webhook. Meskipun Anda dapat mengandalkan logika STOP/START yang ada untuk saat ini, sebaiknya perbarui logika Anda untuk menangani peristiwa UNSUBSCRIBE dan SUBSCRIBE, karena peristiwa ini akan menjadi wajib sesuai dengan spesifikasi GSMA.

Pengguna dapat berlangganan kembali percakapan yang sebelumnya mereka batalkan langganannya di Google Message.

Peristiwa SUBSCRIBE menunjukkan bahwa pengguna ingin menerima pesan dari agen Anda, termasuk konten tidak penting seperti promosi. Berikut adalah contoh payload JSON:

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

Cara kerjanya

• 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 berlangganan
  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.
• Berlangganan 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 yang dibuat agen

Agen Anda mengirimkan peristiwa untuk menyimulasikan interaksi manusia dan meyakinkan pengguna bahwa agen Anda berinteraksi dengan pesan mereka. Bagi pengguna, acara ditampilkan sebagai notifikasi dalam percakapan mereka.

Untuk opsi pemformatan dan nilai, lihat phones.agentEvents.

Agen mengirim peristiwa READ

Bagi pengguna, peristiwa ini muncul sebagai tanda terima telah dibaca untuk pesan tertentu. Pesan ini memberi tahu pengguna bahwa platform RBM telah mengirimkan pesannya dan agen sedang memprosesnya.

Kode berikut mengirimkan peristiwa READ untuk pesan dengan messageId yang cocok.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'READ',
  'messageId': 'MESSAGE_ID'
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage('[phone]', messageId);

Kode ini adalah kutipan dari agen contoh RBM.

Java

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage(messageId, "[phone]");

Kode ini adalah kutipan dari agen contoh RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that message_id was read
rbm_service.send_read_event('[phone]', message_id)

Kode ini adalah kutipan dari agen contoh RBM.

C#

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that messageId has been read
rbmApiHelper.SendReadMessage(messageId, "[phone]");

Kode ini adalah kutipan dari agen contoh RBM.

Agen mengirim peristiwa IS_TYPING

Bagi pengguna, peristiwa ini muncul sebagai indikator pengetikan dan memberi tahu mereka bahwa agen Anda sedang menyusun pesan. Indikator pengetikan akan berakhir setelah beberapa saat (sekitar 20 detik) atau saat perangkat pengguna menerima pesan baru dari agen Anda. Agen Anda dapat mengirim beberapa peristiwa IS_TYPING untuk mereset timer habis masa berlaku indikator pengetikan.

Kode berikut mengirimkan peristiwa IS_TYPING.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'IS_TYPING',
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage('[phone]', function() {
    console.log('Typing event sent!');
});

Kode ini adalah kutipan dari agen contoh RBM.

Java

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage("[phone]");

Kode ini adalah kutipan dari agen contoh RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that the agent is typing
rbm_service.send_is_typing_event('[phone]')

Kode ini adalah kutipan dari agen contoh RBM.

C#

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that the agent is typing
rbmApiHelper.SendIsTypingMessage(messageId, "[phone]");

Kode ini adalah kutipan dari agen contoh RBM.