Introducción

La SMS API de Vonage te permite enviar y recibir mensajes de texto desde y hacia usuarios de todo el mundo, usando nuestras API REST. En este tutorial, nos centraremos en el envío y la recepción de mensajes SMS y en el manejo de los recibos de entrega con Next.js utilizando la SMS API. Next.js es un framework React para crear aplicaciones web completas. Utiliza React Components para el desarrollo de la interfaz de usuario e incorpora funciones adicionales y optimizaciones a través de Next.js. Si estás interesado en obtener más información, puedes acceder a la Documentación de SMS API de Vonage.

tldr; Si quieres saltarte el proceso e ir directamente a desplegarla, puedes encontrar todo el código de la aplicación en GitHub.

Requisitos previos

Este tutorial asume que tienes un conocimiento básico de Git, Next.js, React y JavaScript. Antes de empezar, asegúrate de tener lo siguiente:

• Cuenta de API de Vonage - Ingresa a tu panel de API de Vonage para localizar tu clave y secreto de API, que se encuentran en la parte superior de la página.

• Número virtual de Vonage - Alquila un número de teléfono virtual para enviar o recibir mensajes y llamadas.

• Node.js 18.17 o posterior - Node.js es un entorno de ejecución JavaScript multiplataforma de código abierto.

• Plataforma de despliegue como Vercel, Netlifyetc. - Configuraremos webhooks para las URLs que reciben SMS entrantes y recibos de entrega. De esta forma, podremos recibir SMS y gestionar los recibos de entrega.

Cómo enviar un SMS con Next.js

Para la sección inicial de este tutorial, exploraremos cómo enviar mensajes de texto utilizando Next.js. Utilizaremos la SMS API de Vonage para interactuar con Next.js. Para enviar un SMS con Next.js y la SMS API de Vonage, sigue estas instrucciones:

1. Cómo crear un nuevo proyecto Next.js

2. Cómo declarar variables de entorno

3. Cómo instalar el SDK de Vonage Node.js

4. Cómo instalar la biblioteca de validación Zod

5. Cómo crear un formulario sólo para servidor

6. Cómo ejecutar el servidor de desarrollo

7. Cómo implantarse en Vercel

1. Cómo crear un nuevo proyecto Next.js

Para crear una aplicación Next.js, ejecuta:

Durante la instalación, verás las siguientes indicaciones:

En este tutorial, utilizaremos el App Router y JavaScriptpor lo que puedes elegir las mismas respuestas que arriba. Después de las indicaciones, create-next-app creará una carpeta con el nombre de tu proyecto e instalará las dependencias necesarias.

2. Cómo declarar variables de entorno

Recupere su clave y secreto de API de su configuración de APITambién puede obtener su número virtual en la página su página de Numbersy cree un archivo .env.local con las siguientes variables de entorno:

VONAGE_API_KEY=your-vonage-api-key
VONAGE_API_SECRET=your-api-secret
VONAGE_VIRTUAL_NUMBER=your-virtual-number

Para alquilar un número virtual de Vonage:

1. Inicie sesión en el panel del desarrollador.

2. En el menú de navegación de la izquierda, haga clic en Numbers y, a continuación, Comprar Numbers.

3. Elija los atributos que necesite y haga clic en Buscar en.

   1. En este tutorial sólo necesitamos la capacidad de SMS. Pero puedes utilizar el mismo número para añadir otras funciones de voz.

4. Haga clic en el botón Comprar junto al número que desee y valide su compra.

5. Su número virtual aparece ahora en Sus Numbers.

Consulte alquilar un número virtual.

3. Cómo instalar el SDK de Vonage Node.js

Usaremos el SDK de Vonage Node.js. Es muy fácil enviar un SMS con Next.js.

Para instalar el SDK de Node.js, ejecute:

4. Cómo instalar la biblioteca de validación Zod

Zod es una biblioteca de validación y declaración de esquemas de TypeScript. La usaremos para comprobar los valores después de enviar el formulario. Pero no es obligatorio, puedes saltarte este paso si lo deseas.

Para instalar el Zod, ejecute:

5. Cómo crear un formulario sólo para servidor

Cree una nueva carpeta llamada lib dentro de /app. A continuación, cree un nuevo archivo send-sms.js dentro de la carpeta lib con el siguiente contenido:

"use server";

import { revalidatePath } from "next/cache";
import { Vonage } from "@vonage/server-sdk";

Tras importar las dependencias, inicializa la biblioteca de nodos de Vonage instalada anteriormente:

const vonage = new Vonage({
  apiKey: process.env.VONAGE_API_KEY,
  apiSecret: process.env.VONAGE_API_SECRET,
});

const from = process.env.VONAGE_VIRTUAL_NUMBER;

A continuación inicializaremos la librería de nodos de Vonage, crearemos una función asíncrona llamada sendSMS:

export async function sendSMS(prevState, formData) {
  try {
    const vonage_response = await vonage.sms.send({
      to: formData.get("number"),
      from,
      text: formData.get("text"),
    }); 

    revalidatePath("/");
    return {
      response:
        vonage_response.messages[0].status === "0"
          ? `🎉 Message sent successfully.`
          : `There was an error sending the SMS. ${
              // prettier-ignore
              vonage_response.messages[0].error-text
            }`,
    };
  } catch (e) {
    return {
      response: `There was an error sending the SMS. The error message: ${e.message}`,
    };
  }
}

Para enviar un mensaje SMS usando la SMS API, usaremos el método vonage.messages.send de la biblioteca Vonage Node.js. Este método acepta objetos como parámetros que contienen información sobre el destinatario, el remitente y el contenido. La SMS API tiene dos tipos de respuesta (vonage_response), una es mensaje enviado y la otra es error. Consulta Respuestas SMS.

Ejemplo de respuesta para el Mensaje Enviado:

{
   "message-count": "1",
   "messages": [
      {
         "to": "447700900000",
         "message-id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
         "status": "0",
         "remaining-balance": "3.14159265",
         "message-price": "0.03330000",
         "network": "12345",
         "client-ref": "my-personal-reference",
         "account-ref": "customer1234"
      }
   ]
}

Ejemplo de respuesta para el Error:

{
   "message-count": "1",
   "messages": [
      {
         "status": "2",
         "error-text": "Missing to param"
      }
   ]
}

Invalidaremos todo un segmento de ruta con revalidatePathque permite purgar los datos almacenados en caché bajo demanda para una ruta específica. No devuelve ningún valor. Véase revalidatePath.

Para una validación más avanzada del lado del servidor, utilice la biblioteca Zod. Si la utiliza, el archivo send-sms.js debería tener este aspecto:

"use server";

import { revalidatePath } from "next/cache";
import { Vonage } from "@vonage/server-sdk";
import { z } from "zod";

const vonage = new Vonage({
  apiKey: process.env.VONAGE_API_KEY,
  apiSecret: process.env.VONAGE_API_SECRET,
});

const from = process.env.VONAGE_VIRTUAL_NUMBER;

const schema = z.object({
  number: z
    .string()
    .regex(new RegExp(/^\d{10,}$|^(\d{1,4}-)?\d{10,}$/), "Invalid Number!"),
  text: z.string().min(1, "Type something, please!").max(140, "Too long text!"),
});

export async function sendSMS(prevState, formData) {
  try {
    const data = schema.parse({
      number: formData.get("number"),
      text: formData.get("text"),
    });

    const vonage_response = await vonage.sms.send({
      to: data.number,
      from,
      text: data.text,
    }); 

    revalidatePath("/");
    return {
      response:
        vonage_response.messages[0].status === "0"
          ? `🎉 Message sent successfully.`
          : `There was an error sending the SMS. ${
              // prettier-ignore
              vonage_response.messages[0].error-text
            }`,
    };
  } catch (e) {
    return {
      response: `There was an error sending the SMS. The error message: ${e.message}`,
    };
  }
}

Para la interfaz de usuario, cree un nuevo archivo send-form.jsx dentro de /app con el siguiente contenido:

"use client";

import { sendSMS } from "@/app/lib/send-sms";
import { useFormStatus, useFormState } from "react-dom";

const initialState = {
  response: null,
};

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      aria-disabled={pending}
      className="border rounded-md hover:bg-slate-50 p-2 flex justify-center items-center"
    >
      {pending ? (
        <>
          <div class="border-gray-300 h-5 w-5 animate-spin rounded-full border-2 border-t-blue-600 mr-2" />
          Sending...
        </>
      ) : (
        "Send"
      )}
    </button>
  );
}

export function SendForm() {
  const [state, formAction] = useFormState(sendSMS, initialState);

  return (
    <form action={formAction} className="flex flex-col gap-y-2">
      <label htmlFor="number">Phone number:</label>
      <input
        name="number"
        id="number"
        type="number"
        placeholder="909009009099"
        autoComplete="off"
        className="border rounded p-2"
        required
      />
      <label htmlFor="text">Message:</label>
      <textarea
        name="text"
        id="text"
        rows={4}
        cols={40}
        placeholder="Hello from Next.js App!"
        className="border rounded p-2"
        required
      />
      <SubmitButton />
      <p aria-live="polite">{state?.response}</p>
    </form>
  );
}

Puede utilizar el hook useFormStatus para mostrar el estado de carga cuando se envía un formulario al servidor. Otro hook, el useFormStatele permite actualizar el estado basándose en el resultado de una acción del formulario.

Por último, puede importar el archivo send-form.jsx al directorio page.js dentro de /app.

import { SendForm } from "./send-form";

export default function Home() {
  return (
    <main className="mx-auto max-w-3xl my-3 p-3 border border-slate-300 shadow rounded-lg divide-y divide-solid">
      <header className="flex flex-row p-3 items-center justify-between">
        <img src="/vonage.svg" alt="Vonage" />
        <h2 className="text-lg font-medium">Send SMS with the Vonage APIs</h2>
      </header>
      <section className="pt-3">
        <SendForm />
      </section>
    </main>
  );
}

Nota: Puede encontrar el archivo vonage.svg en el repositorio de muestras.

6. Cómo ejecutar el servidor de desarrollo

En el primer paso de esta sección, creamos un directorio llamado vonage-send-sms. Ahora vamos a cd en él a través del terminal:

cd vonage-send-sms

A continuación, ejecute el siguiente comando:

npm run dev

Este comando inicia el servidor de desarrollo de su aplicación Next.js en el puerto 3000. Para ver tu página de inicio, abre http://localhost:3000 desde tu navegador. Debería tener este aspecto:

Next.js test form to send SMS

7. Cómo implantarse en Vercel

Usaremos Vercel para desplegar nuestra aplicación en este tutorial, pero también puedes desplegar tu proyecto con Netlify. Vercel tiene varias opciones para desplegar tu proyecto como Git, Vercel CLI, etc. El método más popular para crear un despliegue en Vercel es empujando código a repositorios Git, así que usaremos Git con GitHub. Puedes empezar a usarlo de forma gratuita.

Crear una Account GitHub

Para empezar a utilizar GitHub, crea una Account gratuita en GitHub.com y confirma tu dirección de correo electrónico.

Sube tu proyecto a GitHub

Antes del despliegue, vamos a subir nuestra aplicación Next.js a GitHub. El repositorio puede ser compartido con todo el mundo o mantenerse privado. No tienes que configurarlo con un README o cualquier otro archivo.

Para enviar a GitHub, ejecute estos comandos, sustituyendo <username> por su nombre de usuario de GitHub:

git remote add origin https://github.com/<username>/vonage-send-sms.git
git push -u origin main

Consulte esta guía en GitHub si necesitas ayuda para enviar tu aplicación.

Crear una Account Vercel

Para empezar a utilizar Vercel, visite https://vercel.com/signup para crear una Account Vercel. Seleccione Continuar con GitHub y siga el proceso de registro.

Vercel Sign Up Page

Importe suvonage-send-sms repositorio

Después de registrarte en Vercel y subir tu aplicación a GitHub, puedes importar tu repositorio a Vercel. Sólo necesitas darle acceso a tu repositorio, o a Todos los Repositorios en este paso. Puedes hacerlo aquí: https://vercel.com/import/git.

Vercel New Project Page

También puede desplegar el repositorio de ejemplo que hemos creado para usted en este paso en un solo paso con el botón desplegar Si lo desea. Pero no olvides definir las claves de las variables de entorno.

Cuando se complete la implementación, recibirás direcciones URL. Haz clic en uno de los enlaces para acceder al formulario de envío de SMS de Vonage en su versión activa. ¡Así de fácil!

Una vez que despliegue su aplicación, Vercel desplegará cada push por defecto.

Para enviar SMS a algunos países (como Turquía), los números virtuales deben cumplir la normativa específica del país. Consulta Funciones y restricciones específicas de cada país para obtener más información.

2. Cómo recibir SMS y recibos de entrega de SMS con Next.js

Cuando se solicita correctamente la API de SMS, ésta envía una serie de objetos de mensaje, cada uno de los cuales tiene un estado de 0 para indicar el éxito. Sin embargo, esto no garantiza que los destinatarios hayan recibido el mensaje. Para recibir recibos de entrega en nuestra aplicación Next.js, debemos proporcionar un punto final webhook para que Vonage los envíe.

1. Crear un punto final de webhook

2. Crear un gestor de peticiones POST

3. Añadir una respuesta al manejador

4. Configurar los ajustes de la API

5. Recibir un SMS y gestionar los recibos de entrega

1. Crear un punto final webhook

Cree una nueva carpeta llamada webhook dentro de /app. A continuación, cree otra carpeta nueva llamada status dentro de la webhook carpeta . A continuación, cree un nuevo archivo route.js archivo dentro de la status carpeta. La estructura de la carpeta debe tener este aspecto:

.
└── vonage-send-sms
    └── app
        ├── webhook
        │   └── status
        │       └── route.js
        ├── page.js
        └── layout.js

Como haremos exactamente lo mismo para capturar los SMS entrantes, crearemos otra carpeta llamada inbound con el archivo route.js bajo la carpeta webhook carpeta:

.
└── vonage-send-sms
    └── app
        ├── webhook
        │   ├── status
        │   │   └── route.js
        │   └── inbound
        │       └── route.js
        ├── page.js
        └── layout.js

2. Crear un gestor para las solicitudes POST

Crearemos un gestor de peticiones POST en /webhook/status para gestionar los recibos de entrega y en /webhook/inbound para gestionar los mensajes SMS entrantes. Después, registraremos el cuerpo de la petición en la consola:

export async function POST(request) {
    const res = await request.json();
    console.log("The request from Vonage: ", JSON.stringify(res, null, 2));
}

Ahora mismo, puedes ver el estado del mensaje en los registros y también añadir el estado del mensaje a tu base de datos o a otra cosa.

3. Añadir una respuesta al manejador

Vonage asumirá que no has recibido el mensaje y seguirá reenviándolo durante las próximas 24 horas. De esta manera, el punto final de webhook debe enviar un mensaje 200 OK o 204 No Content respuesta:

export async function POST(request) {
    const res = await request.json();
    console.log("The request from Vonage: ", JSON.stringify(res, null, 2));

    return new Response("ok", {
      status: 200,
    });
}

4. Configurar los ajustes de la API

Tu webhook endpoint es ahora desplegable en Vercel, Netlify o en tu propio servidor. Después de desplegar su aplicación, rellene cada campo añadiendo /webhook/inbound y /webhook/status a la URL de SMS entrantes y a la URL de recibos de entrega en la configuración de la API Configuración de la API.

Configure SMS API Setting

5. Recibir un SMS y gestionar los acuses de recibo

Para ver los recibos de entrega y los mensajes SMS entrantes en Vercel:

1. Elija su aplicación Next.js en el Panel Vercel.

2. Vaya a la vista general de su proyecto y seleccione la pestaña Registros.

3. Desde aquí, puede ver, filtrar y buscar los registros de tiempo de ejecución.

Vercel Runtime Logs

Ahora, envía un mensaje SMS a través de tu aplicación Next.js y deberías poder ver las solicitudes de Vonage en los registros de ejecución.

La respuesta de Vonage será algo parecido a esto:

{
  "msisdn": "905423247231",
  "to": "***9512387",
  "network-code": "28603",
  "messageId": "4a3cf988-570f-4cdb-95be-179f89c64498",
  "price": "0.02380000",
  "status": "failed",
  "scts": "2311031929",
  "err-code": "1",
  "api-key": "******",
  "message-timestamp": "2023-11-03 19:29:32"
}

Consulte Comprender el albarán de entrega.

Para ver cómo aparecen los mensajes SMS entrantes en el registro de la consola, envía un mensaje SMS desde tu teléfono a tu número de Vonage:

{
  "msisdn": "905423247231",
  "to": "***9512387",
  "messageId": "2B00000018726238",
  "text": "Hi! This is test message from Emre!",
  "type": "text",
  "keyword": "HI!",
  "api-key": "******",
  "message-timestamp": "2023-11-03 19:55:15"
}

Véase Anatomía de un mensaje entrante.

Conclusión

Ahora que sabes cómo enviar y recibir mensajes SMS y obtener recibos de entrega con la API de SMS de Vonage y Next.js. Considera la posibilidad de ampliar este proyecto respondiendo a mensajes SMS entrantes o añadiendo elementos interactivos más complejos.

Como siempre, no dudes en ponerte en contacto con nosotros en el Slack para desarrolladores de Vonage o en Twitter para cualquier pregunta o comentario. Gracias por leer y espero conectarme contigo la próxima vez.

Si te ha gustado este post, ¡ponte en contacto con Emre! Lleva mucho tiempo buscando trabajo :)

Otros recursos

• Habilitar Videollamada para una Aplicación Next.js Usando Vonage Video API

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

• Siguiente.js Acciones y mutaciones del servidor

• Siguiente.js Gestores de rutas