Logo Site EngageLab Mark Colored Transparentドキュメント
OTP
ドキュメントホーム
ドキュメントAPI リファレンス
検索
ログイン
API リファレンス/カスタムメッセージ送信
API リファレンスカスタムメッセージ送信...

カスタムメッセージ送信

最新更新：7日前

OTP プラットフォーム上でカスタムテンプレートの内容を作成している場合、このインターフェースを呼び出してカスタムメッセージの内容を送信できます。

リクエスト URL

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

認証

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

リクエスト形式

リクエストヘッダー

POST /v1/custom-messages HTTP/1.1 Content-Type: application/json Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
              
              POST /v1/custom-messages  HTTP/1.1  
Content-Type: application/json  
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
このコードブロックはフローティングウィンドウ内に表示されます

リクエストボディ

{ "to": "+6591234567", "template":{ "id":"test-template-1", "params": { "code": "codevalue", "var1":"value1" } } }
              
              {
    "to": "+6591234567", 
    "template":{
      "id":"test-template-1",
      "params": {
        "code": "codevalue",
        "var1":"value1"
        }
    }
}
このコードブロックはフローティングウィンドウ内に表示されます

リクエストパラメータ

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

パラメータ 型 必須/任意 説明
to String 必須 送信先。携帯電話番号またはメールアドレス。+6598765432、support@engagelab.com
template JSON Object 必須 テンプレート情報。以下の下位パラメータを参照
|_ id String 必須 テンプレート ID
|_ params JSON Object 任意 テンプレートパラメータ
_ |_ code String 任意 テンプレート種別が検証コードの場合、このフィールドは必須です。
_ |_ var String 任意 カスタムテンプレート変数キーの値。テンプレート作成時に変数をカスタマイズした場合は、ここでその値を渡します。渡さない場合は、{{var1}} のように変数キーがそのまま送信されます

params に関する注意

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

リクエスト例

1. カスタム検証コードの送信:

{ "to": "+6591234567", "template":{ "id":"code-template", "params": { "code": "123456" } } }
              
              {
    "to": "+6591234567", 
    "template":{
      "id":"code-template",
      "params": {
        "code": "123456"        
        }
    }
}
このコードブロックはフローティングウィンドウ内に表示されます

2. カスタム通知内容の送信:

{ "to": "+6591234567", "template": { "id": "notification-template", "params": { "order": "123456" } } }
              
              {
    "to": "+6591234567",
    "template": {
        "id": "notification-template",
        "params": {
            "order": "123456"
        }
    }
}
このコードブロックはフローティングウィンドウ内に表示されます

3. カスタムマーケティング内容の送信:

{ "to": ["+6591234567"], "template": { "id": "marketing-template", "params": { "name": "EngageLab", "promotion": "30%" } } }
              
              {
    "to": ["+6591234567"],
    "template": {
        "id": "marketing-template",
        "params": {
            "name": "EngageLab",
            "promotion": "30%"
        }
    }
}
このコードブロックはフローティングウィンドウ内に表示されます

レスポンスパラメータ

成功レスポンス

フィールド 型 必須/任意 説明
message_id String 必須 メッセージ ID。メッセージを一意に識別する
send_channel String 必須 現在の送信チャネルを示す。値は whatsapp/sms/email/voice
{ "message_id": "1725407449772531712", "send_channel": "sms" }
              
              {
    "message_id": "1725407449772531712",
    "send_channel": "sms"
}
このコードブロックはフローティングウィンドウ内に表示されます

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

失敗レスポンス

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

フィールド 型 必須/任意 説明
code int 必須 エラーコード。詳細はエラーコードの説明を参照
message String 必須 エラーの詳細
{ "code": 5001, "message": "sms send fail" }
              
              {
    "code": 5001,
    "message": "sms send fail"
}
このコードブロックはフローティングウィンドウ内に表示されます

エラーコード

エラーコード HTTP コード 説明
1000 500 内部エラー
2001 401 認証失敗。付与されたトークンが正しくない
2002 401 認証失敗。トークンが期限切れまたは無効化されている
2004 403 この API を呼び出す権限がない
3001 400 リクエストパラメータの形式が不正。JSON の内容がパラメータ形式に準拠しているか確認してください
3002 400 リクエストパラメータが正しくない。リクエストパラメータが要件を満たしているか確認してください
3003 400 リクエストパラメータが正しくない。関連するビジネス検証に失敗。詳細は message フィールドのエラー説明を参照してください
3004 400 頻度制限を超過。同一テンプレート・同一宛先ユーザーに対しては、検証コードの有効期間内に再送信できません
4001 400 関連リソースが存在しない。例: テンプレートメッセージ送信時に存在しないテンプレートを使用
5001 400 送信失敗（一般／その他）
5011 400 携帯電話番号の形式が不正
5012 400 宛先に到達不能
5013 400 番号がブラックリストに登録されている
5014 400 内容が規定を満たしていない
5015 400 メッセージがインターセプト／拒否された
5016 400 内部送信エラー
5017 400 中国地域への送信権限がない
5018 400 携帯電話の不具合（電源オフ／圏外）
5019 400 ユーザーが配信を停止している
5020 400 未登録の番号／空番号
Icon Solid Transparent White Qiyu
お問い合わせ