OTP 送信

このインターフェースは、EngageLab プラットフォームで検証コードを生成し、テンプレートで指定されたチャネル戦略に従って送信するために使用されます。

EngageLab プラットフォームに検証コードを生成させるのではなく、ご自身で検証コードを生成したい場合は、EngageLab OTP のカスタム OTP 送信 インターフェースを呼び出すことができます。

リクエスト URL

POST https://otp.api.engagelab.cc/v1/messages

認証

API 認証の方法については 認証 を参照してください。

リクエスト例

リクエストヘッダー

              
              POST /v1/messages  HTTP/1.1  
Content-Type: application/json  
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

            

リクエストボディ

              
              {
    "to": "+6591234567",
    "template":{
      "id":"test-template-1",
      "language": "default",
        "params": {
        "key1": "value1",
        "key2": "value2"
        }
    }
}

            

リクエストパラメータ

リクエストオブジェクトは JSON 形式で表現されるため、リクエストヘッダーには Content-Type: application/json を含める必要があります。

params に関する注意

1. from_id などテンプレートに既定されたフィールドについては、params フィールドの値を渡さない場合、メッセージ送信時にテンプレートの既定の from_id が使用されます;
2. params:{"from_id":"12345"} のように params フィールドの値を渡した場合、メッセージ送信時にテンプレートの from_id が 12345 に置き換えられます;
3. また、テンプレート作成時のテンプレート内容にあるカスタム変数フィールドも params で値を割り当てます。例えばテンプレート内容が Hi {{name}}, your verify code is {{code}} の場合、params:{"name":"Bob"} のようにパラメータを割り当てる必要があります。
4. Email チャネルの特殊変数: Email チャネルでは、params を通じてメール件名（subject）、送信者名（from_name）、送信者メールアドレス（from_mail）などを動的に上書きできます。詳細な高度な使い方は テンプレートの作成 - Email テンプレート変数の高度な使い方 を参照してください。

レスポンスパラメータ

成功レスポンス

              
              {
    "message_id": "1725407449772531712",
    "send_channel": "sms"
}

            

なお、返却される send_channel の値は、最終的にユーザーに配信されるチャネルを表すものではなく、この段階で使用されたチャネルを表すにすぎません。例えば、テンプレートで設定された戦略が WhatsApp チャネルでの配信失敗時に自動的に SMS チャネルへフォールバックする場合、インターフェースは whatsapp の値を返します。一定時間後に配信失敗を検知すると、システムは SMS チャネルを使用して送信します。

失敗レスポンス

HTTP ステータスコードは 4xx または 5xx で、レスポンスボディには次のフィールドが含まれます。

              
              {
    "code": 5001,
    "message": "sms send fail"
}

            

エラーコード

下表は、本 API が認証、送信前検証、および同期送信段階で返すエラーのみを記載します。プロバイダー受理後の非同期配信失敗は本 API では返されません。メッセージステータス照会またはコールバックで取得してください。

呼び出し側は code でエラータイプを判定してください。message は具体的な理由の表示やトラブルシューティングに使用し、固定の message 文言に依存した業務ロジックは推奨しません。

レート制限および送信量エラーの説明

• 3004 はテンプレート検証コード送信の頻度制御です。制限ウィンドウはテンプレート設定に基づき、検証コードの有効期間と一致しない場合があります。
• 6001、6002 は番号またはエンドユーザー IP 次元のセキュリティ頻度制御です。
• 6003、6008 は本リクエストが送信量上限に達したことを示します。上限到達後に一時停止状態へ入ると、以降のリクエストは 6007 を返す場合があります。
• HTTP 429 を受信した場合、すぐに連続してリトライしないでください。しばらくしてから再試行し、継続する場合は管理者またはテクニカルサポートに連絡してください。
• 5011 から 5019 は同期送信段階で識別可能な失敗のみを示します。プロバイダー受理後に発生する空番号、電源オフ、キャリア拒否などの状態は、非同期のメッセージステータスまたはコールバックで返される場合があります。