送信番号をキャンペーンに割り当てる
この操作は、メッセージングブランドと本番キャンペーンが登録され、キャンペーンが有効になった後に使用します。アカウント内のひとつの SMS 対応番号をキャンペーンに関連付けます。ブランドの作成、キャンペーンの作成や承認、番号の購入、メッセージの送信は行いません。
現在のポータルは、番号にキャンペーンを割り当てる際にこのルートを使用します。パブリック API はキャンペーン識別子を受け取り、別個のブランド識別子を受け取るのではなく、アカウントが所有するキャンペーンからブランドを導出します。
リクエスト
有効化された API アカウントと許可された送信元 IP アドレスを使用して、HTTPS 経由でフォームエンコードされた POST を送信します。アカウントの実際の番号とキャンペーン識別子を使用してください。この例の番号は架空のものです。
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--data-urlencode 'action=add' \
--data-urlencode "campaign=$CAMPAIGN_ID" \
--data-urlencode 'number=12025550123' \
'https://api.multitel.net/v3/campaign'| パラメーター | 必須 | 意味 |
|---|---|---|
| action | はい | add を使用して割り当て、delete を使用して番号の現在のキャンペーン関連付けを削除します。大文字小文字と前後の空白は正規化されます。 |
| campaign | add の場合 | 認証されたアカウントが所有する ACTIVE 状態のキャンペーンの campaignId。そのブランドもアカウントに属している必要があります。明示的にサンドボックスとしてマークされたキャンペーンは、実際の送信番号に割り当てることはできません。delete の場合はこのパラメーターを省略してください。削除には番号の既存の関連付けが使用されます。 |
| number | はい | 所有している、有効で、無効化されていない、SMS 対応の送信番号。北米の番号の場合は、プラス記号を付けずに、国番号 1 に続けて十桁の番号を指定してください。ハンドラーは数字以外の文字を除去し、プラス付きおよび十桁の同等表記も検索します。この正規化は一般的な電話番号の妥当性チェックではありません。 |
この操作はひとつの番号を変更します。ページネーション、バッチパラメーター、ドライランオプションはありません。既存のキャンペーンに番号を関連付けるだけの目的でキャンペーン作成エンドポイントを使用しないでください。
現在の関連付けを削除する
所有している番号で action=delete を使用します。これにより、送信キャンペーンの関連付けが削除され、その番号に保存されているブランド/キャンペーンフィールドがクリアされます。キャンペーンやブランドの削除、電話番号の解放、番号のサービス解約、キャンペーンの定期課金の停止は行いません。
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--data-urlencode 'action=delete' \
--data-urlencode 'number=12025550123' \
'https://api.multitel.net/v3/campaign'レスポンスと検証
この架空の例は、通常の API レスポンスエンベロープと一部の結果フィールドを示しています。返される番号は、アカウントに保存されている形式を保持します。削除が成功した後、brandId と campaignId は空文字列になります。
{
"status": {"code": 200, "msg": "Campaign assignment updated."},
"response": {
"number": "+12025550123",
"brandId": "BRAND_FROM_ACCOUNT",
"campaignId": "CAMPAIGN_FROM_ACCOUNT",
"providerStatus": 200
}
}providerStatus はメッセージングパートナーの HTTP ステータスです。ハンドラーは 2xx のトランスポートレスポンスを受け入れた後、ローカルの番号レコードを更新します。パートナーのレスポンスボディを解釈して、別個の業務レベルの受理結果を判定することはありません。したがって、成功レスポンスはメッセージング登録が完了したことや配信が成功することの証明にはなりません。本番トラフィックを送信する前に、ポータルで番号のキャンペーンステータスを確認してください。
ローカルの関連付けだけを配信承認とみなさないでください。キャンペーンとブランドの承認、番号のプロビジョニング、アカウントの権限、コンテンツルール、通常のメッセージング制限は引き続き適用されます。
エラーと部分的な結果
- 401: ハンドラーが利用できる認証済みアカウントがありません。
- 400: action または number が欠落しているか無効であるか、add リクエストにキャンペーン識別子がありません。
- 404: 番号が、所有している有効で無効化されていない SMS 番号ではありません。
- 409: キャンペーンがアカウントで利用できない、ACTIVE ではない、明示的にサンドボックスである、またはそのブランドがアカウントで利用できません。
- 503: メッセージング連携が利用できません。アカウント資格情報を変更したり設定値を推測で作成したりせず、サポートに連絡してください。
- 502: メッセージングリクエストが失敗した、タイムアウトした、または 2xx 以外の HTTP ステータスを返しました。providerStatus が返される場合があります。タイムアウトは、パートナー側で変更が行われなかったことの証明にはなりません。
- 500 と partial=true: メッセージングパートナーは成功の HTTP ステータスを返しましたが、ローカルの関連付けを確認できませんでした。再試行する前に、ポータルで番号の実際の状態を確認して不一致を解消するか、サポートに連絡してください。
HTTP の結果だけでなく、API ステータスコードとレスポンスボディも確認してください。タイムアウトや部分的な結果をやみくもに再試行しないでください。このハンドラーには、リクエストレベルの冪等性キー、トランザクションのロールバック、キャンペーン登録完了チェックはありません。同じ内容のローカル割り当てを繰り返した場合、データベースが変更行なしと報告しても成功を返すことがあります。
範囲と影響
この操作は、送信番号のルーティングと、保存されているキャンペーン/ブランドの関連付けを変更します。レビュー済みのハンドラーには、アカウントへの直接の引き落とし、キャンペーンの作成、購入、メッセージ送信は含まれていません。これは価格見積もりでも無料サービスの約束でもありません。既存の番号、キャンペーン、メッセージングの料金は、アカウントの利用条件に基づいて引き続き発生します。
ポータルでは、別のキャンペーンに変更すると、まず以前の関連付けが削除され、次に新しい関連付けが追加されます。これらは別々のリクエストです。二つ目のリクエストが失敗した場合、以前の関連付けはすでに削除されている可能性があります。この二つのリクエストが一緒にロールバックされると想定しないでください。