メッセージの送信

コミュニケーションに使用するメッセージの種類とチャネルを定義したら、 メッセージAPIメッセージの送信 (opens in a new tab) を使ってリクエストを作成します。

使用するチャネルとメッセージの種類に応じて、送信リクエストにオプションを追加することを忘れないでください。

メッセージAPIリクエストの検証

メッセージAPIは、専用エンドポイントを使用したリクエストの検証をサポートします。このエンドポイントを使用すると、送信前にメッセージペイロードをテストして、各チャネルに必要な要件を満たしていることを確認できます。リクエストを事前に検証することで、潜在的な問題を早期に発見し、解決に関する詳細なフィードバックを受け取ることができます。 この機能は、各チャネルに特定の要件があるため、1つのリクエストで複数のチャネルを処理する場合に特に便利です。検証エンドポイントは、スタンドアロンAPIに対するメッセージの検証、各フェールオーバー手順に対する追加チェックの適用、不明なフィールドのフラグ設定など、より詳細なフィードバックを提供します。

検証エンドポイント

このエンドポイントを使用すると、メッセージAPIリクエストの詳細な検証を実行できます。これにより、メッセージペイロードがプラットフォームへの送信に有効かどうかに関するフィードバックが即座に得られるようになります。リクエストが有効な場合、エンドポイントは 200 OK を返します。問題がある場合は、修正が必要な内容に関する情報を含む 400 BAD REQUEST 応答を返します。

リクエストを検証するには、次の手順に従います：

1. 検証エンドポイント (POST /resource-management/1/messages/validate) にメッセージペイロードを含む POST リクエストを送信します。
2. メッセージが検証に合格すると、送信の準備ができたことを示す 200 OK 応答を受け取ります。
3. 検証に失敗した場合は、エラーの詳細が記載された 400 BAD REQUEST 応答を受け取ります。

サンプルリクエスト

{
  "messages": [
    {
      "channel": "SMS",
      "sender": "447491163443",
      "destinations": [
        {
          "to": "111111111"
        }
      ],
      "content": {
        "body": {
          "text": "May the Force be with you.",
          "type": "TEXT"
        }
      }
    }
  ]
}

エラー応答の例

{
  "description": "Request cannot be processed.",
  "action": "Check the syntax, violations and adjust the request.",
  "violations": [
    {
      "property": "messages[0].content.body",
      "violation": "invalid value"
    }
  ]
}

エンドポイント検証の追加機能：

• スタンドアロンAPIモデルの検証： メッセージが各スタンドアロンAPIによって設定された基準に準拠していることを確認します。
• フェールオーバーチェック： 各フェールオーバー手順が正しく構成されていることを確認します。
• 不明なフィールドの検出： リクエストの送信時に問題を引き起こす可能性のあるフィールドにフラグを立てます。

エンドポイント検証の技術的な詳細については、 APIのドキュメント (opens in a new tab)をご参照ください。

adaptationMode (アダプテーションモード)

メッセージAPIの adaptationMode パラメーターを使用すると、指定したチャネルがサポートしていないエレメントが含まれている場合でも、メッセージを送信および配信できます。

デフォルトでは、adaptationMode が有効になっており、APIは受信者チャネルの機能に合わせてメッセージを自動的に調整し、配信が成功するようにします。適応可能なメッセージエレメントは変換され、適応不可能なエレメントはスキップされます。

適応例

• ヘッダーがチャネルでサポートされていない場合、APIはヘッダーと本文を1つのメッセージにマージし、ヘッダーを最初の行として書式設定し、続く本文のテキストを新しい行に移って書式設定します。
• 画像がネイティブにサポートされていない場合、APIは代わりにテキストの一部としてURLを送信します (例えば、メッセージにプレーンテキストとして追加されます)。
• ボタンがチャネルでネイティブにサポートされておらず、適応できない場合、そのボタンはスキップされます。

adaptationMode が無効 (false として設定) の場合、APIはメッセージを適応させません。チャネルがサポートしていないエレメントがメッセージに含まれている場合、そのメッセージは拒否され、エラーが返されます。

デフォルトの動作では、可能な限りメッセージが配信されます。ただし、メッセージの書式設定を正確に制御する必要があり、エレメントがサポートされていない場合にエラーを受け取りたい場合は、APIリクエストで adaptationMode を true から false に設定することで、この機能を無効にすることができます。

adaptationMode を有効にしたリクエストの例 (デフォルト動作)

 
{
  "messages": [
    {
      "channel": "WHATSAPP",
      "sender": "441234567890",
      "destinations": [
        {
          "to": "440987654321"
        }
      ],
      "content": {
        "body": {
          "text": "Thank you for joining us on Athleete Unlocked! Would you like to subscribe for future Athleete events?",
          "type": "TEXT"
        },
        "buttons": [
          {
            "type": "REPLY",
            "text": "Yes",
            "postbackData": "true"
          },
          {
            "type": "REPLY",
            "text": "No",
            "postbackData": "false"
          }
        ]
      }
    }
  ]
}
 

出力

adaptationMode の無効化

APIでメッセージを適応させず、エレメントがサポートされていない時にエラーを受信するようにしたい場合は、APIリクエストで adaptationMode を false に明示的に設定する必要があります。

adaptationMode を無効にしたリクエストの例

 
{
  "messages": [
    {
      "channel": "SMS",
      "sender": "441234567890",
      "destinations": [
        {
          "to": "440987654321"
        }
      ],
      "content": {
        "body": {
          "text": "Here is a link to our latest updates!",
          "type": "TEXT"
        },
        "buttons": [
          {
            "type": "OPEN_URL",
            "text": "Visit",
            "url": "https://example.com"
          }
        ]
      },
      "options": {
        "adaptationMode": false  // Explicitly disabling adaptation
      }
    }
  ]
}
 

この例では、チャネルがボタン (SMS など) をサポートしていない場合、APIはエラーを返します。

サポートされているメッセージの種類

説明

✅ : チャネルがエレメントをネイティブにサポートし、メッセージがそのまま配信されることを示します。

❌: エレメントがサポートされていないことを示し、エラーが返されます (adaptationMode はエレメントを適応させることができません)。

🔄 : チャネルがエレメントをネイティブにサポートしていないことを示しますが、adaptationMode はチャネルをよりシンプルでネイティブにサポートされている形式 (テキストや URL など) に変換できます (サポートされていないフィールドをスキップ/適応させる)。

Apple Messages for Business テンプレートとRCSテンプレート用の*については、テキストテンプレートのみがサポートされます。

ボタン

画像

ヘッダー付き画像

ドキュメント

ビデオ

テンプレート

フェイルオーバー

常にメッセージを配信するためのユーザーフェールオーバーです。このオプションは、最初のオプションが失敗した場合に、他のチャネルでメッセージを配信します。

以下のことができます：

• チャネル切り替えの自動化： メッセージAPIは、失敗したメッセージ配信のイベントでチャネルを自動的に変更します。
• 有効期間の構成：各チャネルの10秒から48時間までの期間を定義します。有効期間が終了すると、チャネルが切り替わり、新しいチャネルの有効期間が開始されます。
• フェールオーバーフローのカスタマイズ化： チャネルフェールオーバーの順序を定義して優先順位を付けます。

メッセージステータスレポート

ウェブフックオプションを使用して、**message status reports (メッセージステータスレポート)を受信するURLを設定します。APIリクエストのdelivery reports (配信レポート)**の場合は webhooks.delivery.url パラメーター、**seen reports (既読レポート)**の場合は webhooks.seen.url パラメーターの下にURLを定義します。なお、既読レポートは、すべてのチャネルでサポートされているわけではありませんので、ご注意ください。

 
{
  "messages": [
    {
      "channel": "WHATSAPP",
      "sender": "441234567890",
      "destinations": [
        {
          "to": "440987654321"
        }
      ],
      "content": {
        "body": {
          "text": "Thank you for your registration!",
          "type": "TEXT"
        }
      },
      "webhooks": {
        "delivery": {
          "url": "https://notifyme.delivery"
        },
		"seen": {
          "url": "https://notifyme.seen"
        }
      }
    }
  ]
}
 

APIを使用した配信レポートのフェッチ

また、ウェブフックURLの設定に加えて、専用のGETリクエストを使用して、オンデマンドで配信レポートを取得することもできます。これにより、必要に応じてレポート情報をアクティブに引き出すことができます。

配信レポートをフェッチするには、メッセージAPIの GET /messages-api/1/reports エンドポイント (opens in a new tab) を使用します。次のパラメーターを使用して結果をフィルター処理できます：

• channel
• messageID
• entityID
• applicationID
• campaignReferenceID
• bulkID

callbackData によるメッセージのトラッキング

callbackData パラメーターには、メッセージの識別、管理、または監視に使用される追加データを格納できます。メッセージAPIにカスタムデータを添付してトラッキングし、その追跡結果を既読レポートと配信レポートに反映できるため、メッセージの汎用性が高まります。

このパラメーターは、アウトバウンドメッセージとインバウンドメッセージの両方に関連付けることができます。

• アウトバウンド (MT) メッセージ： メッセージの送信時に callbackData が指定されている場合、この値はメッセージに添付されます。
• インバウンド (MO) メッセージ： インバウンドメッセージを処理するためのセットアップで callbackData が定義されている場合、この値が使用されます。

キャンペーン参照ID

キャンペーン参照ID は、メッセージレベルで各APIコール内の各コミュニケーションキャンペーンに割り当てることができるユーザー定義の識別子です。これを使うことにより、キャンペーン管理機能の強化、データインサイトの向上、キャンペーンのパフォーマンスを最適化するためのプロセスの効率化が可能になります。

• 追跡と管理： コミュニケーションキャンペーンのパフォーマンスを効率的に追跡および管理します。各キャンペーンに一意のIDを割り当てることで、様々な成功指標に関する詳細なインサイトを得ることができます。
• 集計された概要： 様々なチャネルでのパフォーマンスに関する集計データをまとめて表示します。
• メトリクスAPIの統合： キャンペーン参照IDは メトリクス API に統合されています。この統合により、詳細な配信レポートにアクセスでき、キャンペーンのパフォーマンス指標の分析が簡素化されます。

URLのトラッキングと短縮

この機能を使用すると、URLを短縮し、クリック行動を監視して、エンゲージメントとメッセージの有効性を評価できます：

• URLの短縮： shortenUrl オプションを使用して、短くてクリーンな URLを作成します。
• クリック数のトラッキング： trackClicksオプションを利用して、送信されたURLのクリック行動を監視します。
• URLのカスタムトラッキング： 高度トラッキング用のカスタム trackingUrl を指定します。
• プロトコルの削除： removeProtocol オプションを使用して、URLからプロトコルを削除します。
• カスタムドメイン： ブランド化された短縮URLには customDomain オプションを使用します。

URLのトラッキングと短縮機能の使用方法の詳細については、 メッセージAPIメッセージの送信 (opens in a new tab)について記載しているAPIドキュメントをご参照ください。

スケジュール設定

メッセージAPIのスケジュール設定機能を使用すると、チャネル内のメッセージの送信スケジュールの設定や送信の自動化ができるようになります。この機能は、コンテンツ、送信するタイミングやターゲットチャネルを指定することを可能にするため、コミュニケーションを効果的に管理しやすくします。例えば、この機能を使えば、エンゲージメントを最大化するために、最適なタイミングでプロモーションメッセージを送信するスケジュールを組めるようになります。

スケジュール設定シナリオ：

• 単一チャネル向けメッセージ： スケジュール設定によってメッセージ送信がトリガーされます。
• フェールオーバー： スケジュールは、最初に一覧表示されたチャネルからメッセージを開始し、その後のフェールオーバーシナリオは、設定されたフェールオーバーと有効性のロジックに従います。