Eventos

Os eventos são notificações que seu agente pode enviar e receber. Há três tipos de eventos:

Eventos gerados pelo servidor

A plataforma RBM envia eventos para notificar seu agente sobre atualizações no nível do servidor, como expiração de mensagens.

Para opções de formatação e valores, consulte ServerEvent.

O status de lançamento do representante 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 após a aprovação da operadora, você recebe um evento AgentLaunchEvent para indicar a mudança. Esses eventos são enviados para todos os agentes do RBM e para todas as mudanças de estado de lançamento da operadora.

Configuração do webhook

Você pode usar um 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 do usuário e eventos gerados pelo usuário.
  • Para diferenciar entre eventos gerados pelo 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 Agente pendente aprovado.
PENDING REJECTED Agente pendente rejeitado.
LAUNCHED SUSPENDED Agente iniciado 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.

A mensagem expirou e foi revogada. Esse evento seria um bom gatilho para sua estratégia de mensagens de substituição.

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

A mensagem expirou. A revogação falhou.

A mensagem expirou, mas não foi revogada.

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

A entrega da mensagem não é garantida.

Se a mensagem for urgente, como um código 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.

Eventos gerados pelo usuário

Assim como ocorre com mensagens de usuário e verificações de capacidade, seu agente recebe eventos de usuário em formato JSON.

Para opções de formatação e valores, consulteUserEvent.

O usuário recebe uma mensagem do agente

Este evento indica que uma mensagem foi entregue.

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

Usuário lê mensagem do agente

Este 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

Este evento indica que um usuário está digitando.

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

Se um usuário não quiser receber mensagens não essenciais de uma empresa, como promoções, ele pode cancelar a inscrição na conversa do RBM no Google Mensagens.

O evento UNSUBSCRIBE indica que o usuário cancelou a inscrição na conversa com seu agente e a empresa que ele representa. Veja um exemplo do payload JSON:

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

Como funciona

  • Uma opção Cancelar inscrição está sempre disponível no menu de bate-papo. Para agentes promocionais e de uso múltiplo, essa opção também aparece diretamente no chat após um certo 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 Messages envia uma palavra-chave específica do país (por exemplo, "PARAR") para o seu agente e a plataforma RBM envia um evento CANCELAR INSCRIÇÃO para o 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 suportado.

    País (código do país) Palavra-chave para cancelar 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 os padrões de mensagens após um usuário cancelar a assinatura.

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 da solicitação de cancelamento de inscrição do usuário, com informações para gerenciar ainda mais suas 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 é multi-uso, você deve parar 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 assinatura do seu agente, ele pode selecionar um motivo dentre as seguintes opções:

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

Atualmente, os motivos para cancelamento da assinatura não são compartilhados com parceiros ou operadoras.

O usuário se inscreve novamente na conversa.

No Google Mensagens, os usuários podem se reinscrever em uma conversa da qual haviam cancelado a inscrição anteriormente.

O evento SUBSCRIBE indica que um usuário deseja receber mensagens do seu agente, incluindo conteúdo não essencial, como promoções. Aqui está um exemplo da carga útil JSON:

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

Como funciona

  • A opção Inscrever-se, disponível tanto no menu de bate-papo quanto em um link no bate-papo, permite que os usuários se inscrevam novamente em uma conversa da qual haviam cancelado a inscrição.

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

    País (código do país) Inscrever-se
    Estados Unidos (EUA), Í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 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 gerados pelo agente

O agente envia eventos para simular interações humanas e garantir ao usuário que o agente está interagindo com as mensagens dele. Para os usuários, os eventos aparecem como notificações nas conversas.

Para opções de formatação e valores, consulte phones.agentEvents.

O agente envia um evento READ

Para os usuários, esse evento aparece como um recibo de leitura de uma mensagem específica. Ele informa ao usuário que a plataforma RBM entregou a mensagem e que o agente está processando.

O código a seguir envia um evento READ para uma mensagem com um messageId correspondente.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'READ',
  'messageId': 'MESSAGE_ID'
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage('+12223334444', messageId);
 Este código é um trecho de um agente de amostra do RBM.

Java

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage(messageId, "+12223334444");
 Este código é um trecho de um agente de amostra do RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that message_id was read
rbm_service.send_read_event('+12223334444', message_id)
 Este código é um trecho de um agente de amostra do RBM.

C#

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that messageId has been read
rbmApiHelper.SendReadMessage(messageId, "+12223334444");
 Este código é um trecho de um agente de amostra do RBM.

O agente envia um evento IS_TYPING

Para os usuários, esse evento aparece como um indicador de digitação e informa que seu agente está escrevendo uma mensagem. O indicador de digitação expira após um curto período (aproximadamente 20 segundos) ou quando o dispositivo do usuário recebe uma nova mensagem do seu agente. Seu agente pode enviar vários eventos IS_TYPING para redefinir o timer de expiração do indicador de digitação.

O código a seguir envia um evento IS_TYPING.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'IS_TYPING',
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage('+12223334444', function() {
    console.log('Typing event sent!');
});
 Este código é um trecho de um agente de amostra do RBM.

Java

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage("+12223334444");
 Este código é um trecho de um agente de amostra do RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that the agent is typing
rbm_service.send_is_typing_event('+12223334444')
Este código é um trecho de umagente de amostra RBM.

C#

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that the agent is typing
rbmApiHelper.SendIsTypingMessage(messageId, "+12223334444");
 Este código é um trecho de um agente de amostra do RBM.
Anterior
Receber mensagens
Avançar
Verificações de capacidade