Introduction

L'API SMS API de Vonage vous permet d'envoyer et de recevoir des messages texte vers et depuis des utilisateurs du monde entier, à l'aide de nos API REST. Dans ce tutoriel, nous nous concentrerons sur l'envoi et la réception de messages SMS et la gestion des accusés de réception avec Next.js en utilisant l'API SMS. Next.js est un framework React qui permet de créer des applications web complètes. Il utilise React Components pour le développement de l'interface utilisateur et intègre des fonctionnalités supplémentaires et des optimisations via Next.js. Si vous souhaitez en savoir plus, vous pouvez accéder à la documentation de l'API SMS de Vonage.

tldr ; Si vous souhaitez passer directement au déploiement, vous pouvez trouver tout le code de l'application sur GitHub.

Conditions préalables

Ce tutoriel suppose que vous avez une compréhension de base de Git, Next.js, React et JavaScript. Avant de commencer, assurez-vous d'avoir les éléments suivants :

• Compte API Vonage - Accédez au tableau de bord de l'API de Vonage pour trouver votre clé et votre secret d'API, qui se trouvent en haut de la page.

• Numéro virtuel Vonage - Louez un numéro de téléphone virtuel pour envoyer ou recevoir des messages et des appels téléphoniques.

• Node.js 18.17 ou version ultérieure - Node.js est un environnement d'exécution JavaScript open-source et multiplateforme.

• Plate-forme de déploiement telle que Vercel, Netlifyetc. - Nous allons configurer des webhooks pour les URL qui reçoivent les SMS entrants et les accusés de réception. De cette manière, nous serons en mesure de recevoir des SMS et de gérer les accusés de réception.

Comment envoyer un SMS avec Next.js

Pour la première section de ce tutoriel, nous allons explorer comment envoyer des messages texte en utilisant Next.js. Nous utiliserons l'API SMS de Vonage pour interagir avec Next.js. Pour envoyer un SMS avec Next.js et l'API SMS de Vonage, suivez ces instructions :

1. Comment créer un nouveau projet Next.js

2. Comment déclarer des variables d'environnement

3. Comment installer le SDK Node.js de Vonage

4. Comment installer la bibliothèque de validation Zod

5. Comment créer un formulaire réservé au serveur

6. Comment faire fonctionner le serveur de développement

7. Comment déployer Vercel

1. Comment créer un nouveau projet Next.js

Pour créer une application Next.js, exécutez :

Lors de l'installation, les invites suivantes s'affichent :

Dans ce tutoriel, nous utiliserons l'outil App Router et JavaScriptvous pouvez donc choisir les mêmes réponses que ci-dessus. Après les invites, create-next-app créera un dossier avec le nom de votre projet et installera les dépendances nécessaires.

2. Comment déclarer des variables d'environnement

Récupérez votre clé et votre secret d'API dans vos paramètres APIVous pouvez également obtenir votre numéro virtuel à partir de la page page de vos Numberset créez un fichier .env.local avec les variables d'environnement suivantes :

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

Pour louer un numéro virtuel Vonage :

1. Se connecter au tableau de bord du développeur.

2. Dans le menu de navigation de gauche, cliquez sur Numbers puis Acheter des Numbers.

3. Choisissez les attributs dont vous avez besoin, puis cliquez sur Rechercher.

   1. Dans ce tutoriel, nous n'avons besoin que de la fonction SMS. Mais vous pouvez utiliser le même numéro pour ajouter d'autres fonctionnalités vocales !

4. Cliquez sur le bouton Acheter à côté du numéro désiré et validez votre achat.

5. Votre numéro virtuel est désormais répertorié dans Vos Numbers.

Voir louer un numéro virtuel.

3. Comment installer le SDK Node.js de Vonage

Nous utiliserons le SDK Node.js de Vonage. Il est si facile d'envoyer un SMS avec Next.js.

Pour installer le SDK Node.js, exécutez :

4. Comment installer la bibliothèque de validation Zod

Zod est une bibliothèque de déclaration et de validation de schémas en TypeScript. Nous l'utiliserons pour vérifier les valeurs après la soumission du formulaire. Mais ce n'est pas obligatoire, vous pouvez sauter cette étape si vous le souhaitez.

Pour installer le Zod, exécutez :

5. Comment créer un formulaire réservé au serveur

Créez un nouveau dossier appelé lib dans /app. Ensuite, créez un nouveau fichier send-sms.js à l'intérieur du dossier lib avec le contenu suivant :

"use server";

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

Après avoir importé les dépendances, initialisez la bibliothèque de nœuds Vonage installée précédemment :

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

const from = process.env.VONAGE_VIRTUAL_NUMBER;

Ensuite, pour initialiser la bibliothèque de nœuds de Vonage, nous allons créer une fonction asynchrone appelée 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}`,
    };
  }
}

Pour envoyer un SMS à l'aide de l'API SMS, nous utiliserons la méthode vonage.messages.send de la bibliothèque Node.js de Vonage. Cette méthode accepte comme paramètres des objets contenant des informations sur le destinataire, l'expéditeur et le contenu. L'API SMS propose deux types de réponses (vonage_response), l'une est le message envoyé et l'autre est l'erreur. Voir Réponses SMS.

Exemple de réponse pour le message envoyé :

{
   "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"
      }
   ]
}

Exemple de réponse pour l'erreur :

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

Nous allons invalider un segment d'itinéraire entier avec revalidatePathqui vous permet de purger les données mises en cache à la demande pour un chemin spécifique. Elle ne renvoie aucune valeur. Voir revalidatePath.

Pour une validation plus avancée côté serveur, utilisez la bibliothèque Zod. Si vous l'utilisez, le fichier send-sms.js devrait ressembler à ceci :

"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}`,
    };
  }
}

Pour l'interface utilisateur, créez un nouveau fichier send-form.jsx dans /app avec le contenu suivant :

"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>
  );
}

Vous pouvez utiliser le crochet useFormStatus pour afficher un état de chargement lorsqu'un formulaire est soumis au serveur. Un autre crochet, le useFormStatevous permet de mettre à jour l'état en fonction du résultat d'une action de formulaire.

Enfin, vous pouvez importer le fichier send-form.jsx dans le fichier page.js à l'intérieur 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>
  );
}

Note : Vous trouverez le fichier vonage.svg dans le référentiel d'exemples : Vous trouverez le fichier vonage.svg dans le référentiel d'exemples.

6. Comment exécuter le serveur de développement

Dans la première étape de cette section, nous avons créé un répertoire appelé vonage-send-sms. Maintenant, entrons dans ce répertoire à l'aide du terminal cd dans ce répertoire à l'aide du terminal :

cd vonage-send-sms

Exécutez ensuite la commande suivante :

npm run dev

Cette commande lance le serveur de développement pour votre application Next.js sur le port 3000. Pour voir votre page d'accueil, ouvrez http://localhost:3000 dans votre navigateur. Elle devrait ressembler à ceci :

Next.js test form to send SMS

7. Comment déployer Vercel

Nous utiliserons Vercel pour déployer notre application dans ce tutoriel, mais vous pouvez également déployer votre projet avec Netlify. Vercel dispose de plusieurs options pour déployer votre projet comme Git, Vercel CLI, etc. La méthode la plus populaire pour créer un déploiement sur Vercel est de pousser le code vers les dépôts Git, nous utiliserons donc Git avec GitHub. Vous pouvez commencer à l'utiliser gratuitement.

Créer un Account GitHub

Pour commencer à utiliser GitHub, créez un compte gratuit sur GitHub.com et confirmez votre adresse e-mail.

Transférez votre projet sur GitHub

Avant le déploiement, téléchargeons notre application Next.js sur GitHub. Le dépôt peut être partagé avec tout le monde ou rester privé. Vous n'avez pas besoin de le configurer avec un README ou d'autres fichiers.

Pour pousser vers GitHub, exécutez ces commandes, en remplaçant <username> par votre nom d'utilisateur GitHub :

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

Consultez ce guide sur GitHub si vous avez besoin d'aide pour pousser votre application.

Créer un Account Vercel

Pour commencer à utiliser Vercel, rendez-vous à l'adresse suivante https://vercel.com/signup pour créer un Account Vercel. Choisissez Continuer avec GitHub et suivez le processus d'enregistrement.

Vercel Sign Up Page

Importer votrevonage-send-sms dépôt

Une fois que vous êtes inscrit à Vercel et que vous avez poussé votre application sur GitHub, vous pouvez importer votre dépôt dans Vercel. Vous devez juste lui donner accès à votre dépôt, ou à Tous les dépôts dans cette étape. Vous pouvez le faire ici : https://vercel.com/import/git.

Vercel New Project Page

Vous pouvez également déployer l'exemple de référentiel que nous avons créé pour vous dans cette étape en une seule étape avec le bouton déployer si vous le souhaitez. Mais n'oubliez pas de définir les clés des variables d'environnement.

Une fois le déploiement terminé, vous recevrez des URL. Cliquez sur l'un des liens pour accéder au formulaire d'envoi de SMS de Vonage dans sa version en ligne. C'est aussi simple que cela !

Une fois que vous avez déployé votre application, Vercel déploie chaque poussée par défaut.

Pour envoyer des SMS dans certains pays (comme la Turquie), les numéros virtuels doivent être conformes aux réglementations nationales. Consultez la rubrique Fonctionnalités et restrictions propres à chaque pays pour plus d'informations.

2. Comment recevoir des SMS et des accusés de réception de SMS avec Next.js

Lorsque vous demandez avec succès l'API SMS, celle-ci vous envoie un tableau d'objets de message, chaque message ayant un statut de 0 pour indiquer le succès. Cependant, cela ne garantit pas que vos destinataires ont reçu le message. Pour recevoir des accusés de réception dans notre application Next.js, nous devons fournir un point de terminaison webhook pour que Vonage les envoie.

1. Créer un point de terminaison webhook

2. Créer un gestionnaire pour les requêtes POST

3. Ajouter une réponse au gestionnaire

4. Configurer les paramètres de l'API

5. Recevoir un SMS et gérer les accusés de réception

1. Créer un point de terminaison webhook

Créer un nouveau dossier appelé webhook à l'intérieur /app. Ensuite, créez un nouveau dossier appelé status à l'intérieur du dossier webhook . Ensuite, créez un nouveau route.js à l'intérieur du status à l'intérieur du dossier La structure du dossier doit ressembler à ceci :

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

Comme nous ferons exactement la même chose pour capturer les SMS entrants, nous créerons un autre dossier appelé inbound avec le fichier route.js sous le dossier webhook sous le dossier

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

2. Créer un gestionnaire pour les requêtes POST

Nous créerons un gestionnaire pour les demandes POST à l'adresse /webhook/status pour gérer les accusés de réception et à /webhook/inbound pour gérer les SMS entrants. Ensuite, nous enregistrerons le corps de la requête dans la console :

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

Actuellement, vous pouvez voir l'état des messages dans les journaux et ajouter l'état des messages à votre base de données ou autre.

3. Ajouter une réponse au gestionnaire

Vonage supposera que vous n'avez pas reçu le message et continuera à le renvoyer pendant les 24 heures suivantes. De cette façon, le point de terminaison du webhook doit envoyer un message de type 200 OK ou 204 No Content la réponse :

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. Configurer les paramètres de l'API

Votre point de terminaison webhook peut maintenant être déployé sur Vercel, Netlify ou votre propre serveur. Après avoir déployé votre application, remplissez chaque champ en ajoutant /webhook/inbound et /webhook/status à l'URL des SMS entrants et à l'URL des accusés de réception dans les paramètres de l'API. Paramètres de l'API.

Configure SMS API Setting

5. Recevoir un SMS et gérer les accusés de réception

Pour voir les accusés de réception et les SMS entrants sur Vercel :

1. Choisissez votre application Next.js dans le tableau de bord Vercel.

2. Allez dans l'aperçu de votre projet et sélectionnez l'onglet Logs.

3. À partir de là, vous pouvez consulter, filtrer et rechercher les journaux d'exécution.

Vercel Runtime Logs

Maintenant, envoyez un SMS via votre application Next.js et vous devriez être en mesure de voir les demandes de Vonage sur les journaux d'exécution.

La réponse de Vonage ressemblera à ceci :

{
  "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"
}

Voir Comprendre le récépissé de livraison.

Pour voir comment les SMS entrants apparaissent dans le journal de la console, envoyez un message SMS de votre téléphone à votre numéro 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"
}

Voir Anatomie d'un message entrant.

Conclusion

Maintenant que vous savez comment envoyer et recevoir des messages SMS et obtenir des accusés de réception avec l'API SMS de Vonage et Next.js. Envisagez de développer ce projet en répondant aux SMS entrants ou en ajoutant des éléments interactifs plus complexes.

Comme toujours, n'hésitez pas à nous contacter sur le Slack des développeurs de Vonage ou sur Twitter pour toute question ou commentaire. Merci d'avoir lu, et j'ai hâte d'être en contact avec vous la prochaine fois.

Si vous avez aimé cet article, contactez Emre ! Il est à la recherche d'un emploi depuis longtemps :)

Ressources complémentaires

• Activer les appels Video pour une application Next.js en utilisant l'API Video de Vonage

• Afficher les notifications SMS dans le navigateur avec Next.JS, Ably et Vercel

• Next.js Actions et mutations du serveur

• Next.js Gestionnaires de routes