このページは Cloud Translation API によって翻訳されました。

イベントを受信する

エージェントは RBM プラットフォームからウェブフックイベントを受信し、ユーザーの操作とプラットフォームレベルの更新の両方を通知します。

これらのイベントは、発生元によって分類されます。

ユーザーイベント: ユーザーのデバイスからエージェントに送信される通知。エージェントまたはそのメッセージとのやり取りを知らせます。
プラットフォームイベント: RBM プラットフォームから送信される、エージェントの起動状態の変化とメッセージの有効期限に関する通知。

エージェントがユーザーのデバイスに送信するステータスイベントの詳細については、イベントを送信するをご覧ください。

ユーザーイベント

ユーザーイベントは、メッセージのステータスやサブスクリプションの変更（ユーザーが Google メッセージで登録解除または再登録したなど）を報告する、ユーザーのデバイスからの通知です。

書式設定と値のオプションについては、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 および SUBSCRIBE Webhook イベントに移行できるように、Google メッセージは Webhook イベントとともに「STOP」メッセージと「START」メッセージも送信しています。当面は既存の STOP/START ロジックに依存できますが、GSMA 仕様に準拠して UNSUBSCRIBE イベントと SUBSCRIBE イベントを処理するようにロジックを更新することを強くおすすめします。

JSON ペイロードの例を次に示します。

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

購読解除の仕組み

チャットメニューには、常に [登録解除] オプションが表示されます。プロモーションエージェントと複数回使用エージェントの場合、このオプションは、未読メッセージが一定数を超えるとチャットに直接表示されます（具体的なルールは国によって異なります）。

[登録解除] を選択すると、2 つのアクションが同時にトリガーされます。Google メッセージは国固有のキーワード（「STOP」など）をエージェントに送信し、RBM プラットフォームは UNSUBSCRIBE イベントを Webhook に送信します。

キーワードは、ユーザーの電話番号の 2 文字の国コードによって決まります。次の表に、サポートされている各国のキーワードを示します。

国（国コード）	登録解除キーワード
米国（US）、インド（IN）、英国（GB）、ドイツ（DE）	停止
スペイン（ES）、メキシコ（MX）	BAJA
フランス（FR）	停止
ブラジル（BR）	parar

ユーザーが登録を解除した後、会話は受信トレイに残ります。ただし、スパムとして報告された場合は、[スパム / ブロック中] フォルダに移動します。
ポリシーとビジネスルールの違反を特定するため、Google はユーザーが登録を解除した後のメッセージパターンをモニタリングします。

ビジネスルール

この会話を管理する RBM パートナーとして、配信停止を求めるユーザーのリクエストに対応する責任があります。
メッセージスレッド内で登録解除を実行できない場合は、ユーザーがサブスクリプション設定を管理できるウェブサイトまたはアプリへの直接リンクを記載した確認メッセージを直ちに送信する必要があります。
ユーザーが登録を解除すると、不要なメッセージの送信は禁止されます。
重要なメッセージは引き続き許可されます。たとえば、以下のようなものがあります。
- 認証（ワンタイムパスワード（OTP）など）
- ユーザーがリクエストして同意した特定のサービスに関する通知
- ユーザーの配信停止リクエストの確認と、コミュニケーション設定をさらに管理するための情報

例

ユースケースが複数回使用の航空会社エージェントからユーザーが登録を解除した場合は、マーケティングメッセージの送信を停止する必要があります。ただし、ユーザーが特定のフライトの更新情報を受け取ることに明示的に同意している場合は、フライトの更新情報を送信できます。

登録解除の理由

ユーザーがエージェントの登録を解除する際に、次のオプションから理由を選択できます。

スパム
登録していない
メールの数が多すぎる
興味がなくなった
その他

パートナーがユーザーの登録解除の理由を把握できるよう、登録解除の理由がアナリティクスの概要に表示されます。

ユーザーが会話に再登録する

このイベントは、ユーザーがエージェントからのメッセージ（プロモーションなどの不要なコンテンツを含む）を再び受信することを希望していることを示します。ユーザーがこのイベントをトリガーするには、Google メッセージで以前に登録解除した会話に再度登録します。

JSON ペイロードの例を次に示します。

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

再登録の仕組み

チャットメニューとチャット内のリンクの両方から利用できる [登録] オプションを使用すると、ユーザーは登録を解除した会話に再度登録できます。

[登録] を選択すると、2 つのアクションが同時にトリガーされます。Google メッセージから国固有のキーワード（「START」など）がエージェントに送信され、RBM プラットフォームから SUBSCRIBE イベントが Webhook に送信されます。特定のキーワードは、ユーザーの電話番号の 2 文字の国コードによって決まります。次の表に、サポートされている各国のキーワードを示します。

国（国コード）	Subscribe キーワード
米国（US）、インド（IN）、英国（GB）、ドイツ（DE）	開始
スペイン（ES）、メキシコ（MX）	ALTA
フランス（FR）	Démarrer
ブラジル（BR）	começar

ビジネスルール

この会話を管理する RBM パートナーは、ユーザーの再登録リクエストに対応する責任があります。
再登録は、プロモーションなどの重要でないコンテンツを含む、すべてのメッセージタイプに適用されます。
ユーザーが配信登録を解除した後にビジネスにメッセージを送信した場合、これは再登録リクエストと見なされます。
ユーザーがメッセージチャネル以外で再登録した場合（ウェブサイトなど）、RBM パートナーとしてユーザーのステータスを更新し、それに応じてメッセージの送信を再開する責任があります。

プラットフォームイベント

RBM プラットフォームは、エージェントの起動状態またはメッセージの有効期限の変更をエージェントに通知するために、プラットフォームイベントを送信します。

エージェントの起動ステータスが変更されました

RBM プラットフォームは、エージェントのリリースステータスが変更されるたびに AgentLaunchEvent を送信します。たとえば、エージェントの状態が PENDING から LAUNCHED に変わった場合などです。イベントは Pub/Sub メッセージとして配信されます。他のイベントと区別するには、message.attributes.type パスで値 agent_launch_event を確認します。

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`	終了したエージェントが起動しました。

メッセージの有効期限が切れました。取り消しは成功しました

このイベントは、メッセージの有効期間（TTL）が終了し、メッセージが正常に取り消されたことを示します。これは、フォールバックメッセージ戦略の適切なトリガーとなります。

書式設定と値のオプションについては、ServerEvent リファレンスをご覧ください。

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

メッセージの有効期限が切れました。取り消しに失敗しました

このイベントは、メッセージの TTL が期限切れになったが、正常に取り消されなかったことを示します。

書式設定と値のオプションについては、ServerEvent リファレンスをご覧ください。

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

メッセージの配信は保証されません。

メッセージが配信されると、Webhook で DELIVERED イベントが受信されます。
メッセージが配信されなかった場合は、取り消し API を使用して取り消しリクエストを送信します。

OTP や不正行為アラートなど、緊急性の高いメッセージの場合は、ユーザーに重複したメッセージが届くことになっても、SMS などの別のチャネルでメッセージを送信することをおすすめします。

イベントを送信する

機能チェック

イベントを受信する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

ユーザー イベント

ユーザーがエージェントのメッセージを受信する

ユーザーがエージェントのメッセージを読む

ユーザーが入力を開始する

ユーザーがテキスト メッセージを送信する

ユーザーがファイルを送信する

ユーザーが返信の候補をタップする

ユーザーが提案されたアクションをタップする

ユーザーが会話の登録を解除する

購読解除の仕組み

ビジネスルール

例

登録解除の理由

ユーザーが会話に再登録する

再登録の仕組み

ビジネスルール

プラットフォーム イベント

エージェントの起動ステータスが変更されました

Webhook の構成

前提条件

イベント ペイロードの構造

メッセージの有効期限が切れました。取り消しは成功しました

メッセージの有効期限が切れました。取り消しに失敗しました

イベントを受信する

ユーザーイベント

ユーザーがテキストメッセージを送信する

プラットフォームイベント

イベントペイロードの構造