
Compartir:
Benjamin Aronov es desarrollador de Vonage. Es un constructor de comunidades con experiencia en Ruby on Rails. Benjamin disfruta de las playas de Tel Aviv, a la que llama hogar. Su base en Tel Aviv le permite conocer y aprender de algunos de los mejores fundadores de startups del mundo. Fuera de la tecnología, a Benjamin le encanta viajar por el mundo en busca del perfecto pain au chocolat.
Crea una experiencia RCS interactiva en tiempo real con Node.js y Vonage
Tiempo de lectura: 7 minutos
Los servicios de comunicación enriquecidos (RCS) está cambiando la forma en que las marcas se relacionan con sus seguidores y clientes. Tanto si organiza un acontecimiento deportivo mundial, un festival de música o simplemente desea establecer conversaciones más interactivas y enriquecedoras, RCS ofrece innovadoras funciones de mensajería para mantener el interés de su público.
En este tutorial, combinaremos RCS respuestas sugeridas, tarjetas ricas independientesy carruseles de tarjetas enriquecidas en un viaje de usuario único y perfecto que puedes adaptar para deportes, música o cualquier experiencia de usuario en tiempo real. Todo usando la Messages API¡!
>> TL;DR: Ver el proyecto completo en GitHub
¿Por qué crear experiencias interactivas en tiempo real?
RCS te permite ir mucho más allá de los SMS. Con rich media, botones interactivos y feedback en tiempo real, puedes:
Aumentar el compromiso y las conversiones
Ofrezca contenidos personalizados al instante
Cree experiencias de marca memorables dentro de la aplicación de mensajería predeterminada del usuario.
Hoy crearás una aplicación que guiará a los usuarios a través de una experiencia dinámica de varios pasos. Este ejemplo es perfecto para eventos en directo, votaciones de fans u ofertas exclusivas.
Nuestra misión: Del hombre del partido al merchandising
Así es como funciona el recorrido del usuario:
El usuario recibe: "¿Quién ganará?" (Brasil, Alemania, Empate)
El usuario toca Brasil → recibe una tarjeta de votación "Hombre del partido" (Ronaldinho, Ronaldo, Pelé).
El usuario toca Ronaldinho → recibe un carrusel de artículos de Ronaldinho.
Puede ampliar fácilmente este flujo para eventos musicales, lanzamientos de productos o cualquier experiencia en tiempo real.
Requisitos previos
Antes de empezar, necesitarás:
Node.js instalado en su máquina
ngrok instalado para exponer su servidor local
Una cuenta API de Vonage
Un agente registrado de RCS Business Messaging (RBM)
Un teléfono compatible con RCS para las pruebas
>> Nota: RCS a través de Vonage requiere una cuenta administrada. Comunícate con tu administrador de cuenta de Vonage para obtener acceso al modo para desarrolladores. Por favor, comunícate con nuestro equipo de ventas si no tienes una cuenta administrada.
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.
Configuración del proyecto
Tu aplicación Node será relativamente simple, con un poco de organización modular para mantener el código limpio y a la altura de las mejores prácticas modernas. Pero antes de crear tu aplicación Node, comienza por crear una aplicación Vonage para usar Messages API y ejecutar nuestra dependencia ngrok.
Exponga su servidor con ngrok
Para recibir webhooks de Vonage, tu servidor local debe ser accesible a través de Internet. Usa ngrok para exponer tu servidor. En tu terminal, ejecuta
ngrok http 3000Observe la URL HTTPS proporcionada por ngrok:
por ejemplo https://your-ngrok-subdomain.ngrok.io
Puede leer más sobre pruebas con ngrok en nuestro portal de herramientas para desarrolladores.
Crea y configura tu aplicación de Vonage
Ahora, crea tu aplicación de Vonage en el Panel de Vonage. Dale un nombre a la aplicación y activa la función Mensajes.
Creating a new Vonage Messages API application for an RCS-based interactive football experience
En la configuración de tu aplicación de Vonage:
Establezca la URL de entrada en
https://YOUR_NGROK_URL/inbound.Establezca la URL de estado en
https://example.com/rcs_status.
** Los estados de los mensajes se tratarán en un próximo artículo.Genere una clave pública y privada haciendo clic en el botón. Asegúrese de mover el archivo
private.keyal directorio raíz del proyecto (rcs-interactive-football) en la siguiente sección.Guarda los cambios.
A continuación, vincule su Agente RCS haciendo clic en la pestaña "Vincular cuentas externas":
Dashboard view showing the Vonage-Node-RCS application linked to the Vonage RoR RCS external account, with voice and message capabilities enabled.
Cree su aplicación de nodo
Nuestra aplicación es sencilla y plana. Puedes consultar el repositorio de GitHub para ver el código limpiado y organizado un poco más.
Tu estructura de archivos tendrá el siguiente aspecto:
rcs-interactive-football/
├── index.js
├── config.js
├── messageTemplates.js
├── messagingService.js
├── .env
├── package.json
└── private.key
Así que, adelante, crea un nuevo directorio e inicializa un proyecto Node.js:
mkdir rcs-interactive-football
cd rcs-interactive-football
npm init -yInstale los paquetes de nodos necesarios con Gestor de paquetes de nodos:
npm install express dotenv @vonage/server-sdkexpress: Crea el servidor web.dotenv: Carga las variables de entorno de forma segura.@vonage/server-sdk: El SDK de Vonage Node para interactuar con Messages API
Y crea los archivos de tu proyecto:
touch index.js config.js messageTemplates.js messagingService.js .envAhora puede mover su private.key que descargaste del panel de Vonage y moverlo a la raíz de tu proyecto.
Configure su entorno
En el archivo .env agrega tus credenciales y configuración de Vonage:
VONAGE_APPLICATION_ID=your_application_id
VONAGE_API_SIGNATURE_SECRET=your_api_secret
VONAGE_PRIVATE_KEY=./private.key
RCS_SENDER_ID=your_rbm_agent_id
PORT=3000VONAGE_APPLICATION_ID: Tu ID de aplicación de Vonage, que se encuentra en el panel API.VONAGE_API_SIGNATURE_SECRET= Tu firma secreta de Vonage Se encuentra en configuración de la cuenta.VONAGE_PRIVATE_KEY: Tu archivo de clave privada.RCS_SENDER_ID: Su RBM SenderID (el nombre de la marca). El SenderID requiere un formato especial, como no tener espacios. Consulte con su Account Manager si no está seguro.PORT: Número de puerto del servidor Express.
Construya su aplicación RCS Node
Paso 1: configura tu cliente de Vonage
Esta aplicación centraliza todos los valores configurables (variables de entorno, URL de imágenes y enlaces externos) en un único archivo config.js. Esto crea una separación limpia entre el contenido y la lógica. Este enfoque le ofrece una única fuente de verdad para los valores que puedan cambiar. Esta organización le permite intercambiar rápidamente activos multimedia o actualizar enlaces de mercancías manteniendo intacto el flujo de mensajería principal.
// config.js
require('dotenv').config();
module.exports = {
port: process.env.PORT || 3000,
vonage: {
applicationId: process.env.VONAGE_APPLICATION_ID,
privateKey: process.env.VONAGE_PRIVATE_KEY,
signatureSecret: process.env.VONAGE_API_SIGNATURE_SECRET,
},
rcsSenderId: process.env.RCS_SENDER_ID,
images: {
footballMatch: "https://github.com/Vonage-Community/tutorial-messages-node-rcs_realtime_football/blob/main/public/football_match.png?raw=true",
manOfMatch: "https://github.com/Vonage-Community/tutorial-messages-node-rcs_realtime_football/blob/main/public/man_of_match.png?raw=true",
jersey: "https://github.com/Vonage-Community/tutorial-messages-node-rcs_realtime_football/blob/main/public/ronaldinho_jersey.png?raw=true",
photo: "https://github.com/Vonage-Community/tutorial-messages-node-rcs_realtime_football/blob/main/public/ronaldinho_photo.png?raw=true",
tshirt: "https://github.com/Vonage-Community/tutorial-messages-node-rcs_realtime_football/blob/main/public/ronaldinho_shirt.png?raw=true",
},
merchLinks: {
jersey: "https://www.ebay.com/b/Ronaldinho-International-Club-Soccer-Fan-Jerseys/2887/bn_16948843",
photo: "https://www.ebay.com/shop/ronaldinho-signed-photo?_nkw=ronaldinho+signed+photo",
tshirt: "https://www.ebay.com/itm/236003366810?_skw=ronaldinho+tshirt",
}
}; Paso 2: Defina sus plantillas de mensajes RCS
A continuación, rellenaremos nuestro archivo messageTemplate.js archivo. El módulo messageTemplates.js encapsula todas las estructuras de mensajes RCS en funciones limpias y reutilizables que separan la presentación de la lógica de negocio.
Cada función de plantilla (respuestas sugeridas, tarjetas enriquecidas independientes o carruseles de tarjetas enriquecidas) sigue el mismo patrón. Acepta un parámetro de número de teléfono, extrae los medios y URL adecuados de nuestro módulo de configuración y luego devuelve un objeto de mensaje RCS con el formato adecuado listo para la API de Vonage.
Este enfoque modular hace que nuestro flujo interactivo sea fácil de entender y modificar, lo que permite a los desarrolladores adaptar rápidamente las plantillas a sus propios escenarios de participación en tiempo real sin tener que vadear a través de una compleja lógica de mensajería.
Así, por ejemplo, en la Mensajespuede ver el ejemplo respuesta sugerida:
vonage.messages.send({
messageType: 'custom',
channel: Channels.RCS,
custom: {
contentMessage: {
text: 'What do you think of Vonage APIs?',
suggestions: [
{
reply: {
text: 'They\''re great!',
postbackData: 'suggestion_1',
},
},
{
reply: {
text: 'They\'re awesome!',
postbackData: 'suggestion_2',
},
},
],
},
},
to: MESSAGES_TO_NUMBER,
from: RCS_SENDER_ID,
})
Del mismo modo, puede crear una función initialMessage en el archivo messagesTemplate.js módulo. Esta versión modularizada abstrae el destinatario y el SenderID:
// messageTemplates.js
const config = require('./config');
module.exports = {
// Initial Suggested Reply Message to Kick-off
initialMessage: (to) => ({
to,
from: config.rcsSenderId,
channel: 'rcs',
message_type: 'custom',
custom: {
contentMessage: {
text: "Who will win?",
suggestions: [
{ reply: { text: "Brazil", postbackData: "brazil" }},
{ reply: { text: "Germany", postbackData: "germany" }},
{ reply: { text: "Draw", postbackData: "draw" }},
]
}
}
})
};Continúe agregando las plantillas para RCS Standalone Rich Card y RCS Rich Card Carousel. Estos adicionalmente abstraer los medios de comunicación, que obtenemos de nuestro módulo de configuración. En primer lugar, la tarjeta independiente, que permite a los usuarios votar por su hombre del partido:
// Standalone Rich Card for voting on Man of the Match
manOfTheMatchMessage: (to) => ({
to,
from: config.rcsSenderId,
channel: 'rcs',
message_type: 'custom',
custom: {
contentMessage: {
richCard: {
standaloneCard: {
thumbnailImageAlignment: "RIGHT",
cardOrientation: "VERTICAL",
cardContent: {
title: "Vote Now!",
description: "Who was the man of the match?",
media: {
height: "TALL",
contentInfo: {
fileUrl: config.images.manOfMatch,
forceRefresh: true
}
},
suggestions: [
{ reply: { text: "Ronaldinho", postbackData: "ronaldinho" } },
{ reply: { text: "Ronaldo", postbackData: "ronaldo" } },
{ reply: { text: "Pele", postbackData: "pele" } }
]
}
}
}
}
}
})Y por último, crea la plantilla de mensaje para el carrusel RCS, que muestra a tus usuarios la mercancía que pueden comprar.
// RCS Rich Card Carousel for Player Merch to Present
playerMerchCarousel: (to) => ({
to,
from: config.rcsSenderId,
channel: 'rcs',
message_type: 'custom',
custom: {
contentMessage: {
richCard: {
carouselCard: {
cardWidth: "MEDIUM",
cardContents: [
{
title: "Ronaldinho Jersey",
description: "Authentic gameworn kit.",
media: {
height: "TALL",
contentInfo: {
fileUrl: config.images.jersey,
forceRefresh: true
}
},
suggestions: [
{
action: {
text: "Buy now",
postbackData: "buy_now_jersey",
openUrlAction: {
url: config.merchLinks.jersey
}
}
}
]
},
{
title: "Autographed Photo",
description: "Timeless photo signed by Ronaldinho himself.",
media: {
height: "TALL",
contentInfo: {
fileUrl: config.images.photo,
forceRefresh: true
}
},
suggestions: [
{
action: {
text: "Buy now",
postbackData: "buy_now_photo",
openUrlAction: {
url: config.merchLinks.photo
}
}
}
]
},
{
title: "Fan T-shirt",
description: "100% Cotton, 100% Passion.",
media: {
height: "TALL",
contentInfo: {
fileUrl: config.images.tshirt,
forceRefresh: true
}
},
suggestions: [
{
action: {
text: "Buy now",
postbackData: "buy_now_shirt",
openUrlAction: {
url: config.merchLinks.tshirt
}
}
}
]
}
]
}
}
}
}
})>> Puede ver el archivo messagesTemplate.js completo
Paso 3: Creación de un servicio de mensajería
Ahora que tenemos la configuración y las plantillas de mensajes, creemos un servicio de mensajería que resuma las interacciones de la API de Vonage. El módulo messagingService.js toma las plantillas de mensajes que ya creamos y agrega la funcionalidad necesaria para enviar el mensaje a través de la API.
Primero, inicialicemos el cliente de Vonage utilizando nuestra configuración:
// messagingService.js
const { Vonage } = require('@vonage/server-sdk');
const config = require('./config');
const messageTemplates = require('./messageTemplates');
// Initialize the Vonage client with our application credentials
const vonage = new Vonage({
applicationId: config.vonage.applicationId,
privateKey: require('fs').readFileSync(config.vonage.privateKey)
});Ahora que nuestro vonage está listo, podemos crear la funcionalidad sendInitialMessage pasando el mensaje con el número de teléfono al cliente:
module.exports = {
sendInitialMessage: async (to) => {
try {
const msg = messageTemplates.initialMessage(to);
const response = await vonage.messages.send(msg);
console.log(`Initial message sent successfully`);
return response;
} catch (error) {
console.error('Error sending initial message:', error);
throw error;
}
}
}Crearemos dos funciones más ( sendManOfTheMatchMessage y sendPlayerMerchCarousel ) para que coincidan con nuestros otros dos mensajes:
sendManOfTheMatchMessage: async (to) => {
try {
const msg = messageTemplates.manOfTheMatchMessage(to);
const response = await vonage.messages.send(msg);
console.log(`Man of the Match message sent successfully`);
return response;
} catch (error) {
console.error('Error sending Man of the Match message:', error);
throw error;
}
},
sendPlayerMerchCarousel: async (to) => {
try {
const msg = messageTemplates.playerMerchCarousel(to);
const response = await vonage.messages.send(msg);
console.log(`Merchandise carousel sent successfully`);
return response;
} catch (error) {
console.error('Error sending merchandise carousel:', error);
throw error;
}
}
>> Puede ver el archivo messagesService.js completo
Paso 4: Implementar la lógica principal de la aplicación
Ahora es el momento de unir todo en nuestro archivo index.js archivo. Aquí es donde vamos a crear nuestro servidor Express, configurar nuestras rutas, e implementar la lógica de flujo interactivo que hace que nuestra experiencia RCS dinámico y atractivo.
Configurar el servidor Express
En primer lugar, configuraremos Express y estableceremos un middleware básico para poder gestionar peticiones JSON y URL codificadas:
// index.js
const express = require('express');
const { verifySignature } = require('@vonage/jwt');
const config = require('./config');
const messagingService = require('./messagingService');
// Initialize Express app
const app = express();
app.use(express.json());
app.use(express.urlencoded());
// Constants
const PORT = config.port;
const VONAGE_API_SIGNATURE_SECRET = config.vonage.signatureSecret;
// Simple home route to confirm server is running
app.get('/', (req, res) => {
res.send('RCS Interactive Football Demo - Server is running!');
}); Activar el primer mensaje
Esta ruta nos permite iniciar manualmente la conversación con un usuario. Puedes utilizar Postman o cURL para iniciar el mensaje inicial "¿Quién ganará?
app.post('/send-initial-message', async (req, res) => {
const toNumber = req.body.to;
try {
await messagingService.sendInitialMessage(toNumber);
res.status(200).json({ message: 'Initial message sent successfully.' });
} catch (error) {
console.error('Error in /send-initial-message:', error);
res.status(500).json({ error: 'Internal server error.' });
}
}); Gestión de webhooks entrantes
Ahora la parte más importante: el manejador webhook que procesa las respuestas del usuario y crea nuestro flujo interactivo.
Vonage envía webhook callbacks cuando un usuario interactúa con su mensaje RCS. Así que comprobamos el tipo de canal y el tipo de mensaje:
if (inboundMessage.channel === 'rcs' && inboundMessage.message_type === 'reply')Y esperamos que esa interacción provenga de una respuesta sugerida, un botón de una tarjeta o un elemento del carrusel. Las tarjetas enriquecidas utilizan el atributo postbackData pero para las respuestas sugeridas tenemos que recurrir al atributo id:
const userSelection = inboundMessage.reply?.postbackData || inboundMessage.reply?.id;
Poniendo todo junto, su inbound webhook tiene este aspecto:
app.post('/inbound', async (req, res) => {
// Verify the message signature for security
const token = req.headers.authorization?.split(' ')[1];
if (!token || !verifySignature(token, VONAGE_API_SIGNATURE_SECRET)) {
console.error('Invalid signature');
return res.status(401).json({ error: 'Invalid signature' });
}
const inboundMessage = req.body;
// Only process RCS reply messages
if (inboundMessage.channel === 'rcs' && inboundMessage.message_type === 'reply') {
// Retrieve the postbackData for RCS Cards, id for Suggested Replies
const userSelection = inboundMessage.reply?.postbackData || inboundMessage.reply?.id;
const userNumber = inboundMessage.from;
// Log the inbound message for debugging
console.log(`User ${userNumber} selected: ${userSelection}`);
try {
// Handle different user selections based on our interactive flow
switch (userSelection) {
case 'brazil':
// User selected Brazil - send man of the match voting
console.log(`Sending man of the match message to ${userNumber}`);
await messagingService.sendManOfTheMatchMessage(userNumber);
break;
case 'ronaldinho':
// User selected Ronaldinho - send merchandise carousel
console.log(`Sending player merchandise carousel to ${userNumber}`);
await messagingService.sendPlayerMerchCarousel(userNumber);
break;
default:
// For any other selection, log a confirmation message to the service
console.log(`Sending confirmation for ${userSelection} to ${userNumber}`);
}
// Always return 200 OK to Vonage
res.status(200).end();
} catch (error) {
console.error('Error processing inbound message:', error);
res.status(500).json({ error: 'Internal server error' });
}
} else {
// Not an RCS reply message
console.log('Received non-RCS reply message');
res.status(200).end();
}
});
// Start the server
app.listen(PORT, () => {
console.log(`Server is running on port ${PORT}`);
console.log('RCS Interactive Football Demo is ready!');
});
>> Puede ver el archivo archivo index.js
Cómo probar su aplicación Node RCS
Abra una nueva pestaña de terminal, separada de su pestaña ngrok, e inicie su servidor Express:
node index.jsUtilice una herramienta como Postman o cURL para enviar una solicitud POST a su /send-initial-message con el número de teléfono del destinatario:
curl -X POST https://YOUR_NGROK_URL/send-initial-message \
-H "Content-Type: application/json" \
-d '{"to": "YOUR_RCS_TEST_NUMBER"}'Vea cómo se desarrolla el flujo interactivo en su dispositivo.
Example of an RCS Rich Card showcasing a Ronaldinho jersey as part of an interactive football campaign
Conclusión
¡Buen trabajo! Acabas de crear una experiencia RCS en tiempo real y en varios pasos usando Node.js y la API Messages API de Vonage. Es modular y fácil de reutilizar. Este patrón funciona muy bien para deportes, música, venta al por menor o cualquier evento en el que necesites interacciones rápidas y un compromiso real.
Dicho esto, sólo hemos construido una rama del flujo. Si el usuario elige Alemania o cree que el partido acabará en Empateno pasa nada... ¡todavía! Esos son tus próximos pasos. Ya tienes las plantillas y la arquitectura listas, así que añadir esas rutas debería ser sencillo.
Pero no te detengas ahí.
Intente combinar esto con la nueva API de ubicación de dispositivos. Si sabes que un usuario está en el estadio o viendo el partido en un pub, puedes activar este flujo RCS interactivo justo en el momento de mayor impacto.
Si desarrollas el resto del flujo o lo integras en tu propia aplicación para eventos, háznoslo saber. Nos encantaría verlo. Etiqueta VonageDev en X, o pásate por Slack de la comunidad de desarrolladores de Vonage y muéstranos en qué estás trabajando.
Compartir:
Benjamin Aronov es desarrollador de Vonage. Es un constructor de comunidades con experiencia en Ruby on Rails. Benjamin disfruta de las playas de Tel Aviv, a la que llama hogar. Su base en Tel Aviv le permite conocer y aprender de algunos de los mejores fundadores de startups del mundo. Fuera de la tecnología, a Benjamin le encanta viajar por el mundo en busca del perfecto pain au chocolat.
