カスタムメッセージ送信
OTPプラットフォームでカスタムテンプレートコンテンツを作成した場合、このAPIを呼び出してカスタムメッセージコンテンツを送信できます。
APIエンドポイント
POST https://otp.api.engagelab.cc/v1/custom-messages
認証
検証にはHTTP Basic Authenticationを使用します。HTTPヘッダーにAuthorizationを追加してください:
Authorization: Basic ${base64_auth_string}
Authorization: Basic ${base64_auth_string}
このコードブロックはフローティングウィンドウ内に表示されます
上記のbase64_auth_stringの生成アルゴリズムは次の通りです: base64(dev_key:dev_secret)
リクエスト形式
リクエストヘッダー
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": "+8618701235678",
"template":{
"id":"test-template-1",
"params": {
"code": "codevalue",
"var1":"value1"
}
}
}
{
"to": "+8618701235678",
"template":{
"id":"test-template-1",
"params": {
"code": "codevalue",
"var1":"value1"
}
}
}
このコードブロックはフローティングウィンドウ内に表示されます
リクエストパラメータ
リクエストオブジェクトはJSON形式で表現されるため、リクエストヘッダーにContent-Type: application/jsonを含める必要があります。
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
| to | String | 必須 | 宛先受信者、電話番号またはメールアドレス、例: +8613800138000, support@engagelab.com |
| template | JSON Object | 必須 | テンプレート情報、以下に二次パラメータを記載 |
| |_ id | String | 必須 | テンプレートID |
| |_ params | JSON Object | 任意 | テンプレートパラメータ |
| _ |_ code | String | 任意 | テンプレートタイプが認証コードの場合に必須 |
| _ |_ var | String | 任意 | カスタムテンプレート変数キー値 |
| テンプレート作成時にカスタム変数を設定している場合、ここで値を渡します。渡さない場合、変数キーがそのまま配信されます（例: {{var1}}） |
paramsの説明
- テンプレートのプリセット変数（例: {{brand_name}}, {{ttl}}, {{pwa_url}}など）については値を渡す必要はありません。システムがテンプレート作成時に指定された内容で自動的に置き換えます。
- テンプレートタイプが認証コードの場合、{{code}}変数を必ず渡す必要があります。渡さない場合、エラーが発生します。
- テンプレートコンテンツ内のカスタム変数フィールドについては、
paramsを通じて値を渡します。例えば、テンプレートコンテンツがHi {{name}}, your verify code is {{code}}の場合、params:{"name":"Bob"}のようにパラメータを渡す必要があります。
リクエスト例
1. カスタム認証コードを送信する場合:
{
"to": "+8618701235678",
"template":{
"id":"code-template",
"params": {
"code": "123456"
}
}
}
{
"to": "+8618701235678",
"template":{
"id":"code-template",
"params": {
"code": "123456"
}
}
}
このコードブロックはフローティングウィンドウ内に表示されます
2. カスタム通知コンテンツを送信する場合:
{
"to": "+8618701235678",
"template":{
"id":"notification-template",
"params": {
"order":"123456"
}
}
}
{
"to": "+8618701235678",
"template":{
"id":"notification-template",
"params": {
"order":"123456"
}
}
}
このコードブロックはフローティングウィンドウ内に表示されます
3. カスタムマーケティングコンテンツを送信する場合:
{
"to": "+8618701235678",
"template":{
"id":"marketing-template",
"params": {
"name":"EngageLab",
"promotion":"30%"
}
}
}
{
"to": "+8618701235678",
"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で再送信するように設定されている場合、APIは値として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 | 認証コードメッセージの配信に失敗しました。messageフィールドのエラー説明を参照してください |
