SMSおよび対応するMMSの送信

送信前の確認

アカウントに設定されている送信元番号を使用して、SMSまたは対応するMMSを送信します。これは本番環境の操作であり、実際に受信者へ連絡が届き、料金が発生する可能性があります。送信を許可された受信者と承認済みの通信にのみ使用してください。以下の番号と参照値の例は架空のものです。

アカウントにはメッセージ送信の承認と、送信元、国、通信内容に応じた権限が必要です。個人・一般消費者ユーザーの認証情報をこのAPIで直接使用することはできません。承認済みのAPI専用認証情報には、別の利用資格判定手順があります。モバイルP2Pの送信元には、追加のP2P権限および米国・カナダ向けの権限が必要になる場合があります。API認証情報があればあらゆる通信の送信が自動的に許可されると考えず、適切なアカウント設定をMultiTELに確認してください。

送信リクエスト

有効なAPIアカウントを使用し、そのアカウントで許可されている送信元IPアドレスからHTTPSで認証してください。認証情報はサーバー側のシークレットストレージに保管してください。フォームエンコードしたフィールドをPOSTで送信するか、フォームフィールドもクエリフィールドも指定しない場合はJSONオブジェクトを使用してください。認証情報やメッセージ本文をURLに含めないでください。

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'from=12025550123' \
  --data-urlencode 'to=12025550124' \
  --data-urlencode 'text=Your requested update is ready.' \
  --data-urlencode 'reference=order-update-example' \
  https://api.multitel.net/v3/sendsms

JSON配列を使用する場合は、toに実際の配列を指定してください。JSON配列を表す文字列をフォームフィールドに入れないでください。最初の連携テストは、単一の受信者への送信で行ってください。複数宛先への送信とMMSの対応状況は経路によって異なるため、使用前に対応する組み合わせを確認してください。

結果全体の確認

説明用に一部のフィールドのみを示しています。表示されている料金は見積もりではありません。

{
  "status": {
    "code": "200",
    "msg": ""
  },
  "response": {
    "sms_log_id_ori": 42,
    "to": "12025550124",
    "from": "12025550123",
    "status": "Success",
    "message": "Message queued",
    "causecode": 0,
    "uniqueid": "fixture-message",
    "cost": "$0.0120",
    "carrier_fee_usd": "0.0020000000",
    "chars": 31,
    "parts": 1,
    "encoding": "GSM-7",
    "permsg": "$0.0120",
    "pid": "fixture-reference"
  }
}

HTTPステータス、JSONのstatus.code、レスポンスのstatus/messageを併せて確認してください。結果コードが文字列で返される場合があります。サポートでの照合のため、sms_log_id_oriと、返されたメッセージおよび参照値を保存してください。従来形式のuniqueidとpidの値は経路によって異なります。その形式を推測したり、クライアントの冪等性トークンだと見なしたりしないでください。

SuccessまたはMessage queuedは通常、選択された経路で受け付けられたことを示し、受信者の携帯端末に届いたことを示すものではありません。sentなどの初期コールバックのステータスだけでは、最終的な配信完了を確認できません。

セグメント数と料金

送信前に、完成した最終テキスト全体に対してSMS文字数分析を使用してください。SMSの料金は宛先とアカウントのサービスによって異なり、適用される通信事業者手数料がセグメントごとに加算されます。送信処理では、宛先別の料金と適用される手数料を合算し、その金額に算出されたSMSセグメント数を掛けます。この計算では、MMSリクエストは単一のメッセージとして扱われます。

従来形式のレスポンスでは、costとpermsgは書式設定された金額の文字列です。carrier_fee_usdは通信事業者手数料の内訳をUSDで示し、算出された送信合計額にすでに含まれています。重ねて加算しないでください。実際のアカウント料金と経路の利用可否は、ご自身のアカウントについて確認する必要があります。このリクエストは料金の照会だけを行う操作ではありません。

レビュー対象のコードでは、通信事業者への送信処理が成功した後に残高から料金が引き落とされますが、通信事業者での受け付け、ローカルでの永続化、課金は単一のトランザクションではありません。上流でリクエストが受け付けられた後に、エラーやタイムアウトが発生する可能性があります。クライアントが指定できる冪等性キーは提供されていません。同じ参照値でリクエストを繰り返すと、再び送信され、課金される可能性があります。

ローカル配信と結果が混在する場合

ローカルでホストされている番号は、外部の通信事業者へ送信することなく、MultiTELのメッセージ受信フローで受け付け（accepted）される場合があります。宛先がすべてローカルのリクエストでは、レスポンスにaccepted、message_id、provider、delivery_statusが含まれる場合があります。ローカルでの受け付けは、受信者が設定した転送先への転送が成功したことを保証しません。

local_delivery_resultsとpartialがある場合は確認してください。転送結果が失敗でも、受信者のacceptedがtrueと表示される場合があります。宛先が混在するリクエストでは、通信事業者経由の宛先は受け付け済み（accepted）でも、ローカル宛先の処理は失敗している場合があります。バッチ全体を自動で再試行しないでください。まず、受信者ごとに結果を照合してください。

この処理経路では、すべてローカルの宛先で受け付けられた場合、送信料金はゼロと報告されますが、受信者には通常のメッセージ受信料金が発生する可能性があります。送信料金がゼロであることを、どのアカウントにも課金されないという保証と解釈しないでください。

コールバックと関連付け

notifyurlを指定すると、初期コールバックにはstatusエンベロープと、message_id、reference、from、to、status、status_text、error_code、timestamp、acceptedなどのレスポンスフィールドが含まれます。ローカルの処理結果が含まれる場合もあります。API認証情報や不要なメッセージ内容をログに記録せずに、関連付けに必要な情報を保存してください。

このハンドラーは、その初期コールバックに署名フィールドを追加しません。未検証のコールバックだけを根拠に、別の操作を許可しないでください。ご自身のアカウントでサポートされている連携・Webhook設定を確認し、不確かな結果はポータルの記録またはサポートを通じて照合してください。コールバックが一度だけ届くことや、最終配信の順序どおりに届くことを前提にしないでください。

失敗と安全な復旧

検証の失敗では、APIコード403が使用される場合があります。アカウント承認、P2P、国別ポリシーによる拒否でも、HTTP 403が設定され、機械可読のresponse.codeが含まれる場合があります。レート制限では、再試行に関する情報とともに429が使用される場合があります。ポリシーを利用できない場合や、送信またはローカルでの永続化に失敗した場合は、503または500が使用される場合があります。従来の残高不足の処理でも500が返される場合があります。

429の場合は、Retry-Afterと、response.retry_afterの値があればその値に従ってください。アカウント、送信元、国、受信者に関する拒否の場合は、再試行する前に原因を解消してください。タイムアウトが発生した場合や送信結果が不明な場合は、リクエスト時刻、参照値、返された識別子を保存し、再送信する前にポータルを確認してサポートに連絡してください。ログに記録がないことだけでは、どの通信事業者もリクエストを受け付けなかった証拠にはなりません。