Cómo enviar carruseles de tarjetas enriquecidas RCS con Node.js

Introducción

Servicios de Comunicación Enriquecidos (RCS) le ofrece las herramientas para crear experiencias de marca modernas e interactivas dentro de la aplicación de mensajería predeterminada del usuario. Entre sus funciones más potentes está el carrusel de tarjetas enriquecidas: un conjunto de tarjetas de desplazamiento horizontal que pueden incluir vídeos, imágenes, texto y acciones táctiles.

En este tutorial, aprenderás a enviar un carrusel RCS utilizando Node.js y la API de Messages de Vonage. Combinarás tarjetas de Video e imágenes con acciones para aumentar la participación.

>> TL;DR: Ver el código completo en GitHub

Caso práctico: Anuncio emergente de moda

Supongamos que su marca lanza una tienda pop-up de moda por tiempo limitado. Quiere generar expectación y mostrar los artículos clave. Con un carrusel de RCS, puede empaquetar todo esto en un mensaje limpio e interactivo.

Su carrusel RCS incluirá medios y acciones sugeridas:

1. Tarjeta 1: Video de lanzamiento del evento

   • Video trailer de la ventana emergente

   • 2 acciones: "Guardar la fecha" y "Ver ubicación".

2. Tarjeta 2: Imagen de camisetas:

   • Una imagen de la camiseta destacada

   • acción: "Ver todas las camisetas"

3. Tarjeta 3: Imagen de sombreros:

   • Una imagen de su colección de sombreros

   • acción: "Ver todos los sombreros"

¿Qué es un carrusel RCS?

Un carrusel RCS es un conjunto de tarjetas ricas deslizables, cada una con la suya propia:

• Un título (máximo 200 caracteres)

• Una descripción (máx. 2000 caracteres)

• Soporte: imagen o Video

• Hasta cuatro respuestas o acciones sugeridas

Las tarjetas aparecen horizontalmente, lo que permite a los usuarios pasarlas por encima.

Illustration of an RCS carousel message in the Android Messages app, annotated to show benefits like trusted branding, verified sender ID, richer media cards, time-saving action buttons, and quick-reply suggestions.

Notas importantes:

• Todas las tarjetas de un carrusel deben utilizar el mismo tipo de sugerencia.

• Los archivos multimedia deben ser de acceso público y ocupar menos de 100 MB.

• Puede incluir entre 2 y 10 tarjetas.

Requisitos previos

Antes de empezar, necesitarás:

• Node.js instalado en su máquina.

• ngrok instalado para exponer su servidor local a Internet.

• Una cuenta API de Vonage.

• Un Agente registrado de RCS Business Messaging (RBM), ver cuentas administradas abajo.

• Un teléfono con capacidades RCS 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.

Cómo contactar a tu administrador de cuentas de Vonage

Para poder enviar y recibir funciones RCS en tu aplicación de Vonage, deberás tener un agente registrado de Rich Business Messaging (RBM) y un teléfono con capacidades de RCS.

Actualmente, la mensajería RCS a través de Vonage sólo está disponible para cuentas administradas. Deberás comunicarte con tu administrador de cuenta para solicitar la activación del modo para desarrolladores para tu agente de RBM. El modo para desarrolladores te permite probar la mensajería RCS a números permitidos antes de completar el proceso de verificación del agente y lanzarlo en producción.

Por favor póngase en contacto con nuestro equipo de ventas si no tiene una cuenta gestionada.

>> Comprender la diferencia entre RCS y RBM.

Cómo configurar un proyecto Node.js

Esta guía asume que estás familiarizado con los conceptos básicos de JavaScript y Node.js.

Inicializar el proyecto

Crea un nuevo directorio e inicializa un proyecto Node.js:

mkdir rcs-carousel-node
cd rcs-carousel-node
npm init -y

Instale los paquetes NPM necesarios

Instale los paquetes de nodos necesarios con Gestor de paquetes de nodos (NPM):

npm install express dotenv @vonage/server-sdk

• exprés: Crea el servidor web

• dotenv: Carga las variables de entorno

• @vonage/server-sdk: Envía mensajes a través de la API Messages API de Vonage

Cree sus archivos de proyecto

Cree el archivo principal de la aplicación y el archivo de configuración del entorno:

touch index.js .env

Cómo configurar 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=3000

• VONAGE_APPLICATION_ID: Tu ID de aplicación de Vonage.

• VONAGE_API_SIGNATURE_SECRET= Tu secreto de API de Vonage

• VONAGE_CLAVE_PRIVADA: El archivo de clave privada de tu aplicación de Vonage.

• RCS_SENDER_ID: Su SenderID de RBM (el nombre de la marca). El SenderID requiere un formato especial, como no tener espacios. Consulte con su Account Manager si no está seguro.

• PUERTO: Número de puerto para el servidor Express.

Obtendrás tu ID de aplicación de Vonage y el archivo private.key a continuación, en la sección "Cómo crear y configurar una aplicación de Vonage". sección. Encuentra tu secreto de API en la página de inicio del panel del desarrollador.

Cómo enviar un carrusel RCS

Ahora que su entorno está configurado, vamos a escribir el código que realmente envía su carrusel de tarjetas ricas RCS.

En este paso, crearás un servidor Express que envíe un mensaje RCS personalizado usando la API Messages de Vonage. El carrusel contendrá tres tarjetas de producto deslizables, cada una con medios (video o imagen), un título y una descripción, y botones accionables que tus usuarios pueden tocar.

Cargar dependencias e inicializar el cliente de Vonage

Comenzaremos importando los paquetes necesarios, cargando tus variables de entorno e inicializando el cliente de Vonage. Agrega el siguiente código a tu archivo index.js para poner las cosas en marcha:

const express = require('express');
const fs = require('fs');
const dotenv = require('dotenv');
const { Vonage } = require('@vonage/server-sdk');
const { verifySignature } = require('@vonage/jwt');

dotenv.config();

const app = express();
app.use(express.json());

const PORT = process.env.PORT || 3000;

const VONAGE_API_SIGNATURE_SECRET = process.env.VONAGE_API_SIGNATURE_SECRET;

const privateKey = fs.readFileSync(process.env.VONAGE_PRIVATE_KEY);

const vonage = new Vonage({
  applicationId: process.env.VONAGE_APPLICATION_ID,
  privateKey: privateKey
});

Definir un punto final Express para enviar un carrusel RCS

Conviene conocer algunos detalles pequeños pero importantes antes de enviar el carrusel. Todos los archivos multimedia deben ser accesibles públicamente a través de HTTPS, idealmente alojados en una CDN o almacenamiento en la nube. En este ejemplo vamos a utilizar activos alojados en GitHub para simplificar el proceso, pero en producción querrás un alojamiento más rápido y fiable.

>> Mantén los archivos multimedia individuales por debajo de 100 MB para cumplir las restricciones de RCS.

Cada tarjeta incluye uno o varios botones de acción que utilizan postbackData, openUrlActiono createCalendarEventAction. La dirección postbackData es una cadena corta (50 caracteres como máximo) que su servidor puede utilizar para rastrear lo que los usuarios tocan. También puedes enlazar directamente a mapas o eventos de calendario precargados para añadir interactividad, haciendo que el carrusel parezca más una miniapp que un simple mensaje.

app.post('/send-rcs-carousel', async (req, res) => {
  const toNumber = req.body.to;

  const message = {
    to: toNumber,
    from: process.env.RCS_SENDER_ID,
    channel: 'rcs',
    message_type: 'custom',
    custom: {
      contentMessage: {
        richCard: {
          carouselCard: {
            cardWidth: "MEDIUM",
            cardContents: [
              {
                title: "Fashion Popup Launch 🎉",
                description: "Join us this weekend for limited drops & exclusive looks.",
                media: {
                  height: "TALL",
                  contentInfo: {
                    fileUrl: "https://raw.githubusercontent.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/main/rcs-fashion-video.gif",
                    thumbnailUrl: "https://raw.githubusercontent.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/main/rcs-fashion-thumbnail.png",
                    forceRefresh: true
                  }
                },
                suggestions: [
                  {
                    "action": {
                      "text": "Save the Date",
                      "postbackData": "save_event",
                      "fallbackUrl": "https://www.google.com/calendar",
                      "createCalendarEventAction": {
                        "startTime": "2024-06-28T19:00:00Z",
                        "endTime": "2024-06-28T20:00:00Z",
                        "title": "Fashion Popup Launch",
                        "description": "Join us this weekend for limited drops & exclusive looks."
                      }
                    }
                  },
                  {
                    action: {
                      text: "See Location",
                      postbackData: "view_location",
                      openUrlAction: {
                        url: "https://maps.google.com/?q=Galleria+Vittorio+Emanuele+II,+Milan,+Italy"
                      }
                    }
                  }
                ]
              },
              {
                title: "Drop 01: T-Shirts",
                description: "Bold graphics. Oversized fit. Designed to stand out.",
                media: {
                  height: "TALL",
                  contentInfo: {
                    fileUrl: "https://raw.githubusercontent.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/main/rcs-fashion-tshirt.png"
                  }
                },
                suggestions: [
                  {
                    action: {
                      text: "See All",
                      postbackData: "see_tshirts",
                      openUrlAction: {
                        url: "https://github.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/blob/main/rcs-fashion-tshirt.png"
                      }
                    }
                  }
                ]
              },
              {
                title: "Drop 02: Hats",
                description: "Top off your look. Fresh colors, bold logos.",
                media: {
                  height: "TALL",
                  contentInfo: {
                    fileUrl: "https://raw.githubusercontent.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/main/rcs-fashion-hat.png",
                  }
                },
                suggestions: [
                  {
                    action: {
                      text: "See All",
                      postbackData: "see_hats",
                      openUrlAction: {
                        url: "https://github.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/blob/main/rcs-fashion-hat.png"
                      }
                    }
                  }
                ]
              }
            ]
          }
        }
      }
    }
  };

  try {
    const response = await vonage.messages.send(message);
    console.log("Carousel sent:", response);
    res.status(200).json({ message: "Carousel sent successfully." });
    console.log("Vonage API response:", JSON.stringify(response, null, 2));
  } catch (error) {
    console.error("Error sending carousel:", error);
    res.status(500).json({ error: "Failed to send carousel." });
  }
});

Cómo recibir acciones sugeridas de RCS a través de Webhooks

¡Enviar un carrusel es genial! Pero, ¿no sería bueno saber si tu usuario interactuó con tu carrusel? Con los webhooks de Vonage, puedes hacerlo.

Crea el siguiente endpoint, que gestionará las solicitudes RCS entrantes de nuestra aplicación de Vonage. Este código:

• Valida que la solicitud proviene de Vonage mediante una firma JWT.

• Busca el botón ya que se espera una acción en lugar de una respuesta y almacena la carga útil en userAction

• Registra la acción userAction a nuestro servidor Node para ver qué ha seleccionado el usuario

app.post('/inbound_rcs', async (req, res) => {
  const token = req.headers.authorization?.split(' ')[1];

  if (!verifySignature(token, VONAGE_API_SIGNATURE_SECRET)) {
    res.status(401).end();
    return;
  }

  const inboundMessage = req.body;

  if (inboundMessage.channel === 'rcs' && inboundMessage.message_type === 'button') {
    const userAction = inboundMessage.button.payload;
    const userNumber = inboundMessage.from;

    console.log(`User ${userNumber} tapped action: ${userAction}`);
  }

  res.status(200).end();
});

Cómo definir su servidor Express

En la parte inferior del archivo index.jsañade este código para construir tu servidor Express.

app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

Y finalmente ejecute su servidor desde la línea de comandos:

node index.js

>> Ver el archivo index.js completo.

Cómo exponer su servidor con ngrok

Para recibir webhooks de Vonage, tu servidor local debe ser accesible a través de Internet. Utiliza ngrok para exponer tu servidor ejecutando el siguiente comando en una pestaña de tu servidor Express:

ngrok http 3000

Tenga en cuenta 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.

Cómo crear y configurar tu aplicación de Vonage

Ahora que tu aplicación Node está lista, también necesitarás crear y configurar tu aplicación de Vonage. Primero, crea tu aplicación en el Panel de Vonage. Dale un nombre a la aplicación y activa la función de mensajes.

Vonage dashboard showing the creation of a new application configured for RCS messaging.

En la configuración de tu aplicación de Vonage:

1. Establezca la URL de entrada en https://YOUR_NGROK_URL/inbound_rcs.

2. 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.

3. Genere una clave pública y privada haciendo clic en el botón. Asegúrese de mover su private.key al directorio raíz del proyecto (rcs-carousel-node).

4. Guarda los cambios.

A continuación, vincule su Agente RCS haciendo clic en el botón "Vincular cuentas externas" pestaña:

Dashboard view showing the Vonage-Node-RCS application linked to the Vonage RoR RCS external account, with voice and message capabilities enabled.

Cómo probar su aplicación Node

Utilice este curl para activar su punto final (sustituya los marcadores de posición):

curl -X POST https://YOUR_NGROK_URL/send-rcs-carousel \
  -H "Content-Type: application/json" \
  -d '{"to": "YOUR_RCS_TEST_NUMBER"}'

En el teléfono del destinatario aparecerá el carrusel de tarjetas enriquecidas y podrá seleccionar una acción.

Notas finales

Ahora has construido un carrusel interactivo de productos RCS con Node.js y la API Messages API de Vonage. Esta es una excelente manera de mostrar productos, promocionar eventos u ofrecer opciones dinámicas en un solo mensaje.

¿Quiere ir más lejos?

• Responder a los toques y selecciones mediante postbackData

• Cargar fichas de productos dinámicamente desde una API

• Añadir filtros o categorías basados en la ubicación

Ven a mostrar lo que estás construyendo en el Slack de la comunidad de Vonage o etiquétanos en X (antes Twitter). ¡Nos encantaría ver tus carruseles en acción!