Enviar y abrir archivos RCS utilizando GitHub Codespaces

Introducción

Este tutorial muestra cómo enviar y abrir un archivo a través de RCS con la Mensajes API de Vonage. A diferencia de SMS o MMS, RCS admite archivos de mayor calidad sin límites de tamaño estrictos, lo que lo convierte en una opción adecuada para documentos como tickets, facturas o PDF. En este post, vamos a enviar un archivo PDF a través de RCS utilizando GitHub Codespaces.

open RCS message containing PDF

Requisitos previos

• A Account GitHub

• A agente registrado de RCS Business Messaging (RBM)

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

Espacios de código GitHub

Visión general

Últimamente he estado explorando GitHub Codespaces. Se trata de un entorno de desarrollo alojado en un contenedor Docker, que se ejecuta en una máquina virtual. Principalmente lo uso accediendo a un repositorio de GitHub y añadiendo /codespaces a la URL, para poder acceder a él en Visual Studio Code a través de mi navegador preferido. Alternativamente, puedes crear una instancia de espacio de código a partir de una plantilla o cualquier rama o commit en un repositorio de GitHub.

Abrir el proyecto en Codespaces

Para empezar accediendo al repositorio que he creado para esta entrada del blog y añadiendo /codespaces. La URL sería la siguiente https://github.com/Vonage-Community/blog-messages-nodejs-rcs-file/codespaces

Haz clic en "Create codespace on main" en la parte superior derecha de la página. GitHub empezará a configurar un nuevo entorno para ti.

Click “Create codespace on main” to start your environmentUna vez cargado, estarás dentro de un editor VS Code basado en navegador donde podrás ejecutar y editar el proyecto inmediatamente. Usa esto para ejecutar tu instancia. Sin embargo, siéntete libre de ejecutar el código que mostraré en esta entrada de blog en tu IDE o entorno preferido.

Para más detalles, consulta la guía oficial de GitHub: Inicio rápido para GitHub Codespaces.

Aprenda algunos comandos en Codespaces

Si tienes experiencia con Visual Studio Code, puedes encontrar tu camino usando Codespaces. Siempre se puede navegar y encontrar el abajo en los menús, pero aquí hay algunos comandos para ayudarle a navegar más fácilmente:

• Abrir archivos: Control + ` en Mac o Windows/Linux.

• Abre el terminal: Command + Shift + P en Mac o Ctrl + Shift + P en Windows/Linux.

Instalación con npm

Ejecute npm install en el terminal de Codespaces para instalar los siguientes paquetes que se encuentran en el archivo package.json.

• dotenv: carga tus variables de entorno desde un archivo .env, manteniendo privada la información sensible como las claves API.

• @vonage/server-sdkel SDK central de Vonage Node.js. Te ayuda a autenticar e inicializar el cliente de Vonage.

• @vonage/mensajesuna biblioteca dedicada para enviar mensajes a través de la API Messages API de Vonage. La utilizamos para enviar mensajes RCS (texto, imágenes, archivos, etc.).

npm install dotenv @vonage/server-sdk @vonage/messages

Añadir las variables de entorno

Algunas variables contienen información sensible, por lo que no me gustaría añadir públicamente claves de API, secretos o incluso el número de teléfono que utilizaré para las pruebas. Así que las añadiremos a un archivo .env. Aquí tienes más información sobre el uso de variables de entorno en Node.

Crear un archivo .env

Copie el archivo .env.example en un nuevo archivo .env que debe crear ahora. Desde la terminal de codespaces:

touch .env

En el fragmento de código siguiente, enumero todas las variables de entorno que necesitaremos. Las explicaré una a una y explicaré dónde encontrarlas.

VONAGE_APPLICATION_ID=000000-0000-0000-0000-0000000000

VONAGE_PRIVATE_KEY=./private.key

RCS_SENDER_ID=NameOfYourAgent

MESSAGES_FILE_URL=https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf

• Ingresa a tu cuenta de Vonage y procede a crear una nueva solicitud.

  • Para crear una aplicación, vaya a la sección Crear una aplicación en el panel de Vonage y define un nombre para tu aplicación.

    

  • Si tiene intención de utilizar una API que utilice Webhooks, necesitará una clave privada. Haga clic en "Generar clave pública y privada"; la descarga debería iniciarse automáticamente. Guárdela de forma segura; esta clave no puede volver a descargarse si se pierde. Seguirá la convención de nomenclatura private_<id de su aplicación>.key. Esta clave puede utilizarse ahora para autenticar llamadas a la API. Nota: La clave no funcionará hasta que se guarde la aplicación.

  • Elija las funciones que necesite (por ejemplo, Voice, Messages, RTC, etc.) y proporcione los webhooks necesarios (por ejemplo, URL de eventos, URL de respuestas o URL de mensajes entrantes). Estos se describirán en el tutorial.

  • Para guardar e implementar, haz clic en "Generar nueva aplicación" para finalizar la configuración. Tu aplicación ahora está lista para usar con las API de Vonage.

• Dentro de la vista de aplicaciones, cada aplicación contiene un ID de aplicación. Copie esa cadena y péguela en su VONAGE_APPLICATION_ID variable.

• Haz clic para generar una clave privada. Se descargará un archivo en tu carpeta de descargas. Añádelo a la raíz de tu archivo en GitHub Codespaces. Ponle un nombre private.key.

• Los mensajes RCS se envían desde un agente, que se puede encontrar en la pestaña "vincular cuentas externas" una vez que lo hayas creado. Entender la mensajería RCS.

• La dirección MESSAGES_FILE_URL contiene una URL a un archivo que se enviará a través de un mensaje RCS. He estado usando esta ruta de archivo PDF pública para las pruebas.

Comprender la lógica

Abra el archivo index.js JavaScript, que se encuentra en el menú de la izquierda en GitHub Codespaces.

Importar dependencias

En la parte superior de tu archivo, verás la importación de ambos paquetes de Vonage: @vonage/server-sdk y @vonage/messagesque se explicaron previamente en la sección "Instalación con Npm".

import "dotenv/config";

const { Vonage } = require('@vonage/server-sdk');

const { Channels } = require('@vonage/messages');

Inicializar el cliente de Vonage

Inicialice el cliente de Vonage pasando el ID de la aplicación y la clave privada.

const vonage = new Vonage({

  applicationId: process.env.VONAGE_APPLICATION_ID,

  privateKey: process.env.VONAGE_PRIVATE_KEY,

});

Enviar el mensaje RCS

Para enviar un mensaje RCS con la Messages API, utilizaremos el método vonage.messages.send de la biblioteca biblioteca Vonage Node.jsespecificando el ‘RCS’ canal. Este método acepta objetos como parámetros, con información sobre el destinatario, el remitente y el contenido.

He puesto el MessageType como file. Puede comprobar todos los Tipos de medios admitidos.

vonage.messages.send({

  messageType: 'file',

  channel: Channels.RCS,

  file: {

    url: process.env.MESSAGES_FILE_URL,

  },

  to: process.env.PHONE_NUMBER,

  from: process.env.RCS_SENDER_ID,

})

  .then(({ messageUUID }) => console.log(messageUUID))

  .catch((error) => {

  console.error("Error sending RCS message:", error);

});

Ejecute su código

Desde el terminal en GitHub Codespaces, ejecute el archivo archivo index.js. Al ejecutar este archivo, se enviará un mensaje RCS al número de teléfono especificado. Verás un mensaje llamado "adjunto" en el dispositivo especificado, y al hacer clic, podrás ver el archivo que has especificado en el archivo MESSAGES_FILE_URL.

node index.js

Buenas prácticas y posible ampliación

Si desea ir más lejos, considere la posibilidad de instalar y ejecutar ngrok para exponer tu servidor local y permitir que Vonage envíe solicitudes de webhook directamente a tu entorno de desarrollo. Esto facilita la prueba de interacciones en tiempo real, como mensajes entrantes y recibos de entrega. También puedes implementar la verificación JWT para validar los webhooks entrantes y asegurarte de que provengan de fuentes confiables.

Conclusión

Ahora que ha aprendido a enviar archivos a través de RCS, considere la posibilidad de ampliar su solución mediante la implementación de respuestas sugeridas o carruseles de tarjetas enriquecidas. Actualmente, simplemente envía un archivo adjunto con el nombre del archivo. Puedes utilizar soluciones de tarjetas enriquecidas para que el mensaje y los archivos que se comparten sean aún más descriptivos y fáciles de consumir.