Crie um aplicativo de lembretes RCS incrível com o Node SDK e a Vonage

Os Serviços de Comunicação Avançada (RCS) estão chegando não apenas ao iOS 18, mas também à Vonage. A partir do início do outono de 2024, você poderá habilitar o envio de RCS por meio da Messages API. O RCS é tão fácil de usar quanto o SDK do Vonage Node e oferece suporte a cartões avançados, carrosséis e respostas sugeridas logo de cara.

O Rich Communications Services (RCS) é um protocolo avançado de mensagens que aprimora os SMS e MMS tradicionais com recursos como mensagens em tempo real, compartilhamento de imagens e Video e transferência de arquivos. Ele oferece suporte a elementos interativos, como conversas em grupo, notificações de digitação e atualizações de status das mensagens. Ao contrário do SMS, que utiliza redes de celular, o RCS funciona por meio de dados móveis e Wi-Fi, oferecendo uma experiência de mensagens mais versátil e moderna, semelhante à de aplicativos populares como o WhatsApp e o Facebook Messenger. Confira este link para obter mais informações sobre como o RCS funciona com a Vonage.

Para mostrar como você pode usar o RCS com a Messages API da Vonage, vamos criar um aplicativo simples para nos lembrar de beber água. O resultado ficará mais ou menos assim:

Drink Water Reminder

Pré-requisitos

• Você precisará de uma account de desenvolvedor da Vonage 

• Você precisará de um serviço de tunelamento de API. Vou usar o ngrok. Saiba mais sobre como usar o ngrok para testes. 

Registrar um agente RCS no Google Business Messaging

Você precisará de um agente RCS vinculado à sua conta da Vonage para enviar e receber mensagens RCS por meio da Messages API da Vonage. Para configurar o agente, entre em contato com o Suporte da Vonage ou com seu gerente de conta para dar início ao processo. Assim que o agente for adicionado à sua conta, você deverá vê-lo listado na seção “Contas externas” do seu painel de controle.

Developer Dashboard

Criar uma aplicação da Vonage

O próximo passo é criar um novo aplicativo da Vonage. Isso gerará credenciais e definirá configurações específicas para nosso aplicativo de lembretes RCS, como URLs de webhooks. Siga estas etapas para criar e configurar seu aplicativo:

1. Clique em “Gerar uma nova Application”.

2. Dê um nome a isso.

3. Clique em “Gerar chave privada e pública” (a chave privada será baixada para o seu computador; salve-a para usar mais tarde)

4. Ative o recurso “Mensagens”. 

   • A URL dos hooks dependerá do que você obtiver do ngrok. Mas o caminho deve ser /inbound e /status, respectivamente.

A screenshot of the “Create Application” form in the developer dashboard

Agora precisamos vincular nosso RCS Agent ao aplicativo da Vonage.

Iniciar o projeto

Crie um novo diretório para o projeto e inicialize-o com o npm.

npm init -y

Em seguida, instalaremos os pacotes de que precisamos.

npm install @vonage/jwt @vonage/auth @vonage/messages @vonage/server-sdk @vonage/jwt cron dotenv express jsonwebtoken uuid

(Observação: Alguns dos pacotes da Vonage estão incluídos no @vonage/server-sdk, mas é sempre uma boa ideia ser explícito quanto aos pacotes necessários)

Aqui está uma breve explicação sobre o que cada pacote oferece:

• @vonage/server-sdk, @vonage/messages, @vonage/auth, e @vonage/jwt serão usados para enviar e receber mensagens

• cron é um pacote usado para executar código de forma programada 

• dotenv carrega dinamicamente arquivos .env ,

  que será usado para configurar nosso aplicativo

• express é usado como servidor web para processar nossas mensagens 

• jsonwebtoken será usado para validar tokens JWT 

• uuid cria identificadores únicos 

Copie o arquivo private.key para a pasta do nosso aplicativo e, em seguida, crie um arquivo arquivo .env com o seguinte conteúdo:

VONAGE_APPLICATION_ID=<your application id>
VONAGE_PRIVATE_KEY_FILE=<full path to the private key>
VONAGE_BRAND_NAME=<id of your RBM account>
REMINDER_NUMBER=<your phone number or number you want to send the reminder to>

Crie um arquivo chamado server.js e inicie o projeto usando este modelo do Express.

const Express = require('express');
require('dotenv').config();

const app = new Express();
const port = process.env.PORT || 3000;

// Catches async functions for express
const catchAsync = (fn) => (req, res, next) => {
  fn(req, res, next).catch(next);
};

app.use(Express.json());

// Hello World
app.all('/', catchAsync(async (req, res) => {
  console.log('Hello World', req.body);
  res.status(200).json({hello: 'World'});
}));

// Setup a 404 handler
app.all('*', (req, res) => {
  res.status(404).json({
	status: 404,
	title: 'Not Found',
  });
});

// Setup an error handler
app.use((err, req, res, next) => {
  res.status(500).json({
	status: 500,
	title: 'Internal Server Error',
	detail: err.message,
  });
});

Em seguida, atualize o arquivo package.json para incluir um script de inicialização:

{
  // ...
  "scripts": {
    "start": "node server.js"
  }
}

Agora você pode executar npm run start e o ngrok, e, em seguida, acessar a URL do ngrok. Você deverá ver “Hello World” no formato JSON. Isso significa que inicializamos o Express com sucesso.

Como enviar mensagens de lembrete

Agora, vamos enviar o lembrete. Vamos programar uma função para ser executada em intervalos regulares usando o pacote cron . As expressões do cron estão fora do escopo deste post, mas se você quiser testar a frequência com que o lembrete é enviado, sugiro o Crontab.guru para ajudar a criar a expressão. 

Como configurar o SDK do Vonage Node

Vamos, primeiro, configurar o SDK para enviar mensagens. Você precisará inserir o ID do aplicativo e a chave privada. Normalmente, é possível indicar o caminho para a chave privada, e o SDK a lerá. No entanto, precisaremos da chave privada na próxima etapa; por isso, vamos ler o arquivo e armazená-la em uma variável.

// Add this to the top of the file
const { Auth } = require('@vonage/auth');
const { Vonage } = require('@vonage/server-sdk');
const { readFileSync } = require('fs');

// This can go anywhere else
const key = readFileSync(process.env.VONAGE_PRIVATE_KEY_FILE).toString();

const auth = new Auth({
  applicationId: process.env.VONAGE_APPLICATION_ID,
  privateKey: key,
});

const vonage = new Vonage(auth);

Como enviar um lembrete com cartão interativo

Vamos gerar nosso próprio token JWT, que poderá ser usado no webhook de entrada para garantir que recebamos as mensagens da Vonage, mas também porque ele possui um prazo de validade embutido. Queremos dar ao usuário um determinado tempo para responder. Ao usar um JWT, atendemos a ambos os requisitos.

Primeiro, vamos configurar a tarefa cron. Vamos executá-la a cada cinco minutos para verificar se o destinatário confirmou que tomou um copo d’água.

// Add to top of the file
const { CronJob } = require('cron');

// Setup the cronjob
const job = new CronJob(
  // Run every 5 minutes
  '5 * * * * *',
  () => {
    sendReminder(reminderNumber);
  },
  null, // Data to pass into the cron function
  true, // Automatically start
  process.env.TZ || 'America/New_York', // The timezone
);

A seguir, vamos escrever algumas funções para verificar se precisamos enviar uma mensagem. Armazenamos o lembrete em um array junto com o token gerado ao enviar a mensagem. 

// Storage for sent reminders
const reminders = [];

// Check to see if we have sent a reminder 
const checkForReminders = (number) => {
  const search = reminders.find((reminder) => reminder.number === number);
  if (!search) {
	console.log('No reminder found');
	return false;
  }

  const { token } = search;
  console.log('Checking token', token);
  return validateToken(token);
};

// Send the reminder
const sendReminder = async (number) => {
  console.log('Checking for reminders');

  if (checkForReminders(number)) {
	console.log('Reminder already sent');
	return;
  }

  const token = await sendMessage(number, (job.nextDate() / 1000) + 10000);
  reminders.push([{number, token}]);
};

Agora, vamos ao envio da mensagem. O sistema de mensagens RCS oferece diversos tipos de mensagens, incluindo Rich Cards. Esses cartões contêm todo o conteúdo necessário para que o cliente exiba a mensagem. No canal RCS da Messages API, os Rich Cards são enviados usando o tipo de mensagem “custom” com um botão para responder com “SIM”. Criamos um token e enviamos a mensagem junto com ele. 

const sendMessage = async (number, exp) => {
  console.log('Sending message to', number);
  const token = tokenGenerate(
    auth.applicationId,
    auth.privateKey,
    {
      reminderId: uuid(),
      ...(exp ? {exp: exp} : {}),
    },
  );

  const message = new RCSCustom({
    to: number,
    from: process.env.VONAGE_BRAND_NAME,
    custom: {
  	contentMessage: {
    	  richCard: {
           standaloneCard: {
           cardOrientation: 'VERTICAL',
           cardContent: {
              title: 'Drink Water Reminder',
              description: 'Did you drink water today?',
              media: {
                height: 'SHORT',
                contentInfo: {
// Add a 
                  fileUrl: 'https://as1.ftcdn.net/jpg/02/22/48/50/220_F_222485075_uAeqmITGagEGdy9D4nWVou0a6dj6EuUz.jpg',
                },
              },
              suggestions: [
                {
                  reply: {
                    text: 'Yes',
                    postbackData: token,
                  },
                },
              ],
            },
          },
    	  },
       },
    },
  });

  console.log('Sending reminder', message);
  try {
	const res = await vonage.messages.send(message);
	console.log('Message sent', res);
	return token;
  } catch (err) {
	console.error('Error sending message');
	err.response.text().then((text) => {
  	console.log(text);
	});
  }
};

Agora, quando executarmos npm run start , após cerca de cinco minutos, nosso celular recebe uma mensagem perguntando se bebemos água.

Confirmando o recebimento da mensagem

Então, como evitamos que a mensagem seja enviada novamente? Bem, é aí que entra o Webhook. Quando o usuário clica em “Sim”, o cliente responde ao RCS Agent, e essa resposta é então encaminhada para a Vonage. Em seguida, chamamos um webhook com os dados anexados para que você possa processá-los. A mensagem terá a seguinte aparência:

{
   "channel": "rcs",
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "Vonage",
   "from": "<Number>",
   "timestamp": "2020-01-01T14:00:00.000Z",
   "context_status": "none",
   "message_type": "reply",
   "reply": {
  	"payload": "<The JWT Token>",
  	"text": "Yes"
   }
}

Observe que a partir de e para trocaram de lugar, já que isso veio do celular. Usando essa carga útil, podemos localizar nosso lembrete e removê-lo. (Também estamos validando o token assinado por nós, que não pode ser facilmente falsificado).

app.all('/inbound', catchAsync(async (req, res) => {
  console.log('Inbound', req.body);

  const {channel, message_type, reply, from} = req.body;
  if (channel !== 'rcs') {
	console.log('Not RCS');
	res.status(200).json({ok: true});
	return;
  }

  if (message_type !== 'reply') {
	console.log('Not reply');
	res.status(200).json({ok: true});
	return;
  }

  const { id } = reply|| {};

  console.log('Id', id);

  if (!id) {
	console.log('No id');
	res.status(200).json({ok: true});
	return;
  }

  if (!validateToken(id)) {
	console.log('Invalid id');
	res.status(200).json({ok: true});
	return;
  }

  const index = reminders.findIndex((reminder) => reminder.number === from);
  reminders.splice(index, 1);
  console.log('Reminder removed', reminders);

  res.status(200).json({ok: true});
}));

E pronto! Enviar e receber mensagens RCS é muito fácil com a Messages API. Agora, você pode criar aplicativos de mensagens avançados com apenas algumas linhas de código. É melhor que essas mensagens sejam de caráter conversacional, em vez de transacional. Dessa forma, você pode melhorar a experiência dos usuários, orientando-os em vez de apenas informá-los.

Próximos passos

O RCS está pronto para aprimorar as experiências de mensagens com recursos avançados e possibilidades de integração. Com a Messages API da Vonage, você pode incorporar facilmente o RCS aos seus aplicativos, oferecendo mensagens em tempo real e elementos interativos avançados aos seus usuários. A partir do início do outono de 2024, a Vonage simplificará a ativação do RCS por meio de sua plataforma. Isso abre oportunidades empolgantes para criar soluções de mensagens envolventes e repletas de recursos.

Para começar, confira a Documentação sobre mensagens personalizadas do RCS para obter mais informações sobre como integrar outros tipos de mensagens RCS com a Vonage. Para uma interatividade RCS mais avançada, você também pode explorar:

• Como enviar e receber respostas sugeridas do RCS com o Node.js para permitir que os usuários interajam rapidamente com as respostas sugeridas por botões.

• Como enviar carrosséis de cartões RCS com Node.js para exibir vários lembretes, promoções ou opções em um formato que permite deslizar o dedo.

Você também pode conferir este repositório do GitHub para ver uma versão completa e funcional desse código.

Participe da conversa na nossa Slack da Comunidade Vonage ou envie-nos uma mensagem no X, antes conhecido como Twitter.