API による SMS 送信

目的

SMS メッセージ送信 API の概要を理解する
必須パラメータと送信リクエストの形式を把握する
API リファレンスへのアクセス方法を知る

概要

SMS メッセージ送信 API を利用して SMS を送信できます。
送信先番号・本文・SenderID などを JSON 形式のリクエストボディで指定します。

フロー

sequenceDiagram
  participant App as お客様のアプリケーション
  participant API as NTT CPaaS API
  participant Carrier as キャリア
  participant User as 受信端末

  App->>API: SMS 送信リクエスト（POST /sms/3/messages）
  API->>Carrier: キャリアへ転送
  Carrier->>User: SMS 配信
  Carrier-->>API: 配信結果（DLR）

エンドポイント

POST https://{baseURL}.ibapi.nttcpaas.com/sms/3/messages

baseURL の確認方法

{baseURL} は、NTT CPaaSポータルページにログインして「ディベロッパー」タブを開き、該当プロジェクトの API 設定画面で確認できます。
デフォルトのプロジェクトにはデフォルトの baseURL が割り当てられています。

リクエストヘッダー

Content-Type: application/json
Authorization: App {API_KEY}

最小リクエスト例 (トライアル時)

{
  "messages": [
    {
      "from": "ServiceSMS",
      "destinations": [
        {
          "to": "819012345678"
        }
      ],
      "text": "NTT CPaaS からのテスト送信です。"
    }
  ]
}

主なリクエストパラメータ

パラメータ	必須	説明
`from`	○	送信元番号（SenderID）。トライアル時は `ServiceSMS`、本番ではNTT CPaaSから払い出される正式な送信元番号を指定
`destinations[].to`	○	送信先の携帯電話番号。国際形式(`8190xxxxxxxx`)(E.164 +なし)を指定。
`text`	○	送信する SMS 本文
`notifyUrl`	-	送信結果（DLR）を受け取る Webhook URL

flash パラメータは使用不可

英語版のAPI リファレンスには flash パラメータが記載されていますが、NTT CPaaS の SMS チャネルではサポートしていません。
flash をリクエストに含めるとエラーになります。リクエストから必ず除外してください。

詳細なパラメータは API リファレンスを参照

すべてのリクエストパラメータ・レスポンス仕様については、以下の API リファレンスをご確認ください。
SMS 送信 API リファレンス

実装時の注意

SenderID を正しく設定する

トライアル環境: ServiceSMS
本番環境: 払い出された正式な SenderID

再送処理に注意する

同一メッセージを同一番号へ短時間に繰り返し送信すると、連続送信制限（スパム防止）に抵触する可能性があります。

リトライサイクルの目安

失敗時の再送（リトライ）を実装する場合は、リトライサイクルとして最低でも 1 時間以上の間隔を設けることを推奨します。
validityPeriod パラメータ（有効期限）を設定することで、配信できなかった場合の再送期限を制御できます。

詳細は送信時の注意事項を参照してください。

API キーを安全に扱う

API キーをソースコードにハードコードせず、環境変数やシークレット管理ツールを使用してください。
詳細はベースURLとAPIキーを参照してください。

送信後の確認

SMS を送信した後は、送信結果（Delivery Report）で到達状況を確認できます。
詳細は送信結果取得（DLR）を参照してください。