送信結果取得（Delivery Report）

目的

• SMS の送信結果（到達・エラー）を確認する仕組みを理解する
• Webhook とポーリングの 2 つの取得方式の違いを把握する
• 代表的なステータスの意味と対処法を知る

Delivery Report（DLR）とは

API で送信した SMS が「実際にお客様の端末に届いたか（到達）」「圏外や解約で失敗したか（エラー）」を確認するための仕組みを Delivery Report（DLR） と呼びます。
NTT CPaaS では、システム構成や要件に合わせて 「Webhook（プッシュ型）」 と 「API ポーリング（プル型）」 の 2 つの取得方法を提供しています。

1. Webhook による取得（本番環境・推奨）

お客様のサーバーに受け取り用の URL（エンドポイント）を用意していただき、NTT CPaaS 側からその URL 宛に結果を自動で通知（POST リクエスト）する方式です。

メリット

• 結果が出た瞬間にリアルタイムで通知されるため、タイムラグがありません
• システムへの負荷も最小限に抑えられます

利用シーン

• 本番運用
• 即時性が求められる通知（ワンタイムパスワード等）
• 大量配信時の結果取得

設定の流れ

sequenceDiagram
  box LightCyan お客様側
    participant App as お客様のアプリケーション
    participant Hook as お客様のWebhookサーバ
  end

  box WhiteSmoke NTT CPaaS 側 / その他
    participant API as NTT CPaaS API
    participant Carrier as キャリア
  end

  App->>API: SMS 送信（notifyUrl を指定）
  API->>Carrier: キャリアへ転送
  Carrier-->>API: 配信結果
  API->>Hook: DLR を POST（notifyUrl へ）

1. お客様側のシステムに、Webhook (POST リクエスト) を受け取るためのエンドポイントを作成します
   （例: https://your-domain.com/webhook/sms-dlr）
2. SMS 送信時の API リクエスト（JSON）内に、作成した URL を指定するパラメータ（notifyUrlなど）を含めて送信します
3. メッセージのステータスが更新されたタイミングで、指定した URL に結果（JSON）が自動で送られてきます

2. API ポーリングによる取得（手軽な確認・トライアル向け）

お客様のシステムから、定期的に NTT CPaaS の「結果取得 API（例: GET /sms/1/reports）」を呼び出して、最新のステータスを取りに行く方式です。

メリット

• 受信用のサーバー（公開 URL）を用意する必要がないため、手元の PC や閉域網からでも簡単にテストが可能です

利用シーン

• トライアル時の動作確認
• 小規模な送信
• お客様のサーバーを外部公開できない場合

注意点

• API を叩く頻度が高すぎると制限（レートリミット）に引っかかる可能性があります
• 本番環境で大量の SMS を送信する場合は、前述の Webhook の利用を強く推奨します

代表的なステータス（Status）の種類

取得できる結果データには、主に以下のステータスが含まれます。
エラーハンドリングや再送処理の判断基準としてご活用ください。

Webhook とポーリングの比較