イベントを受信する

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

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

  • ユーザー イベント: ユーザーのデバイスからエージェントに送信される通知。エージェントとのやり取りを示します。
  • プラットフォーム イベント: 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",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234"
  }
}

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

このイベントは、ユーザーがエージェントとそのエージェントが代表するビジネスからのプロモーションなどの不要なメッセージの受信を解除したことを示します。ユーザーが Google メッセージで RBM 会話の登録を解除すると、このイベントがトリガーされます。

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

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

配信停止の仕組み

  • チャット メニューには、[配信停止] オプションが常に表示されます。プロモーション用エージェントとマルチユース エージェントの場合、一定数の未読メッセージがあると、このオプションがチャットに直接表示されます(具体的なルールは国によって異なります)。
  • [登録解除] を選択すると、2 つのアクションが同時にトリガーされます。Google メッセージは、国固有のキーワード(「STOP」など)をエージェントに送信し、RBM プラットフォームは UNSUBSCRIBE イベントを Webhook に送信します。

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

    国(国コード) 配信停止キーワード
    米国(US)、インド(IN)、英国(GB)、ドイツ(DE)、オランダ(NL) 停止
    スペイン(ES)、メキシコ(MX) BAJA
    フランス(FR) STOP
    ブラジル(BR) parar
  • ユーザーが登録を解除した後も、会話は受信トレイに残ります。ただし、スパムとして報告された場合は、[スパム / ブロック中] フォルダに移動します。

  • ポリシー違反やビジネスルール違反を特定するため、Google はユーザーが登録を解除した後のメッセージ パターンをモニタリングします。

ビジネスルール

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

例

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

登録解除の理由

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

  • メールの数が多すぎる
  • 登録した覚えがない
  • 興味がなくなった
  • 詐欺の可能性がある
  • その他

選択バイアスを軽減するため、最初の 4 つの選択肢はユーザーごとにランダムな順序で表示されます。この順序はユーザーの訪問全体で一貫しており、[その他] は下部に固定されたままになります。

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

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

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

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

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

再度定期購入の仕組み

  • [登録] オプションは、チャット メニューとチャット内のリンクの両方から利用できます。このオプションを使用すると、ユーザーは登録を解除した会話に再度登録できます。
  • [登録] を選択すると、2 つのアクションが同時にトリガーされます。Google メッセージは国固有のキーワード(「START」など)をエージェントに送信し、RBM プラットフォームは SUBSCRIBE イベントを Webhook に送信します。特定のキーワードは、ユーザーの電話番号の 2 文字の国コードによって決まります。次の表に、サポートされている各国のキーワードを示します。

    国(国コード) 「登録」キーワード
    米国(US)、インド(IN)、英国(GB)、ドイツ(DE)、オランダ(NL) 開始
    スペイン(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 メッセージング用にウェブフックを構成します(これは、ユーザー メッセージとユーザー イベントを受信するための要件です)。
  • ユーザー イベントとエージェント起動状態イベントを区別するには、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 フィールドは、エージェントの新しい起動状態を示します。指定できる値は次のとおりです。

値 エージェントの起動状態 詳細
PENDING 保留中 リクエストは審査のために運送業者に送信されました。
LAUNCHED リリース済み メッセージは特定の携帯通信会社で許可されます。
REJECTED 特定の携帯通信会社で拒否された 不承認の理由はコメントに記載されています。
SUSPENDED 特定の携帯通信会社で停止されている 参加停止の理由はコメントに記載されています。
UNLAUNCHED 未リリース すべての携帯通信会社からリリースが解除されたエージェントは編集できます。

データ フィールドには、起動状態の詳細を含む 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 UNLAUNCHED エージェントを終了します。
REJECTED LAUNCHED 以前に不承認となったリリース リクエストを承認します。

パートナー様主導のリリース状態の変更

通常、パートナーが処理する移行は次のとおりです。

古いリリース ステータス 新しいリリース ステータス トリガー アクション
UNSPECIFIED PENDING 審査のために送信します。
PENDING UNLAUNCHED 保留中のリリース リクエストをキャンセルします。
UNLAUNCHED PENDING 審査のために送信します。
REJECTED PENDING 審査のために再送信します。
SUSPENDED PENDING 審査のために再送信します。

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

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

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

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

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

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

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

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

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

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

OTP や不正行為のアラートなど、メッセージが時間的に重要である場合は、ユーザーに重複したメッセージが送信されることになっても、SMS などの代替チャネルを介してメッセージを送信することをおすすめします。