API経由のSMS

SMS API (opens in a new tab)を使用すると、API経由でSMSを受信し、APIリクエストを送信できるようになります。SMSトラフィックを自動化したい時は、SMS APIを活用することをお勧めします。

基本的なリクエストを通じて簡単なSMSを送信する方法

簡単なSMSメッセージをAPI経由で送信するには、/sms/3/messagesエンドポイントを使用します。

詳細については、 Send SMS message (SMSメッセージ送信) (opens in a new tab)について詳述しているドキュメントをご参照ください。

フル機能のAPIを使ってSMSを送信する方法

API経由でSMSを送信する際に活用できる、有効期間の設定や文字変換といった高度な機能を利用したい時は、フル機能のSMS API (opens in a new tab) を使用します。パラメーターをURLで直接設定できるバージョンのAPIを使用することもできます。

SMSメッセージを受け取ったり、受信した SMSメッセージをNTT CPaaSプラットフォームからお使いのプラットフォームに転送したりする方法は２通りあります：

一つは、お使いの番号に届いたメッセージをPULL (プル) する方法です。これらのメッセージは、NTT CPaaSプラットフォームに保存されますので、ご都合の良い時にプルできます。詳細については、Get received messages (受信したメッセージの取得) (opens in a new tab)について詳述しているドキュメントをご参照ください。
もう一つは、受信したメッセージを専用のURLに自動的にPUSH (プッシュ) する方法です。

どちらの方法も、プラットフォームが何をすべきかを認識できるように、使用する番号(/numbers)とその転送アクションの種類を指定する必要があります。

特定の番号への転送を設定していない場合は、受信ログで受信したメッセージを確認します。これは PULLアクションとよく似ていますが、ログに最長48時間しかデータが保存されないところに違いがあります。

SMSプレビュー

SMS preview (SMSプレビュー) (opens in a new tab)を使用すると、顧客に送信する前にSMSメッセージの内容を改めて確認できます。メッセージの長さ、メッセージを構成する部分の数、使用言語、文字変換の出力などを事前に評価できます。

プレビューメソッドでは、次の情報が提供されます：

originalText - プレビュー用に提供された元のメッセージコンテンツ
textPreview - 受信者のデバイスに表示されるメッセージ内容のプレビュー
messageCount - textPreview の配信に必要なメッセージの数
charactersRemaining - messageCount が増加する前の残りの文字数
configuration - textPreview メッセージを配信するために高度なSMSに含める必要がある構成設定
languageCode - 正しい文字セットの言語コード
文字変換 - 送信したメッセージをあるスクリプトから別のスクリプトに翻字したもの。デフォルトのアルファベットの一部として認識されない文字を置き換えるために使用されます

このメソッドは、メッセージに未使用の文字数が残っているか、およびメッセージの長さが1つのメッセージに収まるか、またはそれ以上のメッセージが必要かを確認したい時に使用します。

通知用URL

通知用URLを使用すると、事前定義されたURLを使用して、配信レポート、メッセージステータス、価格情報、またはGSMエラー (例えば、EC_ABSENT_SUBSCRIBERなど) をコールバックサーバーに転送することができます。通知用URLは、NTT CPaaSプラットフォームがデータを受信するとすぐにデータを転送します。

URLを指定するには、notifyUrlパラメーターを使用します。

URLに加えて、次のフィールドにも必要な情報を入力すると、この機能をより高度に活用できます：

notifyContentType - サーバーにプッシュする本文の種類 (JSON、または XML) を決定します。
messageId - メッセージ ID をカスタマイズして、応答に同じ ID が含まれ、見つけやすくします。それ以外の場合、Infobip は応答で自動的に生成します
bulkId - 複数のメッセージまたは複数の受信者に送信する場合は、一括 ID をカスタマイズして、応答に同じ ID が含まれ、見つけやすくします。それ以外の場合、Infobip は応答で自動的に生成します
callbackData - 通知 URL に送信される追加のユーザー定義データ

プッシュ通知のリトライサイクル

通知用URLが何らかの理由で使用できない場合、転送のリトライは次の方式に従って行われます：

1min + (1min * retryNumber * retryNumber)

最初の数回のリトライ例を次の表に示します。リトライの最大回数は20回で、最後のリトライは最初のリトライから41時間30分後に行われます。このリトライ期間を通してご指定のURLが使用できない場合、データは失われます。

リトライ	間隔	累積
0	01分	00時01分
1	02分	00時03分
2	05分	00時08分
3	10分	00時18分
4	17分	00時35分
5	26分	01時01分
6	37分	01時38分

複数の送信先へのSMSの送信

SMSを複数の送信先に送信することが有益な場合があります。例えば、同じメッセージを複数の電話番号に送信できます。

この例では、仕組みを理解しやすいように、送信先の電話番号を2つだけにしています。

複数の送信先へのSMS送信リクエスト

json

 
    {
      "messages": [
        {
          "from": "WineShop",
          "destinations": [
            {
              "to": "41793026727"
            },
            {
              "to": "41793026727"
            }
          ],
          "text": "Wine shop grand opening at Monday 8pm. Don't forget your wine glass!"
        }
      ]
    }

次のパラメーターは、SMSを複数の送信先に送信したい時に重要です：

from - SMSメッセージの送信者を表す送信元のことです。英数字または数字にすることができます：
- 英数字の送信者IDの長さは、3から11文字である必要があります。 (例：CompanyName)
- 送信者IDの長さは、3から16文字にする必要があります。
to - 国際形式でなければならないメッセージ送信先アドレスの配列を表す送信先のことです。 (例：41793026727)
text - 送信されるメッセージの内容のことです。

この例では、同じ内容のメッセージと送信者を持つ2つのアドレスにSMSが送信されます。応答には、複数の受信者を1つの応答にグループ化するbulkIdフィールドも含まれるため、ログやレポートを簡単に取得できます。リクエストでカスタムバルクIDを渡すことができますが、省略すると、NTT CPaaSプラットフォームで自動的に生成され、応答に割り当てられます。

複数の送信先に送信したSMSに対する応答

json

 
    {
        "bulkId": "2034070510160109025",
        "messages": [
            {
                "to": "41793026727",
                "status": {
                    "groupId": 1,
                    "groupName": "PENDING",
                    "id": 26,
                    "name": "PENDING_ACCEPTED",
                    "description": "Message sent to next instance"
                },
                "messageId": "2034070510160109026"
            },
            {
                "to": "41793026834",
                "status": {
                    "groupId": 1,
                    "groupName": "PENDING",
                    "id": 26,
                    "name": "PENDING_ACCEPTED",
                    "description": "Message sent to next instance"
                },
                "messageId": "2034070510250109027"
            }
        ]
    }

応答には、次のものが含まれます：

bulkId - 複数の送信先に送信されたSMSメッセージの配信レポートを取得 (opens in a new tab)する際に使用されます。
to - メッセージの受信者のことです。
status - メッセージのステータスを示します。
smsCount - 1つの送信先に送信されたSMSメッセージの数を表します。
messageId - 送信するメッセージを一意に識別します。

複数の送信先への複数SMSの送信

ターゲットにしたい顧客に次のプロモーションでそれぞれお気に入りの商品を紹介できるようにしたいとします。顧客はそれぞれ異なるため、すべての顧客に同じメッセージを送るべきではありません。顧客の注意を最大限に惹きつけるためには、それぞれの好みに合わせて SMSメッセージをカスタマイズすることが望ましいです。

このオプションを使用すると、1つのAPIメソッドを呼び出すだけで、複数の送信先に複数のメッセージを送信できます。

複数の送信先への複数SMSの送信リクエスト

json

 
    {
      "messages": [
        {
          "from": "WineShop",
          "destinations": [
            {
              "to": "41793026727"
            }
          ],
          "text": "Hey Mike, delicious Istrian Malvazija is finally here. Feel free to visit us and try it for free!"
        },
        {
          "from": "WineShop",
          "destinations": [
            {
              "to": "41793026834"
            }
          ],
          "text": "Hi Jenny, we have new French Merlot on our shelves. Drop by our store for a free degustation!"
        }
      ]
    }

複数のメッセージを送信した後で、詳細な統計データを取得して分析することができます。例えば、配信レポート (opens in a new tab)を取得することで、SMSで送った招待状を何人の顧客が受け取ったかを測定できます。

メッセージのステータスの詳細については、応答ステータスとエラーコードについて詳述しているドキュメントをご参照ください。

クエリパラメーターを含むSMSメッセージの送信

クエリパラメーターを含むメッセージの送信 (opens in a new tab)機能を使用すると、必要なすべてのURLパラメーターを1つのクエリ文字列に含めたSMSを送信できます。

これは、限定的な統合しか可能でないアプリケーションで、 SMSメッセージの送信 (opens in a new tab)機能の完全統合が難しい場合に適しています。

このメッセージは、ウェブページを開くためにアドレスを入力するのと同じ要領で、ウェブブラウザーのアドレスバーから送信することもできます。これは、コードを書かずにアプリケーションに組み込むことができます。

電話番号やメッセージテキストなどのハードコーディングされた値は、毎回同じ受信者に同じメッセージを送信したい場合を除き、プレースホルダーに置き換える必要があります。プレースホルダー名は、使用しているアプリケーションシステムによって提供されます。

最初の行はAPIエンドポイント (即ちhttps://api.infobip.com/sms/3/text/query?) で、これは常に変更されません。

末尾の疑問符は、クエリ文字列パラメーター の先頭を表します。これは、記号&で区切られたキーと値のペア のシステム (例：from=InfoSMS&) で、値が何であるか、値プレースホルダーで置き換える必要がある値はどれかを確認できるようにします。プレースホルダーの名前と形式は、アプリケーションによって異なります。

これでお使いのアプリケーションは、異なるメッセージを異なる受信者に動的に送信し、プレースホルダーを受信者の電話番号とメッセージに動的に置き換えるようになっているはずです。

デフォルトの応答形式は、JSON です。但し、代わりにXMLを受け取る場合は、メソッドURLの末尾に.xml拡張子を指定します。 (例： https://api.infobip.com/sms/3/text/query.xml)

コンバージョントラッキング機能付きのSMSの送信

コンバージョントラッキングとは、マーケティングキャンペーンのパフォーマンスの監視や分析を通じて、メッセージがターゲットオーディエンスにどの程度響いているかを確認できるようにする機能のことです。

SMSにコンバージョントラッキング機能を有効にすると、特定のユーザーアクションのコンバージョンが成功したことをNTT CPaaSプラットフォームに通知できるようになります。典型的なユーザーアクション例としては、SMSを受け取った後のURLのクリック、コード入力、フォームの提出や購入といった望ましい結果をもたらす行動などが挙げられます。

アクションが実行されると、パフォーマンス分析用の情報がNTT CPaaSプラットフォームに送信されます。

コンバージョントラッキングは、NTT CPaaSがトラフィックのパフォーマンスをより正確に把握し、品質の低下を修正するための対策を積極的に講じるのに役立ちます。

顧客の行動とキャンペーンのパフォーマンスに関する詳細なインサイトを入手することができれば、企業はその知見に基づいてマーケティング戦略を改善し、顧客エンゲージメントを向上させ、最終的に売上と収益を増やすことができるようになります。SMSのコンバージョントラッキング機能を実装すれば、ビジネスマーケティングキャンペーンの効果を大幅に高めることができます。

コンバージョン情報は、SMSメールについてのみ送信できます。コンバージョントラッキングの目的は、2FA (二要素認証) パスワードなどの時間的制約のあるメッセージや特定のリンクのクリックなど、エンドユーザーからの迅速な反応を期待するメッセージを追跡することです。

トラッキングを有効にするには、メッセージ本文内にconversionTrackingオブジェクトを設定します。

コンバージョントラッキングを有効にしてSMSを送信する方法に関する詳細については、 API リファレンス (opens in a new tab)を題したドキュメントをご参照ください。

例えば、POST Send SMS Message (ポスト送信SMSメッセージ) に対する応答で messageId が返された場合、これをNTT CPaaSに提供する必要があります：

NTT CPaaSプラットフォームは、メッセージが送信されるとすぐに追跡プロセスを開始します。
メッセージが配信され、それを受け取ったエンドユーザーがアクション (リンクのクリック、コードの入力など)を実行すると、この行動がコンバージョン成功率に反映されます。こうしたアクションは、企業側で実装されたウェブフックを介して追跡できます。
POST /ct/1/log/end/{messageId}を呼び出して、変換が成功したことをNTT CPaaSに通知します。詳細については、 Confirm conversion (コンバージョンの確認) (opens in a new tab)について詳述しているドキュメントをご参照ください。

NTT CPaaSプラットフォームがコンバージョンの成功に関する通知を受け取ると、パフォーマンスを監視し、このデータを使ってより良いサービスを提供できるようになります。

SMSの送信スケジュールの設定

SMS APIを使用すると、将来の配信に備えてメッセージのこの先の送信スケジュールを組むことができます。この機能は特に、時間的制約のあるキャンペーン、リマインダー、またはお知らせを送信する必要がある時に役立ちます。

sendAtフィールドに指定された日付と時刻で送信SMS (opens in a new tab) エンドポイントを使用します。日付/時刻の形式は 'yyyy-MM-dd'T'HH:mm:ss である必要があります。SSSZ' です。また、bulkIdを含めて、後でメッセージを管理することもできます(スケジュール変更、ステータスの変更など)。

json

"options": {
    "schedule": {
      "bulkId": "BULK-ID-123-xyz",
      "sendAt": "2025-05-19T11:15:00.000+0000"
    }
  }

メッセージの送信スケジュールは最長180日先まで組むことができます。bulkIdが指定されていない場合、NTT CPaaSの方でそれを自動生成して、応答で返します。

SMSの配信時間の管理

さらに、SMSが配信されない時間枠を設定できます。通常、これは、サードパーティによって課される送信制限 (たとえば、政治キャンペーンの同意ルール、販促資料のコンプライアンスなど) があるシナリオに使用されます。

送信SMS (opens in a new tab)エンドポイントを deliveryTimeWindow フィールドで使用します。日付/時刻の形式は 'yyyy-MM-dd'T'HH:mm:ss である必要があります。SSSZ' です。

備考

異なるdeliveryTimeWindowを持つ複数のメッセージを 1 つの一括で作成することは、メッセージの検索、スケジュール変更、キャンセル、または更新に影響を与える可能性があるため、お勧めしません。

送信スケジュールが設定されたメッセージの管理

送信スケジュールが設定されたSMSを管理するには、そのbulkIdを使用してメッセージを識別します。これらのエンドポイントを使用すると、SMSキャンペーンを効果的に展開するスケジュールを組んだり、管理や監視したりできるようになります：

詳細なステップバイステップガイドについては、「Infobip APIを使用してSMSをスケジュールするを参照してください。

メッセージを送るレポートとインサイト