Os eventos são notificações que seu agente pode enviar e receber. Há três tipos de eventos:
- Gerado pelo servidor: enviado ao seu agente pela plataforma RBM.
- Gerado pelo usuário: Enviado ao seu agente pelo dispositivo do usuário
- Gerada pelo agente: enviada pelo agente ao usuário
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 eventos gerados pelo usuário e eventos de estado de inicialização do agente, verifique o caminho
message.attributes.typepara o valoragent_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.
Estes são 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 lançamento do agente e as ações que os acionam:
| Estado antigo do lançamento | Novo estado de lançamento | Gatilho para mudança |
|---|---|---|
PENDING |
LAUNCHED |
Agente pendente aprovado. |
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.
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 entregue, você vai receber um evento
DELIVEREDno seu webhook. - Se a mensagem não foi entregue, use a API de revogação para enviar uma solicitação de revogação.
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.
Eventos gerados pelo usuário
Assim como acontece com as mensagens do usuário e as verificações de recursos, seu agente recebe eventos do usuário como JSON.
Para opções de formatação e valores, consulte
UserEvent.
O usuário recebe uma mensagem do agente
Esse evento indica que uma mensagem foi entregue.
{
"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.
{
"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
Se um usuário não quiser receber mensagens não essenciais de uma empresa, como promoções, ele poderá 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 representante 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
- 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 após um determinado número de mensagens não lidas. As regras específicas variam de acordo com o 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 Estados Unidos (US), Índia (IN), Reino Unido (GB), Alemanha (DE) 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 uma companhia aérea cujo caso de uso seja de uso múltiplo, você precisará 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 inscrição do seu agente, ele pode selecionar um motivo entre as seguintes opções:
- Não me inscrevi
- Recebo muitas mensagens
- Não tenho mais interesse.
- Spam
- Outro
No momento, os motivos de cancelamento da inscrição não são compartilhados com parceiros ou operadoras.
O usuário se reinscreve na conversa
Os usuários podem reativar uma conversa de que tinham cancelado a inscrição no Google Mensagens.
O evento SUBSCRIBE indica que um usuário quer receber mensagens do seu
agente, incluindo conteúdo não essencial, como promoções. Confira um exemplo do payload JSON:
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "SUBSCRIBE",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}Como funciona
- 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 de INSCRIÇÃO 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 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) 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 uma confirmação 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);
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");
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)
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");
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!'); });
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");
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')
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");