Получение событий

Ваш агент получает события вебхука от платформы 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",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234"
  }
}

Пользователь отменяет подписку на чат.

Это событие означает, что пользователь отказался от получения несущественных сообщений, например рекламных, от вашего агента и компании, которую он представляет. Пользователи активируют это событие, отменяя подписку на чат RBM в Google Сообщениях.

Пример полезной нагрузки JSON:

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

Как работает отмена подписки

  • Пункт Отменить подписку всегда доступен в меню чата. Для рекламных и многоцелевых агентов эта возможность также появляется непосредственно в чате после определенного количества непрочитанных сообщений (конкретные правила зависят от страны).
  • Если пользователь нажмет Отменить подписку, произойдет два действия: Google Сообщения отправят вашему агенту ключевое слово, которое зависит от страны (например, "STOP"), а платформа RBM отправит событие UNSUBSCRIBE вашему вебхуку.

    Ключевое слово определяется двухбуквенным кодом страны, к которой относится номер телефона пользователя. В таблице ниже перечислены ключевые слова для каждой поддерживаемой страны.

    Страна (код страны) Ключевое слово для отмены подписки
    Великобритания (GB), Германия (DE), Индия (IN), Нидерланды (NL), США (US) ОСТАНОВИТЬ
    Испания (ES), Мексика (MX) BAJA
    Франция (FR) STOP
    Бразилия (BR) parar
  • После отмены подписки чат остается в папке "Входящие", если только пользователь не пожалуется на спам. В этом случае чат перемещается в папку Спам и заблокированные.

  • Чтобы выявлять нарушения правил и бизнес-требований, Google отслеживает шаблоны сообщений после того, как пользователь отменяет подписку.

Бизнес-правила

  • Как партнер RBM, управляющий этим чатом, вы обязаны выполнить запрос пользователя на отмену подписки.
  • Если вы не можете отменить подписку в цепочке сообщений, вы должны немедленно отправить сообщение с подтверждением и прямой ссылкой на сайт или приложение, где пользователи могут управлять своими подписками.
  • После отмены подписки отправка несущественных сообщений запрещена.
  • Важные сообщения по-прежнему разрешены. в том числе:
    • Аутентификация, например одноразовые коды.
    • Уведомления о конкретном сервисе, которые пользователь запросил и на которые дал согласие.
    • Подтверждение запроса пользователя на отмену подписки с информацией о том, как управлять настройками связи.

Пример

Если пользователь отменит подписку на агента авиакомпании, который используется для нескольких целей, вы должны прекратить отправлять ему маркетинговые сообщения. Однако вы можете отправлять обновления, если пользователь дал явное согласие на их получение для конкретного рейса.

Причины отмены подписки

Когда пользователь отменяет подписку на вашего агента, он может выбрать одну из следующих причин:

  • Слишком много сообщений
  • Я не оформлял эту подписку
  • Мне больше не интересно
  • Похоже на мошенничество
  • Другое

Чтобы снизить систематическую ошибку отбора, первые четыре варианта показываются каждому пользователю в случайном порядке. Этот порядок сохраняется при последующих посещениях, а вариант Другое всегда остается внизу.

Причины отмены подписки агрегируются и показываются в обзоре аналитики, чтобы вы могли понять, почему пользователи отменяют подписку.

Пользователь снова подписывается на чат

Это событие означает, что пользователь снова хочет получать сообщения от вашего агента, в том числе необязательный контент, например рекламные акции. Пользователи могут активировать это событие, повторно подписавшись на чат, от которого они ранее отписались в Google Сообщениях.

Пример полезной нагрузки JSON:

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

Как работает возобновление подписки

  • Пункт Подписаться, доступный как в меню чата, так и по ссылке в чате, позволяет пользователям повторно подписаться на чат, от которого они отписались.
  • При нажатии на кнопку Подписаться одновременно выполняются два действия: Google Сообщения отправляют вашему агенту ключевое слово, зависящее от страны (например, "START"), а платформа RBM отправляет событие SUBSCRIBE вашему вебхуку. Ключевое слово определяется двухбуквенным кодом страны, к которой относится номер телефона пользователя. В таблице ниже перечислены ключевые слова для каждой поддерживаемой страны.

    Страна (код страны) Ключевое слово для подписки
    Великобритания (GB), Германия (DE), Индия (IN), Нидерланды (NL), США (US) НАЧАТЬ
    Испания (ES), Мексика (MX) ALTA
    Франция (FR) Démarrer
    Бразилия (BR) começar

Бизнес-правила

  • Как партнер RBM, управляющий этим чатом, вы обязаны выполнить запрос пользователя на повторную подписку.
  • Повторная подписка применяется ко всем типам сообщений, включая необязательный контент, например промоакции.
  • Если пользователь отправит сообщение вашей компании после отмены подписки, это может считаться запросом на повторную подписку.
  • Если пользователь возобновит подписку за пределами канала обмена сообщениями (например, на вашем сайте), вы как партнер RBM должны будете обновить его статус и возобновить отправку сообщений.

События платформы

Платформа RBM отправляет события платформы, чтобы уведомить агента об изменениях в его статусе запуска или об истечении срока действия сообщений.

Статус запуска агента изменился

Платформа RBM отправляет AgentLaunchEvent при каждом изменении статуса запуска агента. Например, когда статус агента меняется с PENDING на LAUNCHED. Событие доставляется в виде сообщения Pub/Sub. Чтобы отличить это событие от других, проверьте путь message.attributes.type на наличие значения agent_launch_event.

Конфигурация вебхука

Чтобы получать такие уведомления, вы можете использовать вебхук на уровне партнера или агента.

Требования

  • Настройте вебхук для обмена сообщениями RBM (это необходимо для получения сообщений и событий пользователей).
  • Чтобы отличить пользовательские события от событий запуска агента, проверьте путь message.attributes.type на наличие значения agent_launch_event.

Структура полезной нагрузки события

AgentLaunchEvent доставляется в виде сообщения издатель-подписчик.

Пример:

{
  "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 Не запущено Редактировать можно агентов, которые были отключены у всех операторов.

Поле данных содержит объект JSON в кодировке Base64 с информацией о статусе запуска. Вот пример декодированного 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"
}

Срок действия сообщения истек. Не удалось отозвать сообщение.

Это событие означает, что срок жизни сообщения истек, но оно не было успешно отозвано.

Полный список вариантов форматирования и значений приведен в справочнике ServerEvent.

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

Доставка сообщений не гарантируется.

  • Если сообщение было доставлено, вы получите событие DELIVERED в вебхуке.
  • Если сообщение не было доставлено, используйте API отзыва, чтобы отправить запрос на отзыв.

Если сообщение срочное, например одноразовый код или предупреждение о мошенничестве, лучше отправить его по альтернативному каналу, например SMS, даже если пользователь получит дубликат.