Mostrar notificaciones de SMS en el navegador con Next.JS, Ably y Vercel

La SMS API de Vonage te permite enviar y recibir mensajes de texto en todo el mundo usando un número virtual que puedes alquilar a Vonage.

En este tutorial, utilizarás la API de SMS de Vonage, la plataforma de mensajería en tiempo real Ably, Next.js y Vercel para recibir mensajes SMS en el navegador en tiempo real a medida que se reciben.

Aprende a hacerlo:

• Crear una nueva aplicación Next.js

• Crear una Account de Ably y obtener una API key

• Crear una API sin servidor Next.js Vercel

• Consigue un número de teléfono virtual con Vonage

• Configura Vonage para reenviar datos SMS como un webhook

• Utilizar componentes funcionales de React y ganchos de React con Ably

• Aloje su aplicación en Vercel

Dependencias

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.

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.

Ready to start building?

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

Para crear esta aplicación, también necesitarás:

• Una Account Ably para enviar mensajes: Crear una Account gratuita en Ably.

• Una Account de Vercel para el alojamiento en producción: Crear una Account gratuita en Vercel.

• Nodo 12 (LTS) o superior: Instalar Node.

Requisitos previos para el desarrollo local

Necesitará una clave API de Ably para autenticarse con el servicio de Ably. Para obtener una clave de API, una vez que haya creado una Account Ably:

1. Visite el panel de aplicaciones y haga clic en "Crear nueva aplicación".

2. Dar un nombre a la nueva aplicación

3. Copie la clave privada de la API una vez creada la aplicación. Guárdala bien, ya que así es como te autenticarás con el servicio de Ably.

Vercel proporciona algunas herramientas de línea de comandos Next.js para ayudarnos. No necesitan estar instaladas en tu sistema ya que se ejecutan usando npx.

WebSockets en Vercel con Ably

Vercel es una plataforma de alojamiento construida desde cero para alojar aplicaciones Next.js y funciones sin servidor. Permite a los usuarios desplegar Funciones Serverlessque son esencialmente bloques de código que responden a una petición HTTP.
Sin embargo, estas funciones tienen un tiempo máximo de ejecución, lo que significa que es imposible mantener una conexión WebSocket de esta manera.

Aquí es donde entra Ably. El cliente puede conectarse a un Canal Ably y enviar y recibir mensajes en él para añadir funcionalidad en tiempo real a su aplicación mediante la gestión de sus conexiones WebSocket para usted. Vamos a ver cómo construir una aplicación que utiliza la funcionalidad en tiempo real en este tutorial. Si quieres aprender más sobre WebSockets en Next.js y Vercel, consulta "Creación de una aplicación de chat en tiempo real con Next.js y Vercel".

Creación de la aplicación SMS en tiempo real

Para crear la Starter App:

1. En tu terminal, escribe npx create-next-app para crear una aplicación Next.js vacía.

2. Cree un archivo llamado .env en la raíz del directorio; aquí es donde pondremos las variables de entorno del proyecto.

3. Añade tu clave de API de Ably al archivo .env:

ABLY_API_KEY=your-ably-api-key:goes-here

1. Navegue hasta el directorio de su aplicación Next.js y escriba en la consola:

El servidor de desarrollo de Next.js se iniciará y verás una aplicación de inicio de Next.JS vacía. Construirás nuestra aplicación sms-in-the-browser sobre ella.

Mensajería Pub/Sub en tiempo real con Ably

Esta aplicación utiliza Ably para mensajería pub/sub entre los usuarios. Pub/Sub significa Publicar y Suscribir, y es un patrón popular utilizado para la entrega de datos en tiempo real. La aplicación enviará, o publishmensajes a través de un Canal Ably. Los clientes que utilicen la app estarán subscribed al canal y podrán recibir los mensajes.

Autenticación con el servicio Ably

Las aplicaciones Vercel Next.js no ejecutan "código del lado del servidor" tradicional. Sin embargo, puedes añadir archivos JavaScript a /pages/api/*y el motor de despliegue de Vercel tratará cada uno de ellos como un punto final de API y los gestionará como funciones sin servidor por ti.

Para el desarrollo local, las herramientas Next.js ejecutan estas funciones en un servidor Node, por lo que funcionan como cabría esperar en tu entorno de desarrollo local. Vas a añadir una función sin servidor Next.js / Vercel al código de inicio que creaste anteriormente para autenticar tu aplicación con Ably y hacer posible que empiece a enviar y recibir mensajes a través del servicio Ably.

Escribir la función sin servidor para conectarse a Ably

Necesitará instalar el paquete paquete npm Ably (es esencial que estés ejecutando Ably 1.2.5+ para esta aplicación, por compatibilidad con Vercel).

En el terminal, en la raíz de tu nueva aplicación, ejecuta:

A continuación, cree un archivo llamado ./pages/api/createTokenRequest.js en el que añadir el siguiente código:

import Ably from "ably/promises";

export default async function handler(req, res) {
    const client = new Ably.Realtime(process.env.ABLY_API_KEY);
    const tokenRequestData = await client.auth.createTokenRequest({ clientId: 'ably-nextjs-demo' });
    res.status(200).json(tokenRequestData);
};

Esta función sin servidor utiliza el SDK de Ably para crear un archivo tokenRequest con tu clave de API. Utilizarás este token más adelante - te permite mantener a salvo tu clave de API "real" mientras la utilizas en la app Next.js.
Por defecto, esta API está configurada para estar disponible en http://localhost:3000/api/createTokenRequest. Vas a proporcionar esta URL al SDK de Ably en tu cliente para autenticarte con Ably.

Recibir un SMS con Vonage y Vercel

Vonage te permite configurar números de teléfono móvil en su panel de API. Cuando se reciba un SMS, se activará tu API.

Para ello, es necesario añadir un Vercel Serverless function a nuestra aplicación Next.js. Vonage llamará a esta función sin servidor cada vez que se reciba un SMS (una vez que hayas configurado un número de teléfono). Necesitas poner algo de código en esta función para desempaquetar el mensaje SMS, y luego enviarlo a tu aplicación React usando un comando Ably channel.

Este proceso es bastante similar a la configuración de su Ably createTokenRequest.

Cree un archivo llamado ./pages/api/acceptWebhook.js en el que añadir el siguiente código:

import Ably from "ably/promises";

export default async function handler(req, res) {

    // Unpack the SMS details from the request query string
    const incomingData = getSmsDetails(req, res);

    // If the request was invalid, return status 400.
    if (!incomingData.success) {
        res.status(400).end();
        return;
    }

    // Create an Ably client, get your `sms-notifications` channel
    const client = new Ably.Realtime(process.env.ABLY_API_KEY);
    const channel = client.channels.get("sms-notifications");

    // Publish your SMS contents as an Ably message for the browser
    await channel.publish({ name: "smsEvent", data: incomingData });

    // Return the received data as a 200 OK for debugging.
    res.send(incomingData);
    res.status(200).end();
};

function getSmsDetails(req, res) {

    const params = req.query;

    if (!params.to || !params.msisdn) {
        console.log('This is not a valid inbound SMS message!');
        return { success: false };
    }

    return {
        success: true,
        messageId: params.messageId,
        from: params.msisdn,
        text: params.text,
        type: params.type,
        timestamp: params['message-timestamp']
    };
}

Vamos a volver a la aplicación por ahora, pero volveremos a esta función al final una vez que la aplicación se despliegue en Vercel y su función tenga un public url.

Reacción a los mensajes SMS con el componente SmsComponent

Las páginas en Next.js son componentes React, por lo que la pages/index.js página de inicio es el componente React que contiene el diseño de la página.

Esta es la página por defecto generada por create-next-appa la que añadirá su componente; la lógica de la aplicación se encuentra dentro de la página SmsComponent.jsx.

Empieza por hacer referencia a las importaciones que necesitarás en la parte superior del archivo:

import React, { useEffect, useState } from 'react';
import { useChannel } from "./AblyReactEffect";
import styles from './SmsComponent.module.css';

A continuación, defina la función que se exportará como un componente React.

const SmsComponent = () => {
    
  let messageEnd = null;

  const [receivedMessages, setMessages] = useState([]);

y usa tu primer react hook:

  const [channel, ably] = useChannel("sms-notifications", (message) => {
    const history = receivedMessages.slice(-199);
    setMessages([...history, message]);
  });

useChannel es un react-hook para suscribirse a los mensajes de un canal Ably. Se le proporciona un nombre de canal y una llamada de retorno que se invocará cada vez que se reciba un mensaje.

A continuación, vas a formatear los datos para la pantalla, de modo que se pueda mostrar cada mensaje, junto con la hora a la que llegó y el número de teléfono del remitente.

   const messages = receivedMessages.map((message, index) => {
    console.log(message);
    let from = [message.data.from.slice(0, 2) + " " + message.data.from.slice(2, 6) +  " " + message.data.from.slice(6, 9) + " "+ message.data.from.slice(9)];
    let date = new Date(message.data.timestamp);
    let day = date.toDateString().replace(/^\S+\s/,'');
    let time = date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });

    return (
      <div key={index} className={styles.message}>
        <span className={styles.from}>{from}</span>
        <span className={styles.when}>{day}, {time}</span>
        <span className={styles.text}>{message.data.text}</span>
      </div>
    );
  });

Por último, cree su componente y devuélvalo:

  return (
    <div className={styles.chatHolder}>
      <h1 className={styles.title}>Text Messages</h1>
      <div className={styles.chatText}>
        {messages}
        <div ref={(element) => { messageEnd = element; }}></div>
      </div>
    </div>
  )
}

Justo al final del archivo, la función se exporta como SmsComponent para que pueda ser referenciada en la página de índice de Next.js.

Uso correcto de Ably en React Components

Una de las partes más complicadas de usar Ably con React Functional Components es saber cuándo y dónde crear la instancia del SDK y cuándo y dónde conectarse a tu(s) canal(es). Usted querrá evitar instanciar el SDK cuando el componente se renderiza, ya que esto podría hacer múltiples conexiones y quemar a través de sus límites de cuenta Ably.

Para asegurarse de que la aplicación gestiona correctamente el redibujado, montaje y desmontaje de componentes - AblyReactEffect exporta un React Hook para interactuar con el SDK de Ably.

Los hooks de React pueden parecer un poco inusuales la primera vez que los usas. Un gancho es una función que:

• Ejecuta la funcionalidad que cabría esperar componentDidMount ejecutar

• Devuelve otra función que será ejecutada por el framework donde componentDidUnmount sería llamada

• Realiza cualquier otro comportamiento que necesite

Este gancho React se basa en useEffect. Cuando se hace referencia a él, crea una instancia del SDK de Ably (sólo lo hace una vez) que está configurada para utilizar el archivo URL de su función Serverless para createTokenRequest para la autenticación:

import Ably from "ably/promises";
import { useEffect } from 'react'

const ably = new Ably.Realtime.Promise({ authUrl: '/api/createTokenRequest' });

Instanciar la biblioteca Ably fuera del ámbito del componente significa que sólo se crea una vez y mantendrá bajo el uso de límites.

A continuación, tienes que crear la función que vas a exportar, tu gancho, para utilizarla en tu componente. Llamémosla useChannelrequerirá el nombre del canal y una llamada de retorno como argumentos. Cada vez que useChannel es llamada, se get el canal solicitado desde el SDK de Ably-JS y prepara las funciones hook.

• onMount es el código que se ejecuta cada vez que se renderiza el componente. Dentro de onMount, se suscribirá al canal especificado, disparando callbackOnMessage cada vez que se reciba un mensaje.

• onUnmount es el código que se ejecuta cada vez que se desmonta el componente antes de que se vuelva a renderizar. Aquí se dará de baja del canal, lo que detendrá las conexiones múltiples accidentales, salvando de nuevo nuestros límites de Account.

• useEffectHook es una función que llama a estas funciones correctamente, devolviendo onUnmount para que React lo use.

El gancho exportado en AblyReactEffect.js tendrá el siguiente aspecto:

export function useChannel(channelName, callbackOnMessage) {
    const channel = ably.channels.get(channelName);

    const onMount = () => {
        channel.subscribe(msg => { callbackOnMessage(msg); });
    }

    const onUnmount = () => {
        channel.unsubscribe();
    }

    const useEffectHook = () => {
        onMount();
        return () => { onUnmount(); };
    };

    useEffect(useEffectHook);

    return [channel, ably];
}

El useChannel Hook devuelve tanto el canal actual de Ably como el SDK de Ably para que el código que llama lo utilice para enviar mensajes. Este hook encapsula Ably pub/sub para componentes funcionales React en un solo lugar, por lo que no necesitas preocuparte por ello en otro lugar, y el código que lo utiliza puede procesar los mensajes que recibe.

Cómo hacer que todo luzca bonito con el módulo CSS -SmsComponent.module.css

Al escribir el componente de chat, te habrás dado cuenta de que Next.js tiene algunas convenciones impuestas por el compilador que dictan dónde guardar el CSS y cómo importarlo.

Para esta aplicación, cree un archivo CSS con el mismo nombre que el archivo .jsx sólo que con las extensiones .module.cssEsto facilita la gestión del componente. Si desea eliminar este componente en el futuro, es agradable y simple para eliminar su CSS también.

Una vez creado, puede importarse al componente:

import styles from './SmsComponent.module.css';

Al crear una clase CSS en un elemento JSX, utilice la siguiente sintaxis en el elemento:

className={styles.yourClassName}

y el CSS que lo acompaña tendría este aspecto:

.yourClassName {
  styles: gohere;
}

Alojamiento en Vercel

Estamos utilizando Vercel como nuestro servidor de desarrollo.

La forma más sencilla de desplegar Next.js en producción es utilizar la plataforma Vercel de los creadores de Next.js. Vercel es una plataforma todo-en-uno con CDN Global que soporta despliegue estático & Jamstack y Funciones Serverless. -- La documentación de Next.js

Para desplegar tu nueva aplicación sms-in-the-browser en Vercel, necesitarás:

1. Crear una cuenta de GitHub (si aún no tienes una)

2. Publica tu aplicación en un repositorio de GitHub

3. Crear una Account Vercel

4. Crea una nueva aplicación Vercel e importa tu aplicación desde tu repositorio GitHub. (Esto requerirá que autorices a Vercel a utilizar tu Account de GitHub).

5. Añada su ABLY_API_KEY como variable de entorno

6. Vea cómo se despliega su aplicación

7. Visite la URL recién creada en su navegador.

Configurar un número de SMS para su aplicación

Para recibir mensajes SMS, deberás alquilar un número de teléfono virtual de Vonage y configurarlo.

Primero, inicia sesión en tu Account de Vonage visitando el tablero. Una vez que hayas creado y verificado tu Account, puedes comprar un número yendo a Numbers => Buy Numbers. Busca un número que te convenga y agrega algunos créditos para pagar el número.

Una vez que haya adquirido su número, deberá configurar la opción SMS Inbound Webhook URL.

Para ello, vaya a Numbers => Sus números => Haga clic en el icono del bolígrafo.

Aparecerá un cuadro de diálogo modal en el que deberás introducir la URL de tu acceptWebhook URL de la API en el cuadro.

Si su aplicación Vercel se llama your-vercel-appla URL del webhook sería https://your-vercel-app.vercel.app/api/acceptWebhook.

Hazlo tuyo

Esta demo es de código abierto, bifúrcalo y hazlo tuyo. No te olvides de mostrarnos lo que construyes @ablyRealtime.

Si buscas formas de ampliar este proyecto, puedes considerar:

• Crear una aplicación de televoto

• Añadir una base de datos para almacenar mensajes

• Añadir la posibilidad de enviar un texto de respuesta.

Háganoslo saber

Si este tutorial te ha resultado útil, o si utilizas Next.js y Ably en tu proyecto, nos encantaría que nos lo contaras. Envíanos un mensaje en Twitter o envíanos un correo electrónico a devrel@ably.io.