Vonage Messages APIにおけるメッセージフェイルオーバーの導入

メッセージのフェイルオーバーが Vonage Messages APIで利用できるようになりました。.フェイルオーバーとは何か、どのように使うのか、その前に メッセージ APIについて簡単に説明しましょう。

Messages API の概要

Messages APIは、SMS、MMS、RCS、WhatsAppなど、複数のメッセージングチャネルで様々なタイプのメッセージを送受信できるマルチチャネルメッセージングAPIです。

APIリクエストのペイロードの正確なJSON構造は、チャネルやメッセージタイプによって異なるが、すべてのメッセージは同じ基本原則に従う。 すべてのメッセージのJSONは、以下のプロパティを持つ。 に対する, から, チャンネルそして message_typeと、メッセージ・タイプによって異なるメッセージ自体のプロパティがあります。さらに、オプションのプロパティもあり、そのいくつかは、特定のチャネルやメッセー ジ・タイプでサポートされている特定の機能に関するものです。

例えば、これは基本的な テキストメッセージを SMSチャネルで基本的なテキストメッセージを送信する場合のJSON構造です：

{
   "to": "447700900001",
   "from": "Vonage",
   "channel": "sms",
   "message_type": "text",
   "text": "Hello from Vonage!"
}

基本的な 画像メッセージは rcsチャネル経由で送信される基本的な画像メッセージは、次のような構造のJSONを使用します：

{
   "to": "447700900001",
   "from": "Vonage-RCS-Agent",
   "channel": "rcs",
   "message_type": "image",
   "image": {
     "url": "https://example.com/image.jpg"
    }
}

APIリクエストに対するレスポンスには、レスポンス・ボディに message_uuidプロパティが含まれます。この UUID を使って ステータスを追跡するために使用できます。

{
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab"
}

メッセージステータス

最初のAPIリクエストが行われると、メッセージオブジェクトはさまざまな ステータス例えば 送信済みや 配信Messages API は、指定されたチャネルのダウンストリームネットワークを経由して、指定された受信者に配信を試みます。

ステータスの変更は、HTTPリクエストをトリガーして ステータスウェブフックエンドポイントに HTTP リクエストが送信されます。リクエスト・ボディは以下のような構造のJSONペイロードになります（チャネルとステータスによって追加のプロパティがある場合もあります）：

{
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "447700900000",
   "from": "Vonage",
   "channel": "sms",
   "timestamp": "2025-02-03T12:14:25Z",
   "status": "delivered"
}

具体的なステータスはチャンネルによって若干異なる場合があります。たとえば RCSや WhatsAppなどは 既読ステータスがある。 SMSやMMSチャンネルには既読機能がありません。 既読ステータスを提供する機能はない。

すべてのチャンネルに共通するメッセージステータスのひとつは 拒否ステータスである。チャネルやメッセージの種類によって、メッセージが拒否された理由はさまざまです。しかし、どのような場合でも 拒否ステータスは、メッセージが受信者に配送されないことを意味する。

メッセージ・フェイルオーバーとは

Vonage Messages API にフェイルオーバーが実装される以前は、メッセージが拒否される状況に対処するためにメッセージング・アプリケーションに弾力性を持たせたい場合、そのためのビジネス・ロジックを自分で実装する必要がありました。例えば、Message Status Webhook メッセージを使って、個々のメッセージ・リクエストのステータスを追跡するシステムを message_uuid値を使って、個々のメッセージ・リクエストのステータスを追跡するシステムを構築することができます。 拒否されたステータスを受信した場合、フォールバックメッセージのリクエストを送信します。

フェイルオーバー機能を使えば、この種のロジックを最初のメッセージリクエスト自体に組み込むことができる。その方法について説明しよう！

Messages APIでフェイルオーバーを使う

メッセージAPIで Messages APIでフェイルオーバーを使用するにはでフェイルオーバーを使用するには、メッセージを定義するJSONペイロードに failoverプロパティを追加する必要があります。このプロパティの値は、1 つ以上のメッセージ・オブジェクトを含む配列です。

{
   "to": "447700900001",
   "from": "Vonage",
   "channel": "sms",
   "message_type": "text",
   "text": "Hello from Vonage!",
   "failover": [
     // message objects
   ]
}

最初のメッセージが拒否された場合、Messages APIは自動的に最初のメッセージオブジェクトを フェイルオーバー配列の最初のメッセージオブジェクトを自動的に送信する。そのメッセージも拒否された場合は、2番目のオブジェクト（定義されている場合）が送信されます。

フェイルオーバー フェイルオーバープロパティをAPIリクエストに含めると message_uuidは通常通り HTTP レスポンスで受け取りますが、追加のプロパティとして ワークフローIDも含まれる：

{
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9"
}

フェイルオーバーで送信されたメッセージ・オブジェクトに対するメッセージ・ステータスWebhookリクエストを受信する場合 フェイルオーバープロパティとともに送信されたメッセージオブジェクトのウェブフックリクエストを受け取るとき、JSON ペイロードには ワークフローオブジェクトが含まれます。 ワークフロープロパティを持つワークフローオブジェクトが含まれる。 ワークフロー_idと一致する。この文脈では、「ワークフロー」は一連のメッセージ（初期メッセー ジと定義されたフェイルオーバー・メッセージ）を表す。

さらに ワークフローオブジェクトには items_numberプロパティと items_totalプロパティが含まれる。この アイテム番号は、このメッセージ・ステータス・リクエストがワークフロー全体のどの「アイテム」またはメッセージに関連するかを示します。この アイテム番号の 1は最初のメッセージを示し アイテム数の 2は フェイルオーバー配列の最初のメッセージ・オブジェクトを示します。このように items_totalプロパティは、ワークフロー全体の 'アイテム' またはメッセージの総数を示します。 例えばの 3で定義された2つのメッセージと1つの初期メッセージを示す。 フェイルオーバー配列に定義された2つのメッセージがあることを示します。

{
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "447700900001",
   "from": "Vonage",
   "channel": "sms",
   "timestamp": "2025-02-03T12:14:25Z",
   "status": "delivered",
   "workflow": {
      "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
      "items_number": "1",
      "items_total": "2"
   }
}

Messages API はワークフロー内の各メッセージに対して、必要に応じて Message Status リクエストを送信します。例えば ステータスの 拒否に対して アイテム数1、そして ステータスの 配送済み(同じ メッセージと ワークフロー_id)に対して items_number2.一方 が1が 配信されたが配信された場合、ワークフローは完了し、ワークフロー内の後続のメッセージはメッセージステータス要求をトリガーしない。

フェイルオーバーの使用時期

さて、ここまで フェイルオーバーとはフェイルオーバーとは何か どのように フェイルオーバーとは何か、そしてそれをどのように使うのかについて説明した。

チャンネル間のフェイルオーバー

あるチャネルへのメッセージ配信を試み、最初のメッセージが拒否された場合、別のチャネルにフェイルオーバーすることで、Vonage Messages APIのマルチチャネル機能を活用することができます。

一般的なユースケースは、RCSからSMSへのフェイルオーバーだろう。しかし RCSは広くサポートされているiOSではv18からRCSメッセージングがサポートされている）とはいえ、デバイスのサポートやネットワークのカバレッジという点では、SMSほど普及していない。さらに、デバイスによっては、そのデバイスでRCSメッセージングを有効にする必要があります（つまり、デフォルトでは有効になっていません）。RCSをサポートしていないデバイスにメッセージを送信すると、そのメッセージは 拒否される.このような場合、代わりにSMSメッセージにフェイルオーバーすることができます。

{
   "to": "447700900001",
   "from": "Vonage-RCS-Agent",
   "channel": "rcs",
   "message_type": "text",
   "text": "Hello from Vonage!",
   "failover": [
     {
       "to": "447700900001",
       "from": "Vonage",
       "channel": "sms",
       "message_type": "text",
       "text": "Hello from Vonage!"
     }
   ]
}

マルチフェイルオーバー

一般的な考え方は前の例と似ていますが、メッセージの種類に応じて適切なフォールバックを提供するために、より多くのチャネルを使用します。たとえば、RCS経由で画像付きのProductメッセージを送信し、受信者のデバイスがRCSをサポートしていない場合はMMS画像にフェイルオーバーし、受信者のネットワークがMMSをサポートしていない場合はSMSにフェイルオーバーしたい場合があります。

{
   "to": "447700900001",
   "from": "Vonage-RCS-Agent",
   "channel": "rcs",
   "message_type": "image",
   "image": {
     "url": "https://example.com/image.jpg"
    },
   "failover": [
     {
      "to": "447700900001",
      "from": "447700900000",
      "channel": "mms",
      "message_type": "image",
      "image": {
         "url": "https://example.com/image.jpg"
      }
    },
    {
       "to": "447700900001",
       "from": "Vonage",
       "channel": "sms",
       "message_type": "text",
       "text": "Check out this image https://example.com/image.jpg"
     }
   ]
}

結論と次のステップ

この投稿では、Vonage Messages API のフェイルオーバー機能について見てきました。フェイルオーバーとは何か、それをどのように使うか、そしてフェイルオーバーが役に立つであろういくつかの状況について見てきました。

フェイルオーバーについてさらに詳しく知りたい方は ガイドをご覧ください、 コードスニペット例をご覧ください。 Messages API仕様書.

Vonage Messages APIを使って何か素晴らしいものを作っていますか、フェイルオーバー機能を使う予定ですか、あるいはこの機能やAPI全般について質問がありますか？私たちの VonageコミュニティSlackワークスペース!