Receber eventos

O 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 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.

Importante: para ajudar os desenvolvedores a fazer a transição para os novos UNSUBSCRIBE e SUBSCRIBE eventos de webhook, o Google Mensagens também está enviando mensagens "PARAR" e "INICIAR" junto com os eventos de webhook. Embora você possa confiar na lógica de PARAR/INICIAR atual por enquanto, recomendamos atualizar sua lógica para processar os UNSUBSCRIBE e SUBSCRIBE eventos, já que eles se tornarão obrigatórios em conformidade com a especificação da GSMA.

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).

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 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 aceito.

País (código do país)	Palavra-chave de cancelamento de inscrição
Estados Unidos (US), Índia (IN), Reino Unido (GB), Alemanha (DE)	PARAR
Espanha (ES), 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 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 não for possível 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 de uso 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 assinatura

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.

Selecionar Inscrever-se 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 aceito.

País (código do país)	Palavra-chave de inscrição
Estados Unidos (US), Índia (IN), Reino Unido (GB), Alemanha (DE)	INICIAR
Espanha (ES), 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 de 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 após 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 de acordo com isso.

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 isso de outros eventos, verifique 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, verifique 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 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 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 normalmente são processadas por parceiros:

Estado de lançamento antigo	Novo estado de lançamento	Ação acionadora
`UNSPECIFIED`	`PENDING`	Enviar para análise.
`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.

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 de cancelamento de inscrição

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

Como funciona a renovação da 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 de eventos

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 bem-sucedida

A mensagem expirou; a revogação falhou

Receber eventos