API SMS Sending
通知およびマーケティングSMSをEngageLabプラットフォームを介さずに自動送信したい場合、このAPIを呼び出すことができます。SMSテンプレートIDと送信対象を指定すると、システムがテンプレート内容に基づいて自動的にSMSを送信します。
プラットフォーム設定
APIを呼び出す前に、EngageLab NewSMSコンソールで以下の設定を完了する必要があります：
SMSテンプレート設定: APIを呼び出す前に、テンプレート管理ページにアクセスし、SMSテンプレートをカスタマイズして提出してください。テンプレートは承認され、テンプレートIDを取得した後にのみ使用可能です。
APIキー設定: APIキー管理ページにアクセスして、API基本認証キーを作成してください。
呼び出しプロセス
SMS送信APIを呼び出すには、以下のプロセスを参照してください。ご不明な点がある場合は、カスタマーサービスにお問い合わせください。
呼び出しURL
POST https://smsapi.engagelab.cc/v1/messages
呼び出し認証
HTTP基本認証を使用して検証を行います。HTTPヘッダーにAuthorizationを追加してください：
Authorization: Basic ${base64_auth_string}
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
POST /v1/messages HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
このコードブロックはフローティングウィンドウ内に表示されます
リクエストボディ
{
"to_ids": [
"8613138283670"
],
"plan_name": "test",
"template": {
"id": 1970314609822883800,
"language": "en",
"params": {
"content": "Verification code: 039487, will expire in 5 minutes. You are trying to create your"
}
},
"source": 1
}
{
"to_ids": [
"8613138283670"
],
"plan_name": "test",
"template": {
"id": 1970314609822883800,
"language": "en",
"params": {
"content": "Verification code: 039487, will expire in 5 minutes. You are trying to create your"
}
},
"source": 1
}
このコードブロックはフローティングウィンドウ内に表示されます
リクエストパラメータ
リクエストオブジェクトはJSON形式で表現されるため、リクエストヘッダーにはContent-Type: application/jsonを含める必要があります。
| 名前 | 場所 | タイプ | 必須 | 日本語名 | 説明 |
|---|---|---|---|---|---|
| Authorization | header | array[string] | No | なし | |
| body | body | object | No | なし | |
| » to_ids | body | [string] | Yes | 送信対象IDリスト | 1つだけの場合は1つだけ渡してください |
| » plan_name | body | string | No | プラン名 | オプション、未入力の場合はデフォルトで"-"が表示されます |
| » schedule_time | body | integer | No | 送信予定時間 | 非スケジュール送信の場合はこのパラメータを渡さないでください、タイムスタンプ形式 |
| » template | body | object | Yes | ||
| »» id | body | string | Yes | なし | |
| »» language | body | string | Yes | なし | |
| »» params | body | object | Yes | なし | |
| »»» custom_param | body | string | Yes | なし | |
| » custom_args | body | object | Yes | カスタムパラメータ |
テンプレート作成時にカスタム変数を設定した場合、ここで値を渡してください。渡さない場合、変数キーがそのまま送信されます（例：{{var1}}）。
paramsの説明
- {{brand_name}}, {{ttl}}, {{pwa_url}}などのテンプレートの事前設定変数については、値を渡す必要はありません。システムがテンプレート作成時に指定された内容で自動的に置き換えます。
- テンプレート作成時にテンプレート内容に含まれるカスタム変数フィールドについては、paramsを通じて値を割り当てます。例えば、テンプレート内容が
Hi {{name}}, welcome to EngageLabの場合、パラメータparams:{"name":"Bob"}を割り当てる必要があります。
リクエスト例
1. カスタム通知内容の送信：
{
"to": "+8618701235678",
"template":{
"id":"notification-template",
"params": {
"order":"123456"
}
}
}
{
"to": "+8618701235678",
"template":{
"id":"notification-template",
"params": {
"order":"123456"
}
}
}
このコードブロックはフローティングウィンドウ内に表示されます
2. カスタムマーケティング内容の送信：
{
"to": "+8618701235678",
"template":{
"id":"marketing-template",
"params": {
"name":"EngageLab",
"promotion":"30%"
}
}
}
{
"to": "+8618701235678",
"template":{
"id":"marketing-template",
"params": {
"name":"EngageLab",
"promotion":"30%"
}
}
}
このコードブロックはフローティングウィンドウ内に表示されます
レスポンスパラメータ
成功レスポンス
HTTPステータスコードは200で、レスポンスボディには以下のフィールドが含まれます：
| フィールド | タイプ | 必須 | 説明 |
|---|---|---|---|
| message_id | String | Yes | メッセージID、メッセージを一意に識別する |
| to_id | String | Yes | 送信先電話番号 |
{
"to_id": "8613138283670",
"message_id": "1971029055205646336"
}
{
"to_id": "8613138283670",
"message_id": "1971029055205646336"
}
このコードブロックはフローティングウィンドウ内に表示されます
失敗レスポンス
HTTPステータスコードは4xxまたは5xxで、レスポンスボディには以下のフィールドが含まれます：
| フィールド | タイプ | 必須 | 説明 |
|---|---|---|---|
| err_code | int | Yes | エラーコード、詳細はエラーコードを参照してください |
| err_msg | String | Yes | エラー詳細 |
{
"err_msg": "sms send failed",
"err_code": 10013
}
{
"err_msg": "sms send failed",
"err_code": 10013
}
このコードブロックはフローティングウィンドウ内に表示されます
エラーコード
| エラーコード | HTTPコード | 説明 |
|---|---|---|
| 1000 | 500 | 内部エラー |
| 2001 | 401 | 認証失敗、トークンが間違っています |
| 2002 | 401 | 認証失敗、トークンが期限切れまたは無効です |
| 2004 | 403 | このAPIを呼び出す権限がありません |
| 3001 | 400 | リクエストパラメータ形式が無効です、JSON形式に準拠しているか確認してください |
| 3002 | 400 | リクエストパラメータが無効です、要件を満たしているか確認してください |
| 3003 | 400 | リクエストパラメータが無効です、関連するビジネス検証に失敗しました、メッセージフィールドのエラー説明を参照してください |
| 3004 | 400 | 頻度制限を超えました、検証コードの有効期間内に同じテンプレートで同じユーザーに再送信できません |
| 4001 | 400 | 関連リソースが存在しません、例えば存在しないテンプレートを使用してテンプレートメッセージを送信する場合 |
| 5001 | 400 | 検証コードメッセージの送信に失敗しました、メッセージフィールドのエラー説明を参照してください |
