Omnichannel-Gespräche mit Vonage, Postmark und Hookdeck

An einem einzigen Tag kann ich zwischen SMS für ein Gespräch mit einem Freund, WhatsApp für allgemeine Updates mit Familienmitgliedern, Facebook Messenger zur Koordinierung einer Gemeinschaftsaktivität und E-Mail für die Arbeit wechseln. Und der bevorzugte Kommunikationskanal kann sich je nach Person, Tageszeit, Geografie, Generation und Kultur unterscheiden. Wäre es nicht schön, wenn es eine einzige Kommunikationsanwendung gäbe, die jeder nutzen könnte und die über alle Kommunikationskanäle hinweg gut funktioniert!

Omnichannel-Konversationen - also Konversationen über verschiedene Kommunikationsmedien hinweg - sind eine Möglichkeit, aber es gibt nur wenige Anleitungen, die zeigen, wie man sie in die Praxis umsetzt. In diesem Tutorial zeigen wir Ihnen, wie Sie eine OmniText-Lösung aufbauen, um eine Konversation über SMS zu ermöglichen, indem Sie die Vonage Messages API und E-Mail mit der Postmark E-Mail-API. Wir verwenden auch Hookdeckeine serverlose asynchrone Messaging-Plattform, um Webhooks zu empfangen und Vonage und Postmark über ihre APIs zu integrieren.

Wenn Sie OmniText einfach nur ausprobieren möchten, können Sie den Code zusammen mit einer vereinfachten Anleitung in der OmniText-Repositorium auf GitHub.

OmniText Übersicht

Bevor wir Sie Schritt für Schritt durch die Konfiguration und den Aufbau der Lösung führen, erhalten Sie hier einen Überblick über die Funktionsweise von OmniText.

Hookdeck hat das Konzept der Verbindungendie einen als Quelle bezeichneten Eingang mit einer Quelle mit einem Ausgang namens Ziel. Um eine Konversation zwischen SMS und E-Mail zu unterstützen, benötigen wir zwei Verbindungen, die:

1. Empfang einer SMS und Auslösung einer E-Mail

2. Empfang einer E-Mail und Auslösung einer SMS

Connections in Hookdeck

Bei dieser Einrichtung unterstützen wir ein einziges Gespräch zwischen einer Telefonnummer und einer E-Mail. Um mehrere Konversationen mit diesem Ansatz zu unterstützen, müssten Sie zwei Verbindungen für jede Konversation erstellen. Wie bereits erwähnt, ist die Unterstützung mehrerer Konversationen durchaus möglich, wird aber in diesem Artikel nicht behandelt.

Für beide Verbindungen werden die Hookdeck Transformationen.

• Die inbound-sms Verbindung wandelt die eingehende Vonage Messages API SMS-Webhook-Nutzlast in eine Nutzlast um, die zum Senden einer E-Mail mit Postmark verwendet wird.

• Die inbound-email Verbindung wandelt die eingehende Postmark-E-Mail-Nutzlast in eine Struktur um, die von der Vonage Messages API zum Senden einer SMS benötigt wird

Wenn Sie eine E-Mail senden, sollten Sie auch beachten, dass Sie zwar E-Mail-Betreffs und Unteradressierung verwendet werden kann, um eine einzelne E-Mail-Adresse mit mehreren Konversationen zu verknüpfen, ist dies bei Telefonnummern und SMS-Nachrichten ein viel schwierigeres Problem. Bei dieser Lösung kann eine Telefonnummer also nur mit einem einzigen Gespräch verknüpft werden.

Voraussetzungen

Bevor Sie beginnen, melden Sie sich für kostenlose Konten bei den Diensten an, die für die OmniText-Lösung erforderlich sind, und holen Sie sich die entsprechenden Anmeldedaten und zusätzlichen Details:

• Vonage: Notieren Sie sich Ihren API-Schlüssel und Ihr API-Geheimnis. Sie müssen auch eine Telefonnummer kaufen, um SMS-Nachrichten zu senden und zu empfangen.

• Poststempel: Notieren Sie sich das API-Token Ihres Servers unter Server > {Ihr Servername} > API-Tokens und die eingehende E-Mail von Server > {Ihr Servername} > Standard-Eingangsstrom > Einstellungen > Eingang > E-Mail Abschnitt. Siehe die Postmark Konfigurieren eines Inbound-Servers für weitere Details. Denken Sie auch daran, Ihre Signatur mit Postmark zu verifizieren, d. h. Ihre E-Mail-Adresse zu überprüfen.

• Hakendeck: einfach den Account erstellen

Empfang einer SMS und Auslösung einer E-Mail

Beginnen wir damit, eine Verbindung herzustellen, die den folgenden Ablauf unterstützt:

1. Ein Benutzer sendet eine SMS an Ihre Vonage API-Telefonnummer

2. Die Vonage API löst einen SMS-Webhook an Hookdeck aus

3. Hookdeck empfängt die SMS-Webhooks über eine Quell-URL und konvertiert die SMS-Nutzdaten in ein Format, das für den Versand einer E-Mail mit Postmark verwendet werden kann.

4. Hookdeck stellt eine HTTP-Anfrage an eine Ziel-URL, den E-Mail-API-Endpunkt von Postmark, um eine E-Mail zu versenden

5. Ein zweiter Benutzer erhält die E-Mail

Gehen Sie zum Dashboard des Hakendecksund wählen Sie Verbindungenund klicken Sie auf die Schaltfläche + Verbindung Schaltfläche.

Auf der Seite Verbindung erstellen Seite, in der Spalte Konfigurieren Sie eine Quelledie Quelle auf. inbound-sms.

Unter Konfigurieren Sie ein Zielstellen Sie den Name auf outbound-email.

Für die Ein Ziel konfigurieren > Endpunkt-URLverwenden Sie den Postmark E-Mail-API-Endpunkt, https://api.postmarkapp.com/email.

Erweitern Sie Konfigurieren Sie ein Ziel > Erweiterte Konfigurationund wählen Sie API-Schlüssel in der Dropdown-Liste Authentifizierung, legen Sie den Parameter Name auf X-Postmark-Server-Tokenein und verwenden Sie Ihr Postmark-Server-API-Token als Wert für API-Schlüssel.

Authentication in Hookdeck for Postmark Request

Im Menü Verbindungsregeln festlegen Abschnitt klicken Sie auf Transformieren gefolgt von Neue Transformation erstellenund Sie sehen den browserinternen Transformationseditor.

Geben Sie den folgenden Text in das Textfeld für den Code ein:

const smsToEmail = (request, context) => {
 const replyToEmail = process.env.REPLY_TO_EMAIL;
 const fromEmail = process.env.FROM_EMAIL;
 const toEmail = process.env.TO_EMAIL;
 const subject = process.env.SUBJECT;


 const domain = toEmail ? toEmail.replace(/.*@/, "") : "example.com";
 const conversationId = `<omnitext/conversation/1@${domain}>`;


 const postmarkSendEmailRequest = {
   From: fromEmail,
   To: toEmail,
   ReplyTo: replyToEmail,
   Subject: subject,
   TextBody: request.body.text,
   MessageStream: "outbound",


   Headers: [
     {
       Name: "Message-ID",
       Value: conversationId,
     },
   ],
 };


 request.body = postmarkSendEmailRequest;


 return request;
};


addHandler("transform", smsToEmail);

Der Großteil des Codes befindet sich in einer Funktion namens smsToEmail. Hier ist ein Überblick über die Funktionsweise des Codes:

Zunächst werden Sie feststellen, dass der Transformationscode eine Reihe von Umgebungsvariablen mit der Syntax process.env.VARIABLE_NAME. Dies macht Gebrauch von Hookdeck Transformations-Umgebungsvariablen die zum Speichern von Geheimnissen verwendet werden.

Öffnen Sie die Variablen und erstellen Sie die folgenden Variablen mit Ihren Werten aus dem Abschnitt Voraussetzungen:

• REPLY_TO_EMAIL: Die Postmark-E-Mail, um sicherzustellen, dass E-Mail-Antworten an Postmark gehen und einen Webhook auslösen

• FROM_EMAIL: Setzen Sie dies auf denselben Wert wie REPLY_TO_EMAIL oder die E-Mail, mit der Sie sich für Postmark angemeldet haben. Wenn Sie das Senden von E-Mails von anderen Domains unterstützen möchten, müssen Sie Ihre Domain mit Postmark verifizieren. Dies kann nützlich sein, um E-Mail-Clients zu helfen, den Kontakt in einem Adressbuch zu identifizieren.

• TO_EMAIL: Die E-Mail-Adresse der Person, die die E-Mail empfängt, ist Teil der Konversation.

• SUBJECT: Der Betreff, der in der E-Mail verwendet werden soll. Sie können dies dynamischer gestalten, wenn Sie möchten.

Sobald die Umgebungsvariablen innerhalb von smsToEmail, a conversationId einen Wert mit einem Inhalt und einem Format zugewiesen, das sicherstellt, dass E-Mails innerhalb eines E-Mail-Clients im selben Thread gehalten werden (weitere Informationen finden Sie im den Artikel zur Unterstützung des Postmark-Threadings und diesen Beitrag über Versenden von E-Mails mit Thread in Rails).

Dann wird die E-Mail-API-Nutzlast erstellt und der postmarkSendEmailRequest Variable zugewiesen. Die wichtigsten Punkte, die in dieser Nutzlast beachtet werden müssen, sind:

• TextBody wird auf den in der SMS gesendeten Text gesetzt

• MessageStream ist gesetzt auf outbound um Postmark mitzuteilen, dass der transaktionale (ausgehende) Stream zum Senden der E-Mail verwendet werden soll

• Die Headers enthalten eine Kopfzeile namens Message-ID mit dem Wert, der aus der Datei conversationId. Wie bereits erwähnt, wird dies verwendet, um E-Mail-Clients bei der Einordnung von E-Mails zu helfen.

request.body wird der Wert der E-Mail-Nutzdaten des Poststempels zugewiesen, postmarkSendEmailRequest. Dieser wird dann in der nachfolgenden Anfrage verwendet, die an das Ziel der Verbindung, den Postmark-E-Mail-API-Endpunkt, gesendet wird.

Die transformierte request wird von der Funktion zurückgegeben und in der Anfrage an die Postmark-API verwendet, wie im Ziel der Verbindung festgelegt. Der addHandler Aufruf weist Hookdeck an, die Funktion smsToEmail jedes Mal aufzurufen, wenn eine transform behandelt werden soll.

Klicken Sie auf Bestätigen Sie, benennen Sie die Transformation vonage-sms-to-postmark-emailund klicken Sie auf Bestätigen um zur Seite Verbindungsaufbau zurückzukehren.

Unter Verbindungsname festlegeneingeben sms-to-email. Klicken Sie abschließend auf +Erstellen um die Verbindung zu erstellen.

Successful Connection Created

Kopieren Sie die Quell-URL aus dem angezeigten Dialogfeld und gehen Sie zum Vonage APIs Dashboard.

Wählen Sie im Vonage API Dashboard die Option Applications auf der linken Seite und klicken Sie auf + Erstellen einer neuen Anwendung.

Nennen Sie Ihre Bewerbung sms-to-email. In der Rubrik Fähigkeiten Abschnitt, aktiviert Meldungenund fügen Sie die URL Ihrer Hookdeck-Quelle in das Feld Eingehende URL und Status-URL Felder ein. Klicken Sie schließlich auf Neue Anwendung generieren.

Add Hookdeck webhook to Messages API Application

Auf dem nächsten Bildschirm sehen Sie Ihre Vonage-Telefonnummer. Verknüpfen Sie diese mit der Anwendung, die Sie gerade erstellt haben, indem Sie auf verknüpfen..

Link Your Messages API to Your Number

Senden Sie nun eine SMS an Ihre Vonage-Nummer.

Test Your First Working OmniText

Kehren Sie zum Hookdeck Dashboard zurück. Sobald Hookdeck den SMS-Webhook empfängt, wird die Benutzeroberfläche aktualisiert und zeigt das empfangene Webhook-Ereignis wie folgt an

Hookdeck Successful Event Fired

Klicken Sie auf Alle Ereignisse anzeigen und wählen Sie das Ereignis in der Tabelle aus, um weitere Details anzuzeigen.

Detailed Hookdeck Events Dashboard

Prüfen Sie als nächstes Ihre E-Mail:

Successful SMS to Email

Das war's. Die SMS-zu-E-Mail-Funktionalität ist vorhanden.

Empfang einer E-Mail und Auslösung einer SMS

Um nun die Verbindung zu erstellen, die den Fluss unterstützt, gilt das Gleiche wie zuvor, nur in umgekehrter Reihenfolge:

1. Ein Benutzer sendet eine E-Mail an eine mit Postmark verbundene E-Mail

2. Poststempel löst einen Webhook für eingehende E-Mails aus

3. Hookdeck empfängt den eingehenden E-Mail-Webhook und konvertiert die Nutzlast einer ausgehenden Voange API SMS-Nutzlast

4. Hookdeck stellt eine HTTP-Anfrage an eine Ziel-URL, den Endpunkt der Vonage Messages API, um eine SMS zu versenden

5. Ein zweiter Benutzer erhält die SMS

Rufen Sie wie bisher das Dashboard von Hookdeckund wählen Sie Verbindungenund klicken Sie auf die Schaltfläche + Verbindung Schaltfläche.

Auf der Seite Verbindung erstellen Seite, in der Spalte Konfigurieren Sie eine Quelle geben Sie der Quelle den Bereich Namen inbound-email.

Unter Konfigurieren Sie ein Zielverwenden Sie das Feld Name outbound-sms und setzen Sie die Endpunkt-URL auf den Vonage Messages API Endpunkt, https://api.nexmo.com/v1/messages.

Erweitern Sie Konfigurieren Sie ein Ziel > Erweiterte Konfigurationund wählen Sie Grundlegende Autorisierung aus der Liste Authentifizierung und verwenden Sie Ihren Vonage API-Schlüssel als Benutzername und das Vonage-API-Geheimnis als Kennwort.

Vonage API Authentication in Hookdeck

Im Menü Verbindungsregeln festlegen Abschnitt klicken Sie auf Transformieren gefolgt von Neue Transformation erstellenund Sie sehen wie zuvor den Transformationseditor im Browser.

Kopieren Sie den folgenden Transformationscode und fügen Sie ihn in den Editor ein:

const emailToSms = (request, context) => {
 const toNumber = process.env.TO_NUMBER;
 const fromNumber = process.env.FROM_NUMBER;


 const vonageRequestPayload = {
   message_type: "text",
   text: request.body.StrippedTextReply || request.body.TextBody,
   to: toNumber,
   from: fromNumber,
   channel: "sms",
 };
 request.body = vonageRequestPayload;


 return request;
};


addHandler("transform", emailToSms);

Der Großteil des Codes besteht aus einer Funktion. Dieses Mal heißt sie emailToSms.

Beginnen Sie, wie zuvor, mit dem Speichern der folgenden Umgebungsvariablen über die Datei Variablen Dropdown:

• TO_NUMBER: Die Telefonnummer des Empfängers der SMS

• FROM_NUMBER: Die Vonage-Telefonnummer, die zum Senden der SMS verwendet wird

Telefonnummern sollten mit der internationalen Landesvorwahl, aber ohne führendes + oder 00 formatiert werden.

Der Rest des Codes hat folgende Aufgaben:

A vonageRequestPayload Variable wird erstellt und enthält die Nutzlast der Messages API-Anforderung. Die Variable message_type hat einen Wert von textund die channel hat einen Wert von sms um anzugeben, dass eine SMS-Nachricht gesendet werden soll. Die Eigenschaft text Eigenschaft ist der Inhalt der SMS, und der Wert ist gesetzt auf request.body.StrippedTextReply oder, falls dieser nicht ausgefüllt ist, die Eigenschaft request.body.TextBody. Die StrippedTextReply ist der E-Mail-Text einer Antwort, der nur den Teil der neuen Nachricht und nicht den gesamten E-Mail-Thread enthält.

Der request.body wird der Wert der Variable vonageRequestPayload zugewiesen, und die Anfrage wird zurückgegeben, um in der Anfrage an das Ziel der Verbindung, den Vonage Messages API-Endpunkt, verwendet zu werden. Der addHandler Aufruf weist Hookdeck an, den emailToSms jedes Mal aufzurufen, wenn eine transform behandelt werden soll.

Klicken Sie auf Bestätigen Sie, benennen Sie die Transformation postmark-email-to-vonage-sms und klicken Sie Bestätigen um zur Seite Verbindungsaufbau zurückzukehren.

Unter Verbindungsname festlegeneingeben email-to-sms. Klicken Sie abschließend auf +Erstellen um die Verbindung zu erstellen.

Email to SMS Connection Created

Kopieren Sie die Quell-URL aus dem Dialog, wechseln Sie zum Postmark-Dashboard und gehen Sie zu Server > {Ihr Servername} > Standard-Eingangsstrom > Einstellungen Abschnitt. Scrollen Sie nach unten zum Abschnitt Eingehender Webhook und fügen Sie die URL in das Feld Eingehender Webhook Feld ein und Speichern Sie die Änderungen.

Postmark Webhook Connecting to Hookdeck

Senden Sie eine E-Mail an die Postmark-Eingangsadresse. Sie können dies tun, indem Sie auf die E-Mail antworten, die Sie im vorherigen Schritt erhalten haben.

Successful Programmatic Email Thread Reply

Nachdem Sie die E-Mail versendet haben, kehren Sie zum Hookdeck Dashboard zurück und sehen, dass das Webhook-Ereignis von Postmark empfangen wurde.

Hookdeck Successful Email to SMS Event

Klicken Sie auf Alle Ereignisse anzeigen, wählen Sie das Ereignis in der Tabelle aus, und prüfen Sie die Details des eingehenden Postmark-Webhooks.

Hookdeck Email to SMS Events Detailed

Überprüfen Sie Ihre SMS-Nachrichten, um den E-Mail-Text in der SMS-Nachricht zu sehen:

Successful Email to SMS

Sie können auch versuchen, erneut per SMS zu antworten, um sicherzustellen, dass die Konversation in Ihrem E-Mail-Client als Thread angezeigt wird:

Successful SMS reply to Email Thread

In Ihrer E-Mail sollten Sie also das Thema sehen:

Successful Threading in Email From SMS

Schlussfolgerung

In diesem Tutorial haben wir eine Verbindung in Hookdeck erstellt, die einen SMS-Webhook von der Vonage Messages API empfängt, die Nutzdaten in eine Postmark E-Mail-API-Anfrage umwandelt und den Text der SMS als Text einer E-Mail versendet. Dann haben wir eine zweite Hookdeck-Verbindung erstellt, die einen Postmark-E-Mail-Webhook empfängt. Wir wandeln die Nutzlast in eine Anforderungsnutzlast für die Vonage Messages API um und senden den Text der E-Mail als Inhalt einer SMS-Nachricht. In allen Fällen werden die API-Anmeldeinformationen sicher in Hookdeck gespeichert.

Und damit haben Sie nun eine Omnichannel-Konversationslösung geschaffen, die SMS und E-Mail miteinander verbindet.

Die OmniText-GitHub-Repositorium enthält den Code, der zeigt, wie man ein Skript für die Einrichtung der Verbindungen in Hookdeck erstellt. Probieren Sie das ruhig als Alternative für die Arbeit mit Hookdeck aus.

In diesem Artikel wurde das Hookdeck-Dashboard verwendet, um die Funktionalität zu erreichen, die zur Unterstützung eines einzelnen Gesprächs zwischen einer vordefinierten Telefonnummer und einer E-Mail erforderlich ist. Alles, was wir getan haben, kann jedoch auch mit der Hookdeck-API. Die programmatische Erstellung neuer Verbindungen ist ein möglicher Ansatz, um mehrere Gespräche zu unterstützen, oder Sie könnten eine bidirektionale Suche von E-Mail zu SMS bei einer Art von Gesprächsregistrierungsereignis speichern.

Wenn Sie nach einer Low-Code/No-Code-Lösung suchen, sollten Sie einen Blick auf Vonage API Studio.

Einige andere Dinge, die Sie mit den in diesem Artikel verwendeten Technologien ausprobieren können, sind:

• Hinzufügen von Webhook-Verifizierung zu den Webhooks für eingehende Postmark- und Vonage-Nachrichten

• Die Verwendung der Hookdeck CLI um die Webhooks in Ihrer lokalen Entwicklungsumgebung zu empfangen (ähnlich dem, wofür ngrok am besten bekannt ist)

• Schaffung eines 2., 3. und n-ten Gesprächs. Fühlen Sie sich frei, mögliche Lösungen zu diskutieren, indem Sie ein Thema erstellen im OmniText-Repositorium erstellen.

• Hinzufügen von Unterstützung für andere Messaging-Kanäle wie WhatsApp, Facebook Messenger und Viber unter Verwendung der Vonage Messages API

Was auch immer Sie als Nächstes vorhaben, wir wollen es wissen! Schließen Sie sich uns auf dem Vonage Entwickler-Community Slack oder schreiben Sie uns auf X, früher bekannt als Twitter.