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 de acordo com a origem:

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

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

Eventos do usuário

Os eventos do usuário são notificações do dispositivo dele que informam o status da mensagem ou mudanças na assinatura (por exemplo, o usuário cancelou a inscrição ou assinou de novo no Google Mensagens).

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

O usuário recebe uma 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 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 envia uma mensagem de texto

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "text": "Hi",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

O usuário envia um arquivo

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "userFile": {
    "payload": {
      "mimeType": "image/gif",
      "fileSizeBytes": 127806,
      "fileUri": "https://storage.googleapis.com/copper_test/77ddb795-24ad-4607-96ae-b08b4d86406a/d2dcc67ab888d34ee272899c020b13402856f81597228322079eb007e8c9",
      "fileName": "4_animated.gif"
    }
  },
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

O usuário toca em uma resposta sugerida

Quando um usuário toca em uma resposta sugerida, seu agente recebe um evento com os dados de postback e o texto da resposta.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234",
    "text": "Hello there!"
  }
}

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.

Confira um exemplo do payload JSON:

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

Como funciona o cancelamento da inscrição

  • A opção Cancelar inscrição está sempre disponível no menu do chat. Para agentes promocionais e de uso múltiplo, essa opção também aparece diretamente no chat depois de um certo número de mensagens não lidas (as regras específicas variam de país).

  • Ao selecionar Cancelar inscrição, duas ações simultâneas são acionadas: 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 para cada país disponível.

    País (código do país) Palavra-chave para cancelamento de inscrição
    Alemanha (DE), Estados Unidos (US), Índia (IN), Reino Unido (GB) PARAR
    Espanha (ES), México (MX) BAJA
    França (FR) PARAR
    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 conversas 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 o parceiro do RBM que gerencia essa conversa, é sua responsabilidade atender ao pedido de cancelamento da 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 inscrição.
  • Depois que o usuário cancela a inscrição, o envio de mensagens não essenciais é proibido.
  • Mensagens essenciais ainda são permitidas. Isso inclui:
    • 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 da 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, pare de enviar mensagens de marketing. 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 de cancelamento de inscrição

Quando um usuário cancela a inscrição do seu agente, ele pode selecionar um motivo entre as 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 Analytics para ajudar os parceiros a entender por que os usuários estão cancelando a inscrição.

O usuário se reinscreve 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 ao renovar a inscrição em uma conversa que tinham cancelado no Google Mensagens.

Confira um exemplo do payload JSON:

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

Como funciona a nova assinatura

  • A opção Inscrever-se, disponível no menu de chat e em um link na conversa, permite que os usuários se inscrevam novamente em uma conversa de que tinham cancelado a inscrição.

  • Ao selecionar Inscrever-se, duas ações simultâneas são acionadas: o Google Mensagens envia uma palavra-chave específica do país (por exemplo, "INICIAR") para seu agente, e a plataforma RBM envia um evento SUBSCRIBE para seu webhook. A palavra-chave específica é determinada pelo código do 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 inscrição
    Alemanha (DE), Estados Unidos (US), Índia (IN), Reino Unido (GB) INICIAR
    Espanha (ES), México (MX) ALTA
    França (FR) Démarrer
    Brasil (BR) começar

Regras de negócios

  • Como o parceiro do RBM que gerencia essa conversa, é sua responsabilidade atender ao pedido do usuário para se inscrever novamente.
  • A nova assinatura 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 reinscrição.
  • Se um usuário assinar novamente fora do canal de mensagens (por exemplo, no seu site), é 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 seu agente sobre mudanças no estado de lançamento ou expiração 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 seu agente. Por exemplo, quando o estado do seu 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

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

Pré-requisitos

  • Configure seu 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 inicialização do agente, verifique o caminho message.attributes.type para o valor agent_launch_event.

Estrutura do payload de 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. Confira os valores possíveis:

Valor Estado de lançamento do agente Detalhes
UNLAUNCHED Não lançado A edição é permitida.
PENDING Pendente A solicitação foi enviada a uma transportadora para análise.
LAUNCHED Lançado As mensagens são permitidas em uma determinada operadora.
REJECTED Rejeitado em uma determinada transportadora O motivo da rejeição é especificado no comentário.
SUSPENDED Suspensa em uma determinada operadora O motivo da suspensão é especificado no comentário.

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

A tabela a seguir mostra os estados de inicialização do agente e as ações que os acionam:

Estado de lançamento antigo Novo estado de lançamento Gatilho para mudança
PENDING LAUNCHED Aprovação do agente pendente.
PENDING REJECTED Agente pendente rejeitado.
LAUNCHED SUSPENDED O agente iniciado foi suspenso.
SUSPENDED LAUNCHED O representante suspenso foi reativado.
SUSPENDED TERMINATED O agente suspenso foi encerrado.
TERMINATED LAUNCHED O agente encerrado foi iniciado.

A mensagem expirou. A revogação foi concluída.

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

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

{
  "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 com êxito.

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

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

A entrega da mensagem não é garantida.

Se a mensagem for sensível ao tempo, como um OTP ou um alerta de fraude, é melhor enviar a mensagem 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