イベントは、エージェントが送受信できる通知です。イベントには次の 3 種類があります。
- サーバー生成: RBM プラットフォームからエージェントに送信されます
- ユーザー生成: ユーザーのデバイスからエージェントに送信されます
- エージェント生成: エージェントからユーザーに送信されたメッセージ
サーバー生成イベント
RBM プラットフォームは、メッセージの有効期限切れなどのサーバーレベルの更新についてエージェントに通知するイベントを送信します。
書式設定と値のオプションについては、ServerEvent をご覧ください。
エージェントの起動ステータスが変更されました
RBM プラットフォームは、エージェントのリリース ステータスの変更ごとに AgentLaunchEvent を送信します。たとえば、携帯通信会社の承認後にエージェントの状態が PENDING から LAUNCHED に変更されると、変更を示す AgentLaunchEvent イベントが送信されます。これらのイベントは、すべての RBM エージェントに対して、すべての携帯通信会社のリリース状態の変更について送信されます。
Webhook の構成
これらの通知は、パートナー レベルまたはエージェント レベルの Webhook を使用して受信できます。
前提条件
- RBM メッセージング用に Webhook を構成します（ユーザー メッセージとユーザー生成イベントを受信するための要件です）。
- ユーザー生成イベントとエージェント起動状態イベントを区別するには、
message.attributes.typeパスの値がagent_launch_eventであるかどうかを確認します。
イベント ペイロードの構造
AgentLaunchEvent は Pub/Sub メッセージとして配信されます。次の例をご覧ください。
{
"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"
}
イベント ペイロードの AgentLaunchEvent.LaunchState フィールドは、エージェントの新しい起動状態を示します。使用できる値は次のとおりです。
| 値 | エージェントの起動状態 | 詳細 |
|---|---|---|
UNLAUNCHED |
未リリース | 編集が許可されています。 |
PENDING |
保留 | リクエストは審査のために運送業者に送信されました。 |
LAUNCHED |
リリース済み | 特定の携帯通信会社でメッセージが許可されています。 |
REJECTED |
特定の携帯通信会社で拒否された | 不承認の理由はコメントに記載されています。 |
SUSPENDED |
特定の携帯通信会社で停止されている | 停止の理由はコメントで指定されています。 |
データ フィールドには、リリース状態の詳細を含む Base64 エンコードの JSON オブジェクトが含まれます。デコードされた JSON の例を次に示します。
{
"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"
}
次の表に、エージェントの起動状態と、その状態をトリガーするアクションを示します。
| 以前のリリース状態 | 新規リリース状態 | 変化のトリガー |
|---|---|---|
PENDING |
LAUNCHED |
エージェントの承認待ち。 |
PENDING |
REJECTED |
保留中のエージェントが拒否されました。 |
LAUNCHED |
SUSPENDED |
起動されたエージェントが一時停止されました。 |
SUSPENDED |
LAUNCHED |
停止中のエージェントが再有効化されました。 |
SUSPENDED |
TERMINATED |
一時停止されたエージェントが終了しました。 |
TERMINATED |
LAUNCHED |
終了したエージェントが起動しました。 |
メッセージの有効期限が切れました。取り消しは成功しました
メッセージの有効期限が切れ、正常に取り消されました。このイベントは、フォールバック メッセージ戦略のトリガーとして適しています。
{ "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] }
メッセージの有効期限が切れました。取り消しに失敗しました
メッセージは期限切れですが、取り消されていません。
{ "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] }
メッセージの配信は保証されません。
- メッセージが配信されると、Webhook で
DELIVEREDイベントが受信されます。 - メッセージが配信されなかった場合は、revoke API を使用して取り消しリクエストを送信します。
OTP や不正行為アラートなど、メッセージが時間的制約を受ける場合は、ユーザーに重複したメッセージが届くことになっても、SMS などの別のチャネルでメッセージを送信することをおすすめします。
ユーザー生成イベント
ユーザー メッセージやケーパビリティ チェックと同様に、エージェントはユーザー イベントを JSON として受け取ります。
書式設定と値のオプションについては、UserEvent をご覧ください。
ユーザーがエージェントのメッセージを受信する
このイベントは、メッセージが配信されたことを示します。
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "DELIVERED",
"eventId": "EVENT_ID",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID"
}ユーザーがエージェントのメッセージを読む
このイベントは、メッセージが開かれたか、確認されたことを示します。
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "READ",
"eventId": "EVENT_ID",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID"
}ユーザーが入力を開始する
このイベントは、ユーザーが入力中であることを示します。
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "IS_TYPING",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}ユーザーがテキスト メッセージを送信する
{
"senderPhoneNumber": "PHONE_NUMBER",
"text": "Hi",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}ユーザーがファイルを送信する
{ "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" }
ユーザーが返信の候補をタップする
ユーザーが返信候補をタップすると、エージェントは返信のポストバック データとテキストを含むイベントを受け取ります。
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID",
"suggestionResponse": {
"postbackData": "postback_1234",
"text": "Hello there!"
}
}ユーザーが候補のアクションをタップする
ユーザーが提案されたアクションをタップすると、エージェントはアクションのポストバック データを含むイベントを受け取ります。
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID",
"suggestionResponse": {
"postbackData": "postback_1234"
}
}ユーザーが会話の登録を解除する
プロモーションなど、ビジネスからの不要なメッセージを受信しないようにするには、Google メッセージで RBM 会話の配信登録を解除します。
UNSUBSCRIBE イベントは、ユーザーがエージェントおよびそのエージェントが代表するビジネスとの会話の登録を解除したことを示します。JSON ペイロードの例を次に示します。
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "UNSUBSCRIBE",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}仕組み
- チャット メニューには常に [登録解除] オプションが表示されます。プロモーション エージェントと複数回使用エージェントの場合、このオプションは、未読メッセージが一定数を超えるとチャットに直接表示されます（具体的なルールは国によって異なります）。
[登録解除] を選択すると、2 つのアクションが同時にトリガーされます。Google メッセージは国固有のキーワード（「STOP」など）をエージェントに送信し、RBM プラットフォームは登録解除イベントを Webhook に送信します。
キーワードは、ユーザーの電話番号の 2 桁の国コードによって決まります。次の表に、サポートされている各国のキーワードを示します。
国（国コード） 登録解除キーワード 米国（US）、インド（IN）、英国（GB）、ドイツ（DE） 停止 スペイン（ES）、メキシコ（MX） BAJA フランス（FR） 停止 ブラジル（BR） parar ユーザーが登録を解除した後、会話は受信トレイに残ります。ただし、スパムとして報告された場合は、[スパム / ブロック中] フォルダに移動します。
ポリシーとビジネスルールの違反を特定するため、Google はユーザーが登録を解除した後のメッセージ パターンをモニタリングします。
ビジネスルール
- この会話を管理する RBM パートナーとして、ユーザーの登録解除リクエストに対応する責任があります。
- メッセージ スレッド内で登録解除を実行できない場合は、ユーザーが購読設定を管理できるウェブサイトまたはアプリへの直接リンクを記載した確認メッセージを直ちに送信する必要があります。
- ユーザーが登録を解除すると、不要なメッセージの送信は禁止されます。
- 重要なメッセージは引き続き許可されます。たとえば、以下のようなものがあります。
- 認証（ワンタイム パスワード（OTP）など）
- ユーザーがリクエストして同意した特定のサービスに関する通知
- ユーザーの配信停止リクエストの確認と、コミュニケーション設定をさらに管理するための情報
例
ユースケースが複数回使用の航空会社エージェントからユーザーが登録を解除した場合は、マーケティング メッセージの送信を停止する必要があります。ただし、ユーザーが特定のフライトの更新情報を受け取ることに明示的に同意している場合は、フライトの更新情報を送信できます。
登録解除の理由
ユーザーがエージェントの登録を解除する際に、次のいずれかの理由を選択できます。
- 申し込んでいない
- メールの数が多すぎる
- 興味がなくなった
- スパム
- その他
現在、配信登録解除の理由はパートナーや携帯通信会社と共有されていません。
ユーザーが会話に再登録する
Google メッセージで、以前に登録を解除した会話に再度登録できます。
SUBSCRIBE イベントは、ユーザーがエージェントからのメッセージ（プロモーションなどの不要なコンテンツを含む）の受信を希望していることを示します。JSON ペイロードの例を次に示します。
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "SUBSCRIBE",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}仕組み
- チャット メニューとチャット内のリンクの両方から利用できる [登録] オプションを使用すると、ユーザーは登録を解除した会話に再度登録できます。
[登録] を選択すると、2 つのアクションが同時にトリガーされます。Google メッセージが国固有のキーワード（「START」など）をエージェントに送信し、RBM プラットフォームが SUBSCRIBE イベントを Webhook に送信します。
特定のキーワードは、ユーザーの電話番号の 2 文字の国コードによって決まります。次の表に、サポートされている各国のキーワードを示します。
国（国コード） チャンネル登録キーワード 米国（US）、インド（IN）、英国（GB）、ドイツ（DE） 開始 スペイン（ES）、メキシコ（MX） ALTA フランス（FR） Démarrer ブラジル（BR） começar
ビジネスルール
- この会話を管理する RBM パートナーは、再登録を求めるユーザーのリクエストに対応する責任があります。
- 再登録は、プロモーションなどの重要でないコンテンツを含む、すべてのメッセージ タイプに適用されます。
- ユーザーが登録解除後にビジネスにメッセージを送信した場合、これは再登録リクエストとみなされます。
- ユーザーがメッセージ チャネル以外で再登録した場合（ウェブサイトなど）、RBM パートナーとしてユーザーのステータスを更新し、それに応じてメッセージの送信を再開する責任があります。
エージェント生成イベント
エージェントは、人間のやり取りをシミュレートし、エージェントがメッセージに応答していることをユーザーに保証するために、イベントを送信します。ユーザーには、会話内の通知としてイベントが表示されます。
書式設定と値のオプションについては、phones.agentEvents をご覧ください。
エージェントが READ イベントを送信する
ユーザーには、このイベントは特定のメッセージの既読確認として表示されます。RBM プラットフォームがメッセージを配信し、エージェントがメッセージを処理していることをユーザーに知らせます。
次のコードは、一致する messageId を含むメッセージの READ イベントを送信します。
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('+12223334444', messageId);
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, "+12223334444");
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('+12223334444', message_id)
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, "+12223334444");
エージェントが IS_TYPING イベントを送信する
ユーザーには、このイベントは入力インジケーターとして表示され、エージェントがメッセージを作成していることを知らせます。入力インジケーターは、短時間（約 20 秒）経過するか、ユーザーのデバイスがエージェントから新しいメッセージを受信すると、期限切れになります。エージェントは、複数の IS_TYPING イベントを送信して、入力インジケーターの有効期限タイマーをリセットできます。
次のコードは 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('+12223334444', function() { console.log('Typing event sent!'); });
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("+12223334444");
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('+12223334444')
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, "+12223334444");