API SMS 送信
通知およびマーケティングSMSをEngageLabプラットフォームを介さずに自動送信したい場合、このAPIを呼び出すことができます。SMSテンプレートIDと送信対象を指定すると、システムがテンプレート内容に基づいて自動的にSMSを送信します。
プラットフォーム設定
APIを呼び出す前に、EngageLab SMSコンソールで以下の設定を完了する必要があります：
SMSテンプレート設定: APIを呼び出す前に、テンプレート管理ページにアクセスし、SMSテンプレートをカスタマイズして提出してください。テンプレートは承認され、テンプレートIDを取得した後にのみ使用可能です。
APIキー設定: APIキー管理ページにアクセスして、API基本認証キーを作成してください。
呼び出しプロセス
SMS送信APIを呼び出すには、以下のプロセスを参照してください。ご不明な点がある場合は、カスタマーサービスにお問い合わせください。
呼び出しURL
POST https://smsapi.engagelab.com/v1/messages
呼び出し認証
HTTP基本認証を使用して検証を行います。HTTPヘッダーにAuthorizationを追加してください：
Authorization: Basic ${base64_auth_string}
上記のbase64_auth_stringの生成アルゴリズムは次の通りです：base64(dev_key:dev_secret)
リクエスト形式
リクエストヘッダー
POST /v1/messages HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
リクエストボディ
{
"to": [
"923700056581"
],
"template": {
"id": 1233,
"params": {
"content": "Verification code: 039487. This code will expire in 5 minutes. You are attempting to create your account."
}
}
}
リクエストパラメーター
リクエストオブジェクトはJSON形式で表現されるため、リクエストヘッダーにはContent-Type: application/jsonを含める必要があります。
| 名前 | 場所 | タイプ | 必須 | 説明 | 備考 |
|---|---|---|---|---|---|
| Authorization | ヘッダー | array[string] | いいえ | ||
| to | ボディ | array[string] | はい | ターゲットIDリスト | 対象の電話番号 |
| plan_name | ボディ | string | いいえ | プラン名 | オプション、指定されない場合は"-"がデフォルト |
| schedule_time | ボディ | integer | いいえ | スケジュール時間 | スケジュール送信でない場合は不要、タイムスタンプ |
| template | ボディ | object | はい | ||
| id | ボディ | string | はい | ||
| params | ボディ | object | はい | ||
| custom_args | ボディ | object | いいえ | カスタムパラメーター |
テンプレート作成時にカスタム変数がある場合は、ここで値を渡します。渡されない場合、変数キーがそのまま送信されます（例: {{var1}}）。
paramsの説明
カスタム変数フィールドを含むテンプレートコンテンツの場合、paramsを通じて値を割り当てます。例えば、テンプレートコンテンツがHi {{name}}, welcome to EngageLabの場合、パラメーターをparams:{"name":"Bob"}として割り当てる必要があります。
リクエスト例
1. カスタム通知コンテンツの送信:
{
"to": "+8618701235678",
"template":{
"id":"notification-template",
"params": {
"order":"123456"
}
}
}
2. カスタムマーケティングコンテンツの送信:
{
"to": "+8618701235678",
"template":{
"id":"marketing-template",
"params": {
"name":"EngageLab",
"promotion":"30%"
}
}
}
レスポンス
HTTPステータスコードは200で、レスポンスボディには以下のフィールドが含まれます:
| フィールド | タイプ | 必須 | 説明 |
|---|---|---|---|
| plan_id | string | 必須 | プランID |
| total_count | integer | 必須 | 受信したターゲット数 |
| accepted_count | integer | 必須 | 有効なターゲット数 |
| message_id | string | オプション | 単一送信の場合、対応するメッセージIDが返されます |
成功例（単一ターゲット）
{
"plan_id": "1972488990548348928",
"total_count": 1,
"accepted_count": 1,
"message_id": "1972488990804201472"
}
成功例（複数ターゲット）
{
"plan_id": "1972484198153367552",
"total_count": 2,
"accepted_count": 2
}
成功例（スケジュールタスク）
{
"plan_id": "1972492618659033088",
"total_count": 1,
"accepted_count": 1,
"schedule_info": {
"task_id": 1972492621368553472
}
}
エラー例
{
"plan_id": "1972490061974913024",
"total_count": 1,
"accepted_count": 1,
"message": "err xxxx",
"code": 1
}
送信エラー
HTTPステータスコードは200で、レスポンスボディには以下のフィールドが含まれます:
| フィールド | タイプ | 説明 |
|---|---|---|
| plan_id | string | 必須 |
| total_count | integer | 必須 |
| accepted_count | integer | 必須 |
| message | string | 必須 |
| code | integer | 必須 |
{
"plan_id": "string",
"total_count": 0,
"accepted_count": 0,
"message": "string",
"code": 0
}e": 0
}
エラーコード
| エラーコード | HTTPコード | 説明 |
|---|---|---|
| 1000 | 500 | 内部エラー |
| 2001 | 401 | 認証失敗、トークンが正しくありません |
| 2002 | 401 | 認証失敗、トークンが期限切れまたは無効 |
| 2004 | 403 | このAPIを呼び出す権限がありません |
| 3001 | 400 | リクエストパラメーター形式が無効、JSON形式に準拠しているか確認してください |
| 3002 | 400 | リクエストパラメーターが無効、要件を満たしているか確認してください |
| 3003 | 400 | リクエストパラメーターが無効、ビジネス検証に失敗、エラーメッセージフィールドを参照してください |
| 3004 | 400 | 頻度制限を超えています、有効期間内に同じテンプレートを同じターゲットユーザーに再送信できません |
| 4001 | 400 | リソースが見つかりません（例: 存在しないテンプレートを使用してメッセージを送信） |
| 5001 | 400 | 認証コードメッセージ送信失敗、エラーメッセージフィールドを参照してください |
