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プラットフォームからお使いのプラットフォームに転送したりする方法は2通りあります：

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

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

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

SMSプレビュー

SMSメッセージに問題がないかを顧客に送信する前にチェックしたい時は、SMS preview (SMSプレビュー) (opens in a new tab)が役立ちます。これを使用すると、メッセージの長さ、メッセージを分割した場合の構成パーツの数、使用言語、音訳の出力などを事前に評価できます。

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

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が応答にも含まれるようにメッセージIDをカスタマイズします。そうしない場合は、NTT CPaaSが自動的に生成したIDが応答に含まれます。
bulkId - 複数のメッセージまたは複数の受信者にメッセージを送信する際、メッセージへの応答を見分けやすくするために、メッセージIDと同じIDが応答にも含まれるようにしたい時は、一括IDをカスタマイズします。そうしない場合は、NTT CPaaSが自動的に生成したIDが応答に含まれます。
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 - 送信されるメッセージの内容のことです。

この例では、同じ内容のメッセージと送信者からのSMSを2つのアドレスに送信されます。応答には、複数の受信者を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メッセージの送信

クエリパラメーターを含む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 を持つ複数のメッセージを作成することは推奨されません。メッセージの検索、スケジュール変更、キャンセル、更新に影響を与える可能性があります。

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

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

詳細なステップバイステップガイドについては、NTT CPaaS APIによるSMSのスケジュール設定と題したセクションをご参照ください。

メッセージの送信レポートとインサイト