Vonage、Postmark、Hookdeckとのオムニチャネル対談

友人との会話にはSMS、家族との一般的な近況報告にはWhatsApp、コミュニティ活動の調整にはFacebookメッセンジャー、そして仕事にはEメールと、1日のうちに飛び回ることもある。そして、好みのコミュニケーション・チャンネルは、個人、時間帯、地域、世代、文化によって異なる。誰もが使えて、すべてのコミュニケーション・チャンネルでうまく機能するコミュニケーション・アプリケーションが1つあったらいいと思いませんか？

オムニチャネル・カンバセーション（コミュニケーション・メディアを横断した会話）は可能性がありますが、それを実践する方法を示すガイドはほとんどありません。そこで、このチュートリアルでは、VonageのMessages APIを使用してSMSをまたいだ会話を可能にするOmniTextソリューションを構築する方法を説明します。 Messages APIそして Postmark email API.また Hookdeckサーバーレスの非同期メッセージングプラットフォームであるHookdeckを使って、Webhookを受信し、API経由でVonageとPostmarkを統合します。

OmniTextを試してみたいだけなら、簡単な説明と一緒にコードをGitubの GitHubのOmniTextリポジトリ.

オムニテキストの概要

ソリューションの設定と構築をステップ・バイ・ステップで説明する前に、OmniTextがどのように機能するかの概要を説明します。

フックデッキにはコンセプトがある。 コネクションと呼ばれる入力を ソースと呼ばれる出力と デスティネーション.SMSとEメールを横断する会話をサポートするには、次の2つの接続が必要である：

1. SMSを受信してEメールを送信する

2. Eメールを受信し、SMSをトリガーする

Connections in Hookdeck

このセットアップでは、1つの電話番号と1つのEメールの間で1つの会話をサポートします。この方法で複数の会話をサポートするには、会話ごとに2つの接続を作成する必要があります。上述したように、複数の会話をサポートすることは十分に可能ですが、この記事では取り上げません。

どちらの接続もフックデッキを使用する。 変換.

• 接続は inbound-sms接続は、インバウンドの Vonage Messages API SMS ウェブフックのペイロードを、Postmark でメールを送信するためのペイロードに変換します。

• 接続は inbound-email接続は、受信した Postmark メールのペイロードを Vonage Messages API が SMS を送信するために必要な構造に変換します。

Eメールを送信する際、Eメールの件名やサブアドレスを使用することができる一方で、次のことにも注意する価値があります。 サブアドレスを使用することで、1つのEメールアドレスを複数の会話の一部にすることができますが、電話番号やSMSメッセージの場合は、これが非常に難しい問題です。そのため、このソリューションでは、電話番号は1つの会話にしか関連付けることができません。

前提条件

始める前に、OmniTextソリューションに必要なサービスの無料アカウントにサインアップし、それぞれの認証情報と追加情報を入手してください：

• ボンテージAPIキーとAPIシークレットを控えておいてください。また、SMSメッセージを送受信するために電話番号を購入する必要があります。

• 消印サーバーのAPIトークンは サーバー > {サーバー名} > APIトークンと受信メール サーバー > {サーバー名} > デフォルト受信ストリーム > 設定 > 受信 > Eメールセクションを参照してください。Postmark 受信サーバーの設定を参照してください。また、Postmarkで "Verify your signature"（署名をVerifyする）、つまりメールアドレスをVerifyすることを忘れないでください。

• フックデッキアカウントを作成する

SMSを受信してEメールをトリガーする

まず、以下の流れをサポートするコネクションを作ることから始めよう：

1. ユーザーがVonage APIの電話番号にSMSを送信します。

2. Vonage APIはHookdeckにSMS webhookをトリガーします。

3. HookdeckはSource URL経由でSMSウェブフックを受信し、SMSペイロードをPostmarkでメールを送信できるフォーマットに変換します。

4. Hookdeck は Postmark email API のエンドポイントである Destination URL に HTTP リクエストを行い、メールを送信します。

5. 2番目のユーザーがメールを受け取る

フックデッキのダッシュボード フックデックダッシュボードを選択し 接続を選択し + 接続ボタンをクリックします。

接続の作成 接続の作成ページで ソースの構成を呼び出します。 inbound-sms.

で デスティネーションの設定で 名前を outbound-email.

については 宛先を設定 > エンドポイントURLには EメールAPIエンドポイント, https://api.postmarkapp.com/email.

拡大する デスティネーションの設定 > 詳細設定を選択します。 APIキーを選択し パラメータ名に設定します。 X-Postmark-Server-Tokenに設定し、Postmark サーバ API トークンを APIキー.

Authentication in Hookdeck for Postmark Request

接続ルールの設定 接続ルールの設定セクションで 変換をクリックし、続いて 新しい変換を作成をクリックすると、ブラウザ内の変換エディタが表示されます。

コード・テキストエリアに以下を入力する：

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

コードの大部分は smsToEmail.以下は、このコードが何をするのかのウォークスルーである：

まず、変換コードが次の構文を使って多くの環境変数を取得していることに気づくだろう。 process.env.VARIABLE_NAME.これは Hookdeck の 変換環境変数を利用しています。

開く 変数ドロップダウンメニューを開き、前提条件のセクションで設定した値を使用して以下の変数を作成します：

• REPLY_TO_EMAIL:返信メールがPostmarkに届き、WebhookをトリガーするためのPostmarkメール

• FROM_EMAIL:と同じに設定してください。 REPLY_TO_EMAILまたはPostmarkに登録したメールと同じに設定してください。他のドメインからのメール送信をサポートしたい場合は ドメインをPostmarkでVerifyする必要があります。.これはメールクライアントがアドレス帳で連絡先を特定するのに役立つかもしれません。

• TO_EMAIL:会話のメール受信側の人のメールアドレス。

• SUBJECT:メールで使用する件名。お望みであれば、もっとダイナミックにすることもできます。

環境変数が smsToEmail, a conversationId変数には、メールクライアント内でメールが同じスレッドに保たれるような内容と書式を持つ値が代入されます（詳しくは Postmark スレッディングサポート記事および Railsでスレッド化されたメールを送信する).

次に、EメールAPIのペイロードが構築され、変数 postmarkSendEmailRequest変数に代入される。このペイロードの中で注意すべき主な点は以下の通りです：

• TextBodyはSMS内で送信されたテキストに設定される。

• MessageStreamを outboundに設定することで、Postmark にトランザクション(送信)ストリームをメール送信に使うように指示します。

• には Headersと呼ばれるヘッダーを1つ含む。 Message-IDと呼ばれるヘッダが1つ含まれています。 conversationId.前述のように、これは電子メールクライアントが電子メールをスレッドするのを助けるために使われる。

request.bodyには、Postmark電子メールのペイロードの値が割り当てられる、 postmarkSendEmailRequest.これは、接続先であるPostmark email APIエンドポイントに送られるリクエストで使用されます。

変換された requestは関数から返され、接続先で設定された Postmark API へのリクエストで使用されます。この addHandlerを呼び出すよう Hookdeck に指示します。 smsToEmailを呼び出すよう Hookdeck に指示します。 transformを呼び出すように指示します。

クリック 確認変換の名前 vonage-sms-to-postmark-emailをクリックし 確認をクリックして、接続設定ページに戻ります。

接続名 接続名の設定を入力します。 sms-to-email.最後に +をクリックする。をクリックして接続を作成します。

Successful Connection Created

表示されたダイアログからソースURLをコピーし、Vonage APIダッシュボードに向かいます。

Vonage API ダッシュボードで Applicationsメニュー項目を選択し + 新規アプリケーションの作成.

アプリケーションの名前 sms-to-email.アプリケーションの 機能セクションで メッセージを有効にし、Hookdeck のソース URL を インバウンドURLと ステータス URLフィールドに貼り付けます。最後に 新しいアプリケーションを生成する.

Add Hookdeck webhook to Messages API Application

次の画面で、Vonageの電話番号が表示されます。これを先ほど作成したアプリケーションにリンクするには リンク.

Link Your Messages API to Your Number

Vonage番号にSMSを送信してください。

Test Your First Working OmniText

Hookdeck ダッシュボードに戻り、Hookdeck が SMS webhook を受信すると、UI が更新されて以下のように受信した webhook イベントが表示されます：

Hookdeck Successful Event Fired

クリック すべてのイベントを表示をクリックし、テーブルでイベントを選択すると、詳細が表示されます。

Detailed Hookdeck Events Dashboard

次にメールをチェックする：

Successful SMS to Email

以上です。SMS-to-Eメール機能が整いました。

Eメールを受信してSMSをトリガーする

さて、フローをサポートするコネクションを作るには、先ほどと同じだが、逆の手順を踏む：

1. ユーザーがPostmarkに関連付けられたメールにメールを送信する

2. Postmarkが受信メールのWebhookをトリガーする

3. Hookdeck は受信メールの webhook を受け取り、送信 Voange API SMS のペイロードを変換します。

4. Hookdeck は SMS を送信するために Vonage Messages API のエンドポイントである Destination URL に HTTP リクエストを行います。

5. 第二のユーザーがSMSを受信する。

前回同様 ダッシュボードにアクセスし 接続を選択し + 接続ボタンをクリックします。

接続の作成 接続の作成ページで ソースの構成セクションで、ソースに 名前 inbound-email.

で デスティネーションの設定で 名前 outbound-smsを設定し エンドポイントURLを Vonage Messages APIエンドポイントに設定します。, https://api.nexmo.com/v1/messages.

拡大する デスティネーションの設定 > 詳細設定を選択します。 基本認証を選択する。 認証を選択し、Vonage API Keyを ユーザー名を、Vonage API シークレットを パスワード.

Vonage API Authentication in Hookdeck

接続ルールの設定 接続ルールの設定セクションで 変換をクリックし、続いて 新しい変換を作成をクリックすると、以前と同じように、ブラウザ内の変換エディタが表示されます。

以下の変換コードをコピーしてエディターに貼り付ける：

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

コードの大部分は関数を使っている。今回は emailToSms.

前回同様、以下の環境変数を 変数ドロップダウンから以下の環境変数を保存します：

• TO_NUMBER:SMSの受信者の電話番号

• FROM_NUMBER:SMS送信に使用されるVonageの電話番号

電話番号は国際国番号の書式で、先頭に+や00を付けないでください。

残りのコードは以下のようなものだ：

A vonageRequestPayload変数が作成され、Messages APIリクエストのペイロードが格納される。この message_typeには textであり channelの値を持つ。 smsの値を持ち、SMSメッセージが送信されることを示します。プロパティは textプロパティはSMSの内容であり、値には request.body.StrippedTextReplyに設定されるか、設定されていない場合は request.body.TextBody.になります。 StrippedTextReplyは、新着メッセージ部分のみを含む返信メール本文であり、完全なメール・スレッドではありません。

の値が割り当てられる。 request.bodyには vonageRequestPayload変数の値が代入され、接続先である Vonage Messages API エンドポイントへのリクエストで使われるリクエストが返されます。呼び出しは addHandlerを呼び出すよう Hookdeck に指示します。 emailToSmsを呼び出すように指示します。 transformを処理するよう Hookdeck に指示します。

クリック 確認変換の名前 postmark-email-to-vonage-smsをクリックし 確認をクリックして、接続設定ページに戻ります。

接続名 接続名の設定を入力します。 email-to-sms.最後に +をクリックする。をクリックして接続を作成します。

Email to SMS Connection Created

ダイアログからソースURLをコピーし、Postmarkダッシュボードに移動して サーバー > {サーバー名} > デフォルトインバウンドストリーム > 設定セクションに移動します。までスクロールします。 インバウンドウェブフックセクションまでスクロールし、URLを 受信ウェブフックフィールドに貼り付け 変更を保存.

Postmark Webhook Connecting to Hookdeck

Postmarkの受信メールアドレスにメールを送信します。前のステップで受信したメールに返信することで可能です。

Successful Programmatic Email Thread Reply

メール送信後、Hookdeckダッシュボードに戻ると、Postmarkからウェブフックイベントが受信されていることが確認できます。

Hookdeck Successful Email to SMS Event

クリック 全てのイベントを表示をクリックし、テーブル内のイベントを選択し、受信Postmarkウェブフックの詳細を確認します。

Hookdeck Email to SMS Events Detailed

SMSメッセージをチェックして、SMSメッセージ内のEメール本文を確認してください：

Successful Email to SMS

また、SMSから再度返信し、Eメールクライアントで会話がスレッド化されていることを確認することもできます：

Successful SMS reply to Email Thread

だから、メールにはスレッドが表示されているはずだ：

Successful Threading in Email From SMS

結論

このチュートリアルでは、Vonage Messages API から SMS Webhook を受け取る接続を Hookdeck で作成し、ペイロードを Postmark email API リクエストに変換し、SMS の本文をメール本文として送信するところまで説明しました。次に Postmark email Webhook を受信する 2 つ目の Hookdeck 接続を作成しました。ペイロードをVonage Messages APIのリクエストペイロードに変換し、メール本文をSMSメッセージの内容として送信します。全ての場合において、API認証情報はHookdeck内に安全に保存されます。

これで、SMSとEメールの橋渡しをするオムニチャネル会話ソリューションが構築されたことになる。

オムニテキスト OmniText GitHub リポジトリには Hookdeck で接続を設定するスクリプトのコードがあります。Hookdeck で作業する別の方法として自由に試してみてください。

この記事では Hookdeck ダッシュボードを使い、事前に設定した電話番号とメールの間で1つの会話をサポートするために必要な機能を実現しました。しかし、我々が行ったことは全て Hookdeck API.プログラムで新しい接続を作成することは、複数の会話をサポートするために可能なアプローチの1つです。また、何らかの会話登録イベントが発生した時にEメールとSMSの双方向ルックアップを保存することもできます。

ローコード/ノーコードのソリューションをお探しの場合は、以下をご覧ください。 Vonage API Studio.

この記事で使われている技術を使って、他にもいくつか試すことができる：

• 追加 ウェブフック検証PostmarkとVonage Messagesのインバウンドウェブフックへの追加

• 使用方法 Hookdeck CLIを使ってローカルの開発環境で webhook を受け取ります（ngrok がよく知られているのと似ています）。

• 2回目、3回目、そしてn回目の会話を作る。以下の方法で、解決策を自由に話し合ってください。 課題を作成するを作成してください。

• を使用して、WhatsApp、Facebook Messenger、Viberなどの他のメッセージング・チャネルのサポートを追加します。 メッセージAPI

あなたが次に何をするにしても、私たちはそれを知りたいのです！私たちと一緒に Vonage開発者コミュニティSlackまたは X（以前はTwitterとして知られていました。