Einführung

Die Vonage SMS API ermöglicht das Senden und Empfangen von Textnachrichten an und von Nutzern weltweit über unsere REST APIs. In diesem Tutorial werden wir uns auf das Senden und Empfangen von SMS-Nachrichten und die Bearbeitung von Zustellungsbestätigungen mit Next.js unter Verwendung der SMS API konzentrieren. Next.js ist ein React-Framework für die Erstellung von Full-Stack-Webanwendungen. Es verwendet React Components für die UI-Entwicklung und integriert zusätzliche Funktionen und Optimierungen über Next.js. Wenn Sie mehr darüber erfahren möchten, können Sie auf die Vonage SMS API-Dokumentation.

tldr; Wenn Sie den Vorgang überspringen und direkt mit dem Einsatz beginnen möchten, finden Sie den gesamten Code für die Anwendung auf GitHub.

Voraussetzungen

Dieses Tutorial setzt voraus, dass Sie ein grundlegendes Verständnis von Git, Next.js, React und JavaScript haben. Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:

• Vonage API-Konto - Greifen Sie auf Ihr Vonage API Dashboard zu, um Ihren API-Schlüssel und Ihr API-Geheimnis zu finden, die Sie oben auf der Seite finden.

• Virtuelle Nummer von Vonage - Mieten Sie eine virtuelle Rufnummer, um Nachrichten und Anrufe zu senden oder zu empfangen.

• Node.js 18.17 oder höher - Node.js ist eine plattformübergreifende Open-Source-JavaScript-Laufzeitumgebung.

• Bereitstellungsplattform wie Vercel, Netlifyusw. - Wir werden Webhooks für die URLs einrichten, die eingehende SMS und Zustellungsbestätigungen empfangen. Auf diese Weise werden wir in der Lage sein, SMS zu empfangen und Empfangsbestätigungen zu verarbeiten.

Wie man eine SMS mit Next.js versendet

Im ersten Teil dieses Tutorials werden wir untersuchen, wie man mit Next.js Textnachrichten versendet. Wir werden die Vonage SMS API verwenden, um mit Next.js zu interagieren. Um eine SMS mit Next.js und der Vonage SMS API zu versenden, folgen Sie bitte diesen Anweisungen:

1. Wie man ein neues Next.js-Projekt erstellt

2. Wie man Umgebungsvariablen deklariert

3. Wie installiert man das Vonage Node.js SDK

4. So installieren Sie die Validierungsbibliothek Zod

5. So erstellen Sie ein reines Serverformular

6. Wie man den Entwicklungsserver betreibt

7. Wie man Vercel einsetzt

1. Wie man ein neues Next.js-Projekt erstellt

Um eine Next.js-Anwendung zu erstellen, führen Sie aus:

Bei der Installation werden Sie die folgenden Eingabeaufforderungen sehen:

In diesem Tutorial werden wir den App-Router und JavaScriptverwenden, so dass Sie die gleichen Antworten wie oben wählen können. Nach den Eingabeaufforderungen, create-next-app einen Ordner mit Ihrem Projektnamen anlegen und die erforderlichen Abhängigkeiten installieren.

2. Wie man Umgebungsvariablen deklariert

Rufen Sie Ihren API-Schlüssel und Ihr API-Geheimnis aus Ihren API-Einstellungensowie Ihre virtuelle Nummer von der Seite Ihre Numbers-Seiteund erstellen Sie eine .env.local Datei mit den folgenden Umgebungsvariablen:

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

So mieten Sie eine virtuelle Vonage-Nummer:

1. Melden Sie sich an der Entwickler-Dashboard.

2. Klicken Sie im linken Navigationsmenü auf Numbers dann Numbers kaufen.

3. Wählen Sie die gewünschten Attribute und klicken Sie dann auf Suchen.

   1. In diesem Tutorial benötigen wir nur die SMS-Funktion. Aber Sie können die gleiche Nummer auch für andere Voice-Funktionen verwenden!

4. Klicken Sie die Kaufen neben der gewünschten Nummer und bestätigen Sie Ihren Kauf.

5. Ihre virtuelle Nummer ist jetzt aufgeführt in Ihre Numbers.

Siehe eine virtuelle Nummer mieten.

3. So installieren Sie das Vonage Node.js SDK

Wir werden das Vonage Node.js SDK verwenden. Es ist so einfach, eine SMS mit Next.js zu versenden.

Um das Node.js SDK zu installieren, führen Sie aus:

4. So installieren Sie die Validierungsbibliothek Zod

Zod ist eine Schema-Deklarations- und Validierungsbibliothek, die auf TypeScript basiert. Wir werden sie verwenden, um die Werte zu überprüfen, nachdem das Formular abgeschickt wurde. Dies ist jedoch nicht zwingend erforderlich, Sie können diesen Schritt auslassen wenn Sie wollen.

Um Zod zu installieren, führen Sie aus:

5. So erstellen Sie ein Server-Only-Formular

Erstellen Sie einen neuen Ordner namens lib innerhalb von /app. Erstellen Sie dann eine neue send-sms.js Datei innerhalb des Ordners lib mit folgendem Inhalt:

"use server";

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

Nachdem Sie die Abhängigkeiten importiert haben, initialisieren Sie die zuvor installierte Vonage-Knotenbibliothek:

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

const from = process.env.VONAGE_VIRTUAL_NUMBER;

Dann initialisieren wir die Vonage-Knotenbibliothek und erstellen eine asynchrone Funktion namens 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}`,
    };
  }
}

Um eine SMS-Nachricht über die SMS API zu senden, verwenden wir die vonage.messages.send Methode der Vonage Node.js-Bibliothek. Diese Methode akzeptiert Objekte als Parameter, die Informationen über den Empfänger, den Absender und den Inhalt enthalten. Die SMS API hat zwei Arten von Antworten (vonage_response), eine ist die gesendete Nachricht und die andere ist ein Fehler. Siehe SMS-Antworten.

Beispielantwort für die gesendete Nachricht:

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

Beispielantwort für den Fehler:

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

Wir werden ein ganzes Routensegment ungültig machen mit revalidatePathdie es Ihnen ermöglicht, zwischengespeicherte Daten für einen bestimmten Pfad auf Abruf zu löschen. Es wird kein Wert zurückgegeben. Siehe revalidatePath.

Für eine erweiterte serverseitige Validierung verwenden Sie die Zod-Bibliothek. Wenn Sie diese verwenden, sollte die send-sms.js Datei wie folgt aussehen:

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

Für UI, erstellen Sie eine neue send-form.jsx Datei innerhalb von /app mit folgendem Inhalt:

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

Sie können den useFormStatus können Sie einen Ladestatus anzeigen, wenn ein Formular an den Server übermittelt wird. Ein weiterer Hook, der useFormStateermöglicht es Ihnen, den Status basierend auf dem Ergebnis einer Formularaktion zu aktualisieren.

Schließlich können Sie die send-form.jsx Datei in das Verzeichnis page.js innerhalb von /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>
  );
}

Anmerkung: Die Datei vonage.svg finden Sie im Beispiel-Repository.

6. So führen Sie den Entwicklungsserver aus

Im ersten Schritt dieses Abschnitts haben wir ein Verzeichnis namens vonage-send-sms. Nun wollen wir cd über das Terminal in dieses Verzeichnis:

cd vonage-send-sms

Führen Sie dann den folgenden Befehl aus:

npm run dev

Dieser Befehl startet den Entwicklungsserver für Ihre Next.js-Anwendung auf Port 3000. Um Ihre Homepage zu sehen, öffnen Sie http://localhost:3000 in Ihrem Browser. Sie sollte wie folgt aussehen:

Next.js test form to send SMS

7. Wie man Vercel einsetzt

Für dieses Tutorial werden wir Vercel verwenden, um unsere App bereitzustellen, aber Sie können Ihr Projekt auch mit Netlify bereitstellen. Vercel bietet mehrere Optionen für die Bereitstellung Ihres Projekts, wie z. B. Git, Vercel CLI, etc. Die beliebteste Methode, um ein Deployment auf Vercel zu erstellen, ist das Pushen von Code in Git-Repositories, daher werden wir Git mit GitHub verwenden. Sie können es kostenlos nutzen.

Einen GitHub Account erstellen

Um GitHub zu nutzen, erstellen Sie einen kostenlosen Account auf GitHub.com und bestätigen Sie Ihre E-Mail-Adresse.

Veröffentlichen Sie Ihr Projekt auf GitHub

Vor der Bereitstellung laden wir unsere Next.js-Anwendung auf GitHub hoch. Das Repository kann mit allen geteilt oder privat gehalten werden. Sie müssen es nicht mit einer README oder anderen Dateien einrichten.

Um an GitHub zu pushen, führen Sie diese Befehle aus und ersetzen Sie <username> durch Ihren GitHub-Benutzernamen:

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

Schauen Sie sich diesen Leitfaden auf GitHub, wenn Sie Hilfe beim Pushen Ihrer Anwendung benötigen.

Einen Vercel Account erstellen

Um mit Vercel zu beginnen, besuchen Sie https://vercel.com/signup um einen Vercel Account zu erstellen. Wählen Sie Weiter mit GitHub und führen Sie den Registrierungsprozess durch.

Vercel Sign Up Page

Importieren Sie Ihrevonage-send-sms Repository

Nachdem Sie sich bei Vercel angemeldet haben und Ihre Anwendung auf GitHub veröffentlichen, können Sie Ihr Repository importieren in Vercel importieren. Du musst ihm nur Zugriff auf dein Repository geben, oder auf Alle Repositories in diesem Schritt. Du kannst das hier tun: https://vercel.com/import/git.

Vercel New Project Page

Wenn Sie möchten, können Sie das Beispiel-Repository, das wir in diesem Schritt für Sie erstellt haben, auch in einem Schritt über die Schaltfläche Bereitstellen bereitstellen. Vergessen Sie aber nicht, die Schlüssel der Umgebungsvariablen zu definieren.

Wenn die Bereitstellung abgeschlossen ist, erhalten Sie URLs. Klicken Sie auf einen der Links, um das Vonage-Formular für den SMS-Versand in seiner Live-Version aufzurufen. So einfach geht's!

Sobald Sie Ihre Anwendung bereitstellen, wird Vercel standardmäßig jeden Push bereitstellen.

Um SMS in einige Länder (wie die Türkei) zu senden, müssen virtuelle Numbers den länderspezifischen Bestimmungen entsprechen. Weitere Informationen finden Sie unter Länderspezifische Funktionen und Beschränkungen für weitere Informationen.

2. Wie man SMS und SMS-Zustellungsbestätigungen mit Next.js empfängt

Wenn Sie die SMS API erfolgreich angefordert haben, sendet sie Ihnen ein Array von Nachrichtenobjekten, wobei jede Nachricht einen Status von 0 um den Erfolg anzuzeigen. Dies ist jedoch keine Garantie dafür, dass Ihre Empfänger die Nachricht erhalten haben. Um Zustellungsbestätigungen in unserer Next.js-App zu erhalten, müssen wir Folgendes bereitstellen einen Webhook-Endpunkt zur Verfügung stellen, an den Vonage sie sendet.

1. Erstellen eines Webhook-Endpunkts

2. Erstellen Sie einen Handler für POST-Anfragen

3. Hinzufügen einer Antwort zum Handler

4. Konfigurieren Sie die API-Einstellungen

5. Empfang einer SMS und Bearbeitung von Zustellungsbestätigungen

1. Erstellen Sie einen Webhook-Endpunkt

Erstellen Sie einen neuen Ordner namens webhook innerhalb von /app. Dann erstellen Sie einen weiteren neuen Ordner mit dem Namen status innerhalb des webhook Ordner. Danach erstellen Sie eine neue route.js Datei innerhalb des status Ordner. Die Ordnerstruktur sollte wie folgt aussehen:

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

Da wir genau dasselbe tun werden, um eingehende SMS zu erfassen, erstellen wir einen weiteren Ordner namens inbound mit der Datei route.js Datei unter dem webhook Ordner:

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

2. Erstellen Sie einen Handler für POST-Anfragen

Wir werden einen Handler für POST-Anfragen unter /webhook/status um Zustellungsbestätigungen zu verarbeiten und unter /webhook/inbound um eingehende SMS-Nachrichten zu verarbeiten. Dann protokollieren wir den Text der Anfrage auf der Konsole:

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

Im Moment können Sie den Meldungsstatus in den Protokollen sehen und auch den Meldungsstatus zu Ihrer Datenbank oder etwas anderem hinzufügen.

3. Hinzufügen einer Antwort zum Handler

Vonage geht dann davon aus, dass Sie die Nachricht nicht erhalten haben und sendet sie in den nächsten 24 Stunden erneut. Auf diese Weise muss der Webhook-Endpunkt eine 200 OK oder 204 No Content Antwort senden:

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. Konfigurieren Sie die API-Einstellungen

Ihr Webhook-Endpunkt kann nun entweder auf Vercel, Netlify oder Ihrem eigenen Server bereitgestellt werden. Nachdem Sie Ihre Anwendung bereitgestellt haben, füllen Sie jedes Feld aus, indem Sie /webhook/inbound und /webhook/status an die URL für eingehende SMS und die URL für Zustellungsbelege in den API-Einstellungen.

Configure SMS API Setting

5. SMS empfangen und Empfangsbestätigungen bearbeiten

Um Zustellungsbelege und eingehende SMS-Nachrichten auf Vercel zu sehen:

1. Wählen Sie Ihre Next.js App aus dem Vercel Dashboard.

2. Gehen Sie zu Ihrer Projektübersicht und wählen Sie die Registerkarte Protokolle.

3. Von hier aus können Sie die Laufzeitprotokolle anzeigen, filtern und durchsuchen.

Vercel Runtime Logs

Senden Sie nun eine SMS-Nachricht über Ihre Next.js-Anwendung und Sie sollten die Anfragen von Vonage in den Laufzeitprotokollen sehen können.

Die Antwort von Vonage wird in etwa so aussehen:

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

Siehe Verstehen des Lieferscheins.

Um zu sehen, wie eingehende SMS-Nachrichten im Konsolenprotokoll erscheinen, senden Sie eine SMS-Nachricht von Ihrem Telefon an Ihre Vonage-Nummer:

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

Siehe Anatomie einer eingehenden Nachricht.

Schlussfolgerung

Jetzt wissen Sie, wie Sie mit der Vonage SMS API und Next.js SMS-Nachrichten senden und empfangen und Zustellungsbestätigungen erhalten können. Erwägen Sie, dieses Projekt zu erweitern, indem Sie auf eingehende SMS-Nachrichten antworten oder komplexere, interaktive Elemente hinzufügen.

Wie immer können Sie uns über den Vonage Entwickler-Slack oder Twitter für Fragen oder Feedback. Vielen Dank für die Lektüre und ich freue mich auf das nächste Mal mit Ihnen.

Wenn dir dieser Beitrag gefallen hat, melde dich bei Emre! Er ist schon seit langem auf der Suche nach einem Job :)

Weitere Ressourcen

• Videoanrufe für eine Next.js Applikation mit Vonage Video API aktivieren

• SMS-Benachrichtigungen im Browser anzeigen mit Next.JS, Ably und Vercel

• Weiter.js Server-Aktionen und Mutationen

• Weiter.js Route Handler