O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Receber eventos

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

Esses eventos são categorizados pela origem:

Eventos do usuário: notificações enviadas do dispositivo de um usuário para seu 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 os eventos de status que seu agente envia ao dispositivo do usuário, consulte Enviar eventos.

Para saber como lidar com 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 inscrição ou renovou a assinatura no Google Mensagens).

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

O usuário recebe a mensagem do agente

Este 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 confirmada.

{
  "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, seu 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 seu agente e da empresa que ele representa. Os usuários acionam esse evento ao cancelar a inscrição na conversa do RBM no Google Mensagens.

Importante: para ajudar os desenvolvedores na transição para os novos eventos de webhook UNSUBSCRIBE e SUBSCRIBE, o Google Mensagens também está enviando mensagens "STOP" e "START" com os eventos de webhook. Embora você possa usar sua lógica STOP/START atual por enquanto, recomendamos que você a atualize para processar os eventos UNSUBSCRIBE e SUBSCRIBE, já que eles vão se tornar obrigatórios para obedecer à especificação da GSMA.

Veja um exemplo do payload JSON:

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

Como funciona o cancelamento de inscrição

A opção Cancelar inscrição está sempre disponível no menu de chat. Para agentes promocionais e multiuso, 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).

Selecionar Cancelar inscrição aciona duas ações simultâneas: o Google Mensagens envia uma palavra-chave específica do país (por exemplo, "PARAR") para seu agente, e a plataforma RBM envia um evento UNSUBSCRIBE para seu 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 de cada país aceito.

País (código do país)	Palavra-chave de cancelamento de inscrição
Alemanha (DE), Estados Unidos (US), Índia (IN), Países Baixos (NL) e Reino Unido (GB)	PARAR
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 bloqueadas.
Para identificar violações de políticas e regras de negócios, o Google monitora os 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 à solicitação do usuário para cancelar a inscrição.
Se não for possível cancelar a inscrição na conversa, você precisará enviar 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 inscrição.
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. São eles:
- Autenticações, como senhas únicas (OTPs)
- Notificações sobre um serviço específico que o usuário solicitou e autorizou
- Confirmação do pedido de cancelamento de inscrição do usuário, com informações para gerenciar 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 é multiuso, você precisará parar de enviar mensagens publicitárias. No entanto, você pode enviar atualizações de voo se o usuário tiver dado consentimento explícito para receber atualizações sobre esse voo específico.

Motivos do cancelamento de inscrição

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

Recebo muitas mensagens
Nunca me inscrevi
Não tenho mais interesse
Parece ser um golpe
Outro

Para reduzir o viés de seleção, as quatro primeiras opções são mostradas em uma ordem aleatória para cada usuário. Essa ordem permanece consistente nas visitas do usuário, e Outros permanece fixo na parte de baixo.

Os motivos do cancelamento são agregados e mostrados na Visão geral do Analytics para ajudar você a entender por que os usuários estão cancelando a inscrição.

O usuário renova a assinatura da 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 ao renovar a inscrição em uma conversa que cancelaram anteriormente no Google Mensagens.

Veja um exemplo do payload JSON:

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

Como funciona a renovação de assinatura

A opção Fazer inscrição, disponível no menu do chat e em um link na conversa, permite que os usuários se inscrevam novamente em uma conversa que haviam cancelado.

Selecionar Inscrever-se aciona duas ações simultâneas: o Google Mensagens envia uma palavra-chave específica do país (por exemplo, "START") para seu agente, e a plataforma RBM envia um evento SUBSCRIBE para seu 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 aceito.

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

Regras de negócios

Como parceiro de RBM que gerencia essa conversa, é sua responsabilidade atender à solicitação do usuário para renovar a assinatura.
A renovação da assinatura se aplica a todos os tipos de mensagem, 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.
Se um usuário renovar a assinatura fora do canal de mensagens (por exemplo, no seu site), será sua responsabilidade como parceiro de 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, verifique o caminho message.attributes.type para o valor agent_launch_event.

Configuração do webhook

Use o webhook no nível do parceiro ou do agente para receber essas notificações.

Pré-requisitos

Configure seu webhook para mensagens RBM (este é um requisito para receber mensagens e eventos do usuário).
Para diferenciar entre eventos do usuário e eventos de estado de inicialização do agente, verifique o caminho message.attributes.type para o valor agent_launch_event.

Estrutura do payload do evento

O AgentLaunchEvent é entregue como uma mensagem do Pub/Sub.

Veja 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 inicialização do agente. Estes são os valores possíveis:

Valor	Estado de lançamento do agente	Detalhes
`PENDING`	Pendente	A solicitação foi enviada 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 tiveram o lançamento cancelado em todas as operadoras.

O campo de dados contém um objeto JSON codificado em Base64 com os detalhes do estado de lançamento. Veja 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

Estas são as transições permitidas que normalmente 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 restrição/administração.
`SUSPENDED`	`LAUNCHED`	Restaure um agente para o status ativo.
`SUSPENDED`	`UNLAUNCHED`	Desativar um agente.
`REJECTED`	`LAUNCHED`	Aprovar um pedido de lançamento que foi recusado.

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

Estas são as transições permitidas que normalmente são processadas pelos parceiros:

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

A mensagem expirou; a revogação foi concluída

Este evento indica que o time to live (TTL) da mensagem expirou e ela foi revogada. Esse é um bom gatilho para sua estratégia de mensagens de fallback.

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

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

A mensagem expirou. Falha na revogação

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

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

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

A entrega da mensagem não é garantida.

Se a mensagem tiver sido entregue, você vai receber um evento DELIVERED no seu webhook.
Se a mensagem não tiver sido entregue, use a API de revogação para enviar uma solicitação de revogação.

Se a mensagem for urgente, 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.

Enviar eventos

Avançar

Verificações de capacidade

Receber eventos Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Eventos do usuário

O usuário recebe a mensagem do agente

O usuário lê a mensagem do agente

O usuário começa a digitar

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

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

Como funciona o cancelamento de inscrição

Regras de negócios

Exemplo

Motivos do cancelamento de inscrição

O usuário renova a assinatura da conversa

Como funciona a renovação de assinatura

Regras de negócios

Eventos da plataforma

O estado de lançamento do agente mudou

Configuração do webhook

Pré-requisitos

Estrutura do payload do evento

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

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

A mensagem expirou; a revogação foi concluída

A mensagem expirou. Falha na revogação

Receber eventos