Receber eventos

O agente recebe eventos de webhook da plataforma RBM, notificando você sobre interações do usuário e atualizações da plataforma.

Esses eventos são categorizados por origem:

  • Eventos do usuário: notificações enviadas do dispositivo de um usuário para o agente, sinalizando uma interação com ele.
  • Eventos da plataforma: notificações sobre mudanças no estado de lançamento do agente e expirações de mensagens enviadas pela plataforma RBM.

Para detalhes sobre eventos de status que o agente envia ao dispositivo do usuário, consulte Enviar eventos.

Para detalhes sobre como processar mensagens do usuário, como texto, arquivos, locais, e outros, consulte Receber mensagens.

Eventos do usuário

Os eventos do usuário são notificações do dispositivo do usuário que informam o status da mensagem ou mudanças na assinatura (ou seja, o usuário cancelou a assinatura ou renovou a assinatura no Google Mensagens).

Para opções completas de formatação e valor, consulte a UserEvent referência.

O usuário recebe a mensagem do agente

Esse evento indica que uma mensagem foi entregue ao dispositivo do usuário.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "DELIVERED",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

O usuário lê a mensagem do agente

Esse evento indica que uma mensagem foi aberta ou reconhecida.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "READ",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

O usuário começa a digitar

Esse evento indica que um usuário está digitando uma resposta.

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

O usuário toca em uma ação sugerida

Quando um usuário toca em uma ação sugerida, o agente recebe um evento com os dados de postback da ação.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234"
  }
}

O usuário cancela a inscrição na conversa

Esse evento indica que o usuário cancelou a inscrição para receber mensagens não essenciais, como promoções, do agente e da empresa que ele representa. Os usuários acionam esse evento cancelando a inscrição na conversa do RBM no Google Mensagens.

Confira um exemplo do payload JSON:

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

Como funciona o cancelamento de inscrição

  • Uma opção de cancelamento de inscrição está sempre disponível no menu de chat. Para agentes promocionais e de uso múltiplo, essa opção também aparece diretamente no chat após um determinado número de mensagens não lidas (as regras específicas variam de acordo com o país).

  • A seleção de cancelamento de inscrição aciona duas ações simultâneas: o Google Mensagens envia uma palavra-chave específica do país (por exemplo, "PARAR") para o agente, e a plataforma RBM envia um evento UNSUBSCRIBE para o webhook.

    A palavra-chave é determinada pelo código de país de duas letras do número de telefone do usuário. A tabela a seguir lista as palavras-chave para cada país compatível.

    País (código do país) Palavra-chave de cancelamento de inscrição
    Estados Unidos (US), Índia (IN), Reino Unido (GB), Alemanha (DE), Países Baixos (NL) STOP
    Espanha (ES) e México (MX) BAJA
    França (FR) STOP
    Brasil (BR) parar

  • Depois que o usuário cancela a inscrição, a conversa permanece na caixa de entrada, a menos que seja denunciada como spam. Nesse caso, ela é movida para a pasta Spam e bloqueados.

  • Para identificar violações de políticas e regras de negócios, o Google monitora padrões de mensagens depois que um usuário cancela a inscrição.

Regras de negócios

  • Como parceiro do RBM que gerencia essa conversa, é sua responsabilidade atender ao pedido de cancelamento de inscrição do usuário.
  • Se você não puder cancelar a inscrição na conversa, envie imediatamente uma mensagem de confirmação com um link direto para o site ou app em que os usuários podem gerenciar as preferências de assinatura.
  • Depois que o usuário cancelar a inscrição, o envio de mensagens não essenciais será proibido.
  • As mensagens essenciais ainda são permitidas. Elas incluem:
    • Autenticações, como senhas únicas (OTPs)
    • Notificações sobre um serviço específico que o usuário solicitou e consentiu
    • Confirmação do pedido de cancelamento de inscrição do usuário, com informações para gerenciar ainda mais as preferências de comunicação

Exemplo

Se um usuário cancelar a inscrição de um agente de companhia aérea cujo caso de uso seja múltiplo, você precisará parar de enviar mensagens de marketing. No entanto, você poderá enviar atualizações de voo se o usuário tiver dado consentimento explícito para receber atualizações desse voo específico.

Motivos de cancelamento de inscrição

Quando um usuário cancela a inscrição do seu agente, ele pode selecionar um motivo nas seguintes opções:

  • Spam
  • Nunca me inscrevi
  • Recebo muitas mensagens
  • Não tenho mais interesse.
  • Outro

Os motivos de cancelamento de inscrição são mostrados na visão geral do Google Analytics para ajudar os parceiros a entender por que os usuários estão cancelando a inscrição.

O usuário renova a inscrição na conversa

Esse evento indica que um usuário quer receber mensagens do seu agente novamente, incluindo conteúdo não essencial, como promoções. Os usuários podem acionar esse evento renovando a inscrição em uma conversa que eles cancelaram anteriormente no Google Mensagens.

Confira um exemplo do payload JSON:

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

Como funciona a renovação da inscrição

  • Uma opção de inscrição, disponível no menu de chat e em um link no chat, permite que os usuários renovem a inscrição em uma conversa que eles cancelaram.

  • A seleção de inscrição aciona duas ações simultâneas: o Google Mensagens envia uma palavra-chave específica do país (por exemplo, "INICIAR") para o agente, e a plataforma RBM envia um evento SUBSCRIBE para o webhook. A palavra-chave específica é determinada pelo código de país de duas letras do número de telefone do usuário. A tabela a seguir lista as palavras-chave para cada país compatível.

    País (código do país) Palavra-chave de inscrição
    Estados Unidos (US), Índia (IN), Reino Unido (GB), Alemanha (DE), Países Baixos (NL) INICIAR
    Espanha (ES) e México (MX) ALTA
    França (FR) Démarrer
    Brasil (BR) começar

Regras de negócios

  • Como parceiro do RBM que gerencia essa conversa, é sua responsabilidade atender ao pedido de renovação da inscrição do usuário.
  • A renovação da inscrição se aplica a todos os tipos de mensagens, incluindo conteúdo não essencial, como promoções.
  • Se um usuário enviar uma mensagem para sua empresa depois de cancelar a inscrição, isso poderá ser considerado um pedido de renovação da inscrição.
  • Se um usuário renovar a inscrição fora do canal de mensagens (por exemplo, no seu site), será sua responsabilidade como parceiro do RBM atualizar o status dele e retomar o envio de mensagens.

Eventos da plataforma

A plataforma RBM envia eventos para notificar o agente sobre mudanças no estado de lançamento ou expirações de mensagens.

O estado de lançamento do agente mudou

A plataforma RBM envia um AgentLaunchEvent para cada mudança no status de lançamento do agente. Por exemplo, quando o estado do agente muda de PENDING para LAUNCHED. O evento é entregue como uma mensagem do Pub/Sub. Para diferenciar esse evento de outros, confira o caminho message.attributes.type para o valor agent_launch_event.

Configuração do webhook

Você pode usar o webhook no nível do parceiro ou do agente para receber essas notificações.

Pré-requisitos

  • Configure o webhook para mensagens do RBM. Esse é um requisito para receber mensagens e eventos do usuário.
  • Para diferenciar entre eventos do usuário e eventos de estado de lançamento do agente, confira o caminho message.attributes.type para o valor agent_launch_event.

Estrutura do payload de eventos

O AgentLaunchEvent é entregue como uma mensagem do Pub/Sub. Confira um exemplo:

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

O campo AgentLaunchEvent.LaunchState no payload do evento indica o novo estado de lançamento do agente. Confira os valores possíveis:

Valor Estado de lançamento do agente Detalhes
PENDING Pendente O pedido foi enviado a uma operadora para análise.
LAUNCHED Lançado As mensagens são permitidas em uma determinada operadora.
REJECTED Rejeitado em uma determinada operadora O motivo da rejeição é especificado no comentário.
SUSPENDED Suspenso em uma determinada operadora O motivo da suspensão é especificado no comentário.
UNLAUNCHED Não lançado A edição é permitida para agentes que não foram lançados de todas as operadoras.

O campo de dados contém um objeto JSON codificado em Base64 com os detalhes do estado de lançamento. Confira um exemplo do JSON decodificado:

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

Mudanças no estado de lançamento iniciadas pela operadora

Essas são transições permitidas que geralmente são processadas pelas operadoras durante o processo de análise e aplicação:

Estado de lançamento antigo Novo estado de lançamento Ação acionadora
PENDING LAUNCHED Aprovar um pedido de lançamento.
PENDING REJECTED Rejeitar um pedido de lançamento.
LAUNCHED SUSPENDED Suspender por motivos de aplicação/administração.
SUSPENDED LAUNCHED Restaurar um agente ao status ativo.
SUSPENDED UNLAUNCHED Encerrar um agente.

Mudanças no estado de lançamento iniciadas pelo parceiro

Essas são transições permitidas que geralmente são processadas por parceiros:

Estado de lançamento antigo Novo estado de lançamento Ação acionadora
UNSPECIFIED PENDING Enviar para análise.
PENDING UNLAUNCHED Cancelar um pedido de lançamento pendente.
UNLAUNCHED PENDING Enviar para análise.
REJECTED PENDING Reenviar para análise.

A mensagem expirou; a revogação foi bem-sucedida

Esse evento indica que o tempo de vida (TTL) da mensagem expirou e a mensagem foi revogada. Esse é um bom gatilho para sua estratégia de mensagens de fallback.

Para opções completas de formatação e valor, consulte a ServerEvent referência.

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

A mensagem expirou; a revogação falhou

Esse evento indica que o TTL da mensagem expirou, mas ela não foi revogada.

Para opções completas de formatação e valor, consulte a ServerEvent referência.

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

A entrega de mensagens não é garantida.

  • Se a mensagem foi entregue, você vai receber um evento DELIVERED no webhook.
  • Se a mensagem não foi entregue, use a API de revogação para enviar um pedido de revogação.

Se a mensagem for sensível ao tempo, como uma OTP ou um alerta de fraude, é melhor enviá-la por um canal alternativo, como SMS, mesmo que isso resulte em mensagens duplicadas para o usuário.

Anterior
Enviar eventos
Avançar
Verificações de capacidade