MultiTEL
開発者

PUT/tcr/v2/campaign/{campaignId}

メッセージ配信キャンペーンを更新する

キャンペーンの内容を修正し、保存結果を確認します。審査の依頼と更新の判断は、それぞれ明示的に行います。

このページの内容
  1. 新たに登録せずにキャンペーンを修正する
  2. 実際に変更したフィールドを選ぶ
  3. 必要な修正に絞って送信する
  4. キャンペーンを再取得する
  5. 制限や結果が不確かな場合に対処する

新たに登録せずにキャンペーンを修正する

このルートを使用して、既存のキャンペーンの説明、メッセージ例、同意に関する説明、またはサポート対象のコンテンツ特性を修正します。キャンペーンIDと現在のブランドおよびユースケースは維持してください。既存のキャンペーンの修正を再試行するために、新規登録を行わないでください。

許可された送信元IPアドレスから、有効なAPIアカウントを使用し、HTTPS経由で認証してください。操作できるのは、そのアカウントに属するキャンペーンのみです。変更を準備する前に、現在の状態を取得してください。有効期限が切れたキャンペーンは、このワークフローでは更新できません。

curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/campaign/$CAMPAIGN_ID"

実際に変更したフィールドを選ぶ

サポート対象の変更を含むcampaign-update.jsonを用意してください。現在のポータルは変更されたキャンペーンフィールドのみを送信し、brandId、usecase、campaignIdや、レスポンス専用のステータス情報は送信しません。APIを直接使用する更新でも、フィールドを含むJSONオブジェクトを使用します。ポータルのchanges/versionラッパーは使用しません。

キャンペーン更新フィールド
フィールド指定する内容
description, messageFlow正確なサービスの説明と、利用者が同意し、メッセージを受信し、同意を撤回する方法を記載します。それぞれ40–4096文字で指定できます。
sample1–sample5このキャンペーンで実際に使用する内容に即したサンプルを記載します。空でないサンプルは、それぞれ20–1024文字で指定してください。適格とされたユースケースで必要なサンプル数を維持し、無関係なメッセージは送信しないでください。
helpMessage, optinMessage, optoutMessage該当する受信者向けの応答を、最大1024文字で記載します。必要とされる場合は、最低20文字の要件を満たし、実際のサービスを説明してください。フィールドを空にする前に、現在の同意要件を確認してください。
optinKeywords, optoutKeywords, helpKeywordsスペースを含めず、キーワードをカンマで区切って最大255文字で指定します。応答の内容と実際のキーワード処理を一致させてください。
privacyPolicyLink, termsAndConditionsLinkこのサービスの実際の運用を説明する、関連する公開URLを最大2048文字で指定します。
embeddedLinkSampleメッセージに含めるリンクの代表例を、最大255文字で指定します。
numberPool, embeddedLink, embeddedPhone, ageGated, directLendingキャンペーンの実際の特性をJSONの真偽値で指定します。無効にする場合はfalseを使用し、文字列の"false"は使用しないでください。
autoRenewal公開APIスキーマは、このJSONの真偽値をサポートしています。ただし、ポータルの通常のキャンペーン内容編集画面には表示されません。自動更新を無効にしても、既存の最低契約義務が解除されたり、すでに支払義務が生じている料金がなくなったりすることはありません。
resellerIdスキーマでは、リセラーとの関連付けも指定できます。これはポータルの通常の内容修正フォームの対象外です。このフィールドを使用してキャンペーンを別の顧客へ移動しないでください。また、APIが別のリセラー向けに通信事業者のサービスを設定するとは考えないでください。

更新スキーマでは、brandId、usecase、subscriberOptin、subscriberOptout、subscriberHelpを変更可能なフィールドとして提供していません。キャンペーン作成用のペイロード全体を更新リクエストにコピーしないでください。メッセージ要件を確認する際は、現在の適格性情報を参照してください。

必要な修正に絞って送信する

この例は、予約リマインダーサービスを想定したものです。使用する前に、キャンペーンの実際のサービスと同意の流れに合わせて調整してください。

{
  "description": "Appointment reminders requested by customers of the registered business.",
  "sample1": "Example business: Your requested appointment reminder is ready. Reply STOP to opt out."
}
curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-binary @campaign-update.json \
  "https://api.multitel.net/tcr/v2/campaign/$CAMPAIGN_ID"

同じ内容の送信を意図している場合は、同じキーを使用し、メソッド、パス、クエリ、本文のバイト列を完全に同一に保ってください。内容を変更する場合は、別途レビューしたリクエストが必要です。タイムアウト後に、確認せずにキーを切り替えないでください。完了済みのリクエストではキャッシュされたエラーが再度返されることがあり、処理中のリクエストと重複する場合は、409とRetry-Afterが返されることがあります。

キャンペーンを再取得する

HTTP 200では、キャンペーンのJSONオブジェクトが直接返されます。campaignIdを確認してから、同じキャンペーンをGETで取得し、変更対象のフィールドを比較してください。保存が成功しても、それだけで通信事業者への再審査依頼、番号の割り当て変更、送信の有効化、メッセージの送信が行われることはありません。

ポータルは保存前にフォームのバージョンを確認し、保存後にキャンペーンを再取得します。公開PUTエンドポイントでは、このポータルのバージョンによる制御は行われません。同時に編集する場合は調整してください。冪等性キーでは、他の編集者による更新を検出できません。

ポータルに未解決の審査不承認が表示されている場合は、まず内容を修正し、別途用意されている審査依頼の操作が利用可能であれば、その操作を行ってください。この操作では、現在の本番キャンペーンと共有状態が確認されます。内容を保存するだけでは実行されません。また、キャンペーンIDが存在するだけでは、承認済みであることにはなりません。

現在のサービスでは、通常のキャンペーンのPUT更新によって、別途キャンペーン登録料金の引き落とし処理が行われることはありません。既存の月額料金、最低契約義務、番号レンタル料、メッセージ利用料金は引き続き適用されます。現在設定されているキャンペーン料金については、キャンペーン料金を参照してください。

制限や結果が不確かな場合に対処する

HTTP 400の場合は、フィールド単位のエラーを読み、文字数、同意文、キャンペーンの状態を確認してください。401、403、404の場合は、API認証情報、許可された送信元IP、所有権を確認してください。429の場合は、Retry-Afterの指示に従ってください。500、502、またはリクエストが中断された場合は、キャンペーンIDと、存在するすべてのrequestIdを保持し、再送信する前に既存のレコードを照合して状態を確認してください。

ローカルのスナップショットは、返された本文に依存します。空でない部分的なレスポンスでは、更新に関するメタデータを含め、以前のフィールドが省略されることがあります。空のレスポンスでは、古い値が残ることがあります。成功したという事実だけで全フィールドが保持されたと判断せず、GETの完全な取得結果を確認してください。解消できない相違は、サポート窓口に報告してください。このルートでは、通信事業者への割り当てをアトミックに更新することも、通信事業者側での有効化を復旧する汎用的な操作を提供することもありません。