Crea una impresionante aplicación RCS Reminder con Node SDK y Vonage

Los servicios de comunicación enriquecida (RCS) no solo llegarán a iOS 18, sino también a Vonage. A partir de principios de otoño de 2024, podrás habilitar el envío de RCS a través de la Messages API. RCS es tan fácil de usar como el SDK de Vonage Node y admite tarjetas enriquecidas, carruseles y respuestas sugeridas desde el primer momento.

Rich Communications Services (RCS) es un protocolo de mensajería avanzada que mejora los tradicionales SMS y MMS con funciones como mensajería en tiempo real, intercambio de imágenes y Video y transferencia de archivos. Admite elementos interactivos como chats de grupo, notificaciones de escritura y actualizaciones del estado de los mensajes. A diferencia de los SMS, que utilizan redes celulares, RCS funciona a través de datos celulares y Wi-Fi, ofreciendo una experiencia de mensajería más versátil y moderna, similar a la de aplicaciones populares como WhatsApp y Facebook Messenger. Consulte este enlace para obtener más información sobre cómo funciona RCS con Vonage.

Para mostrar cómo puedes usar RCS con la API de mensajería de Vonage, crearemos una simple aplicación que nos recuerde beber agua. El resultado será algo parecido a esto:

Drink Water Reminder

Requisitos previos

• Necesitará una cuenta de desarrollador de Vonage

• Necesitará un servicio de túnel API. Yo utilizaré ngrok. Más información sobre cómo usar ngrok para realizar pruebas.

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Registrar un agente RCS con Google Business Messaging

Necesitarás un agente RCS vinculado a tu cuenta de Vonage para enviar y recibir mensajes RCS a través de Messages API de Vonage. Para configurar el agente, comunícate con el soporte de Vonage o con tu administrador de cuenta para comenzar. Una vez que el agente esté agregado a tu Account, deberías verlo en "Cuentas externas" en tu panel.

Developer Dashboard

Crear una aplicación de Vonage

El siguiente paso es crear una nueva aplicación de Vonage. Esto generará credenciales y definirá configuraciones específicas para nuestra aplicación de recordatorio RCS, como las URL de webhook. Sigue estos pasos para crear y configurar tu aplicación:

1. Haga clic en "Generar una nueva Application".

2. Dale un nombre.

3. Haga clic en "Generar clave privada y pública" (la clave privada se descargará en su ordenador; guárdela para más tarde).

4. Activar la función "Mensajes".

   • La URL para los ganchos dependerá de lo que obtenga de ngrok. Pero la ruta debería ser /entrada y /estado respectivamente.

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

Ahora necesitamos vincular nuestro Agente RCS a la aplicación de Vonage.

Poner en marcha el proyecto

Crea un nuevo directorio para el proyecto e inicialízalo con npm.

npm init -y

A continuación, instalaremos los paquetes que necesitemos.

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

(Nota: Algunos de los paquetes vonage se incluyen con @vonage/server-sdk, pero siempre es una buena idea estar implícito con los paquetes requeridos)

He aquí una rápida explicación de lo que ofrece cada paquete:

• @vonage/server-sdk, @vonage/messages, @vonage/auth, y @vonage/jwt se utilizarán para enviar y recibir mensajes

• cron es un paquete utilizado para ejecutar código en un horario

• dotenv carga dinámicamente .env ,

  que se utilizará para configurar nuestra aplicación

• express se utiliza como servidor web para procesar nuestros mensajes

• jsonwebtoken se utilizará para validar tokens JWT

• uuid crea identificadores únicos

Copie la private.key en nuestra carpeta de aplicaciones y, a continuación, cree un archivo .env con lo siguiente:

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>

Cree un archivo llamado servidor.js y arranca usando esta plantilla 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,
  });
});

A continuación, actualice package.json para tener un script de inicio:

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

Ahora puede ejecutar npm run start y ngrok, luego navega a la URL de ngrok. Deberías ver "Hello World" en formato JSON. Eso significa que hemos arrancado Express con éxito.

Cómo enviar mensajes recordatorios

Ahora, enviaremos el recordatorio. Programaremos una función para que se ejecute a intervalos regulares utilizando la función cron . Las expresiones de cron están fuera del alcance de este artículo, pero si quieres jugar con la frecuencia con la que se envía el recordatorio, te sugiero que utilices Crontab.guru para ayudar a construir la expresión.

Cómo configurar el SDK de Vonage Node

Primero vamos a configurar el SDK para enviar mensajes. Tendrás que introducir el ID de la aplicación y la clave privada. Normalmente, puedes pasar la ruta a la clave privada, y el SDK la leerá. Sin embargo, necesitaremos la clave privada en el siguiente paso, así que leeremos el archivo y lo almacenaremos en una variable en su lugar.

// 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);

Cómo enviar un recordatorio de tarjeta enriquecida

Generaremos nuestro propio token JWT, que luego puede usarse para el webhook de entrada para asegurarnos de recibir mensajes de Vonage, pero también porque tienen un vencimiento incorporado. Queremos darle al usuario un tiempo determinado para responder. Al utilizar un JWT, cumplimos ambos requisitos.

En primer lugar, registraremos la tarea cron. Lo ejecutaremos cada cinco minutos para comprobar si el destinatario ha reconocido que se ha tomado un vaso de agua.

// 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 continuación, escribiremos algunas funciones para comprobar si necesitamos enviar un mensaje. Almacenamos el recordatorio en un array con el token generado a partir del envío del mensaje.

// 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}]);
};

Ahora, a enviar el mensaje. La mensajería RCS proporciona muchos tipos de mensajes diferentes, incluyendo Tarjetas enriquecidas. Estas tarjetas contienen todo el contenido que el cliente necesita para procesar el mensaje. Dentro del canal RCS de la API de Messages de Vonage, las Rich Cards se envían usando el tipo de mensaje "personalizado" con un botón para responder con "SÍ". Creamos un token y enviamos el mensaje.

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);
	});
  }
};

Ahora, cuando ejecutemos npm run start después de unos cinco minutos, nuestro teléfono recibe un mensaje preguntando si hemos bebido agua.

Acuse de recibo del mensaje

Entonces, ¿cómo evitamos que el mensaje vuelva a salir? Bueno, aquí es donde entra el Webhook. Cuando el usuario presiona "Sí", el cliente responderá al agente RCS, que luego se reenviará a Vonage. Luego llamamos a un webhook con los datos adjuntos para que puedas procesarlos. El mensaje se verá así:

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

Tenga en cuenta que de y a se han intercambiado desde que esto vino del teléfono. Usando este payload, podemos encontrar nuestro recordatorio y eliminarlo. (También estamos validando el token firmado por nosotros, que no puede ser fácilmente 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});
}));

¡Y ahí lo tienes! Enviar y recibir mensajes RCS es una brisa con el Messages API. Ahora, usted puede construir ricas aplicaciones de mensajería con unas pocas líneas de código. Es mejor mantener estos mensajes conversacionales en lugar de transaccionales. De esta forma, puedes mejorar la experiencia de tus usuarios guiándoles en lugar de informándoles.

Próximos pasos

RCS está preparado para mejorar las experiencias de mensajería con funciones avanzadas y posibilidades de integración. Con Messages API de Vonage, puedes incorporar fácilmente RCS en tus aplicaciones, brindando mensajería en tiempo real y elementos interactivos enriquecidos a tus usuarios. A partir de principios del otoño de 2024, Vonage simplificará la habilitación de RCS a través de su plataforma. Esto abre interesantes oportunidades para crear soluciones de mensajería atractivas y repletas de funciones.

Para empezar, consulte la Documentación de mensajes personalizados de RCS para obtener más información sobre la integración de otros tipos de mensajes RCS con Vonage. Para una interactividad de RCS más avanzada, también puedes explorar:

• Cómo enviar y recibir respuestas sugeridas RCS con Node.js para permitir a los usuarios interactuar rápidamente con respuestas sugeridas con botones.

• Cómo enviar RCS Rich Card Carousels con Node.js para mostrar múltiples recordatorios, promociones u opciones en un formato deslizable.

También puede consultar este repositorio GitHub para ver una versión completa de este código.

Únete a la conversación en nuestro Slack de la comunidad de Vonage o envíanos un mensaje en X, antes conocido como Twitter.