コールバックイベントリファレンス

コールバックURLの設定と検証

コールバックURLを設定すると、EngageLab SMSはそのURLへ自動的にHTTP POSTリクエストを送信し、インターフェースの可用性を検証します。あなたのサービスは3秒以内にHTTP 200ステータスコードを返す必要があります。返さない場合、システムはURLが利用不可とみなします。

注意：
コールバックデータを正常に受信できるようにするため、119.8.170.74 と 114.119.180.30 をサーバーのファイアウォールのホワイトリストに追加してください。

リクエスト例

コールバックURLが https://example.engagelabSMS.callback.com であると仮定すると、システムは次のリクエストを送信します。

curl -X POST https://example.engagelabSMS.callback.com -d '{}'

              
              curl -X POST https://example.engagelabSMS.callback.com -d '{}'

このコードブロックはフローティングウィンドウ内に表示されます

レスポンス要件

あなたのサービスは、HTTP 200ステータスコードを返すだけでよく、内容は不要です。例：

HTTP/1.1 200 OK Content-Length: 0

              
              HTTP/1.1 200 OK
Content-Length: 0

このコードブロックはフローティングウィンドウ内に表示されます

注意：
コールバックURLの検証はHTTPステータスコードのみを確認し、特定のペイロード内容を返す必要はありません。サービスインターフェースが3秒以内に200で正しく応答できることを確認してください。

コールバックのセキュリティメカニズム

コールバックデータの安全性と送信元の信頼性を確保するため、EngageLab SMSは複数のセキュリティ検証方式に対応しています。

UsernameおよびSecretによる検証（任意）

任意の設定です。usernameを設定する場合は、secretも設定する必要があります。
設定すると、EngageLabはすべてのコールバックリクエストのHTTPヘッダーに X-CALLBACK-ID フィールドを次の形式で追加します。

X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}

              
              X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}

このコードブロックはフローティングウィンドウ内に表示されます

各項目の意味：
- timestamp：コールバック送信時のタイムスタンプ
- nonce：乱数
- username：設定したusername
- signature：署名情報。以下のとおり計算されます

署名の計算方法（Pythonの例）

import hashlib, hmac def verify(username, secret, timestamp, nonce, signature): return signature == hmac.new( key=secret.encode(), msg=f'{timestamp}{nonce}{username}'.encode(), digestmod=hashlib.sha256 ).hexdigest()

              
              import hashlib, hmac
def verify(username, secret, timestamp, nonce, signature):
    return signature == hmac.new(
        key=secret.encode(),
        msg=f'{timestamp}{nonce}{username}'.encode(),
        digestmod=hashlib.sha256
    ).hexdigest()

このコードブロックはフローティングウィンドウ内に表示されます

サーバーは上記の方法でコールバックリクエストの正当性を検証できます。

Authorizationによる認証（任意）

コールバックインターフェースで認証（Basic Auth、Bearer Tokenなど）が必要な場合は、設定時にAuthorization情報を入力できます。
EngageLabはリクエスト時にこのAuthorizationフィールドを自動的に含めるため、あなたのサービスはリクエストの身元を容易に検証できます。

コールバックイベントの説明

メッセージステータス

メッセージステータスは、各メッセージのライフサイクル全体にわたるステータスの変化を追跡するために使用されます。送信、配信、検証の進捗をリアルタイムに可視化し、統計分析、例外処理、ユーザー体験の最適化を容易にします。

イベント識別子	説明
plan	送信が計画され、送信待ちキューに入る
target_valid	対象番号が有効
target_invalid	対象番号が無効
sent	メッセージの送信に成功
sent_failed	メッセージの送信に失敗
delivered	メッセージがユーザーの端末に到達
delivered_failed	メッセージは送信されたが、端末への配信に失敗

コールバックのデータ構造

外側の構造

{ "total": 1, "rows": [ { // ReportLifecycle object } ] }

              
              {
  "total": 1,
  "rows": [
    {
      // ReportLifecycle object
    }
  ]
}

このコードブロックはフローティングウィンドウ内に表示されます

フィールド名	型	説明
total	int	このコールバックのデータ件数
rows	array	ライフサイクルステータスデータの配列

ReportLifecycleオブジェクト

フィールド名	型	説明
message_id	string	メッセージの一意なID
to	string	受信者番号
server	string	サービス種別（例：SMS）
channel	string	チャネル種別
itime	int64	コールバックのタイムスタンプ（秒）
custom_args	object	カスタム引数（渡された場合に返される）
status	object	ステータス詳細オブジェクト

statusオブジェクト

フィールド名	型	説明
message_status	string	メッセージの現在のステータス（下表を参照）
status_data	object	ステータスデータオブジェクト
billing	object	課金情報オブジェクト（課金された場合に返される）
error_code	int	エラーコード。0はエラーなしを示す
error_detail	object	エラーの詳細（エラー発生時に返される）

status_dataオブジェクト

フィールド名	型	説明
msg_time	int64	メッセージ作成タイムスタンプ（秒）
message_id	string	メッセージID
current_send_channel	string	現在の送信チャネル名
template_key	string	テンプレート設定Key
business_id	string	ビジネスID
plan_id	string	プランID

billingオブジェクト（課金された場合に返される）

フィールド名	型	説明
cost	float64	費用額
currency	string	通貨。"USD" 固定

一般的に、課金情報を含むのはsent段階のメッセージのみです。

error_detailオブジェクト（エラー発生時に返される）

フィールド名	型	説明
message	string	エラーメッセージの説明

例：メッセージの送信に成功

{ "total": 1, "rows": [ { "message_id": "123456789", "to": "+6598765432", "server": "sms", "channel": "sms", "itime": 1701234567, "custom_args": { "order_id": "ORDER123", "user_id": "USER456" }, "status": { "message_status": "sent", "status_data": { "msg_time": 1701234560, "message_id": "123456789", "current_send_channel": "CHANNEL_A", "template_key": "verify_code", "business_id": "1001", "plan_id": "7198765432109876543" }, "billing": { "cost": 0.005, "currency": "USD" }, "error_code": 0 } } ] }

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456789",
      "to": "+6598765432",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234567,
      "custom_args": {
        "order_id": "ORDER123",
        "user_id": "USER456"
      },
      "status": {
        "message_status": "sent",
        "status_data": {
          "msg_time": 1701234560,
          "message_id": "123456789",
          "current_send_channel": "CHANNEL_A",
          "template_key": "verify_code",
          "business_id": "1001",
          "plan_id": "7198765432109876543"
        },
        "billing": {
          "cost": 0.005,
          "currency": "USD"
        },
        "error_code": 0
      }
    }
  ]
}

このコードブロックはフローティングウィンドウ内に表示されます

例：メッセージの送信に失敗

{ "total": 1, "rows": [ { "message_id": "123456790", "to": "+6598765433", "server": "sms", "channel": "sms", "itime": 1701234568, "status": { "message_status": "sent_fail", "status_data": { "msg_time": 1701234561, "message_id": "123456790", "current_send_channel": "CHANNEL_B", "template_key": "verify_code", "business_id": "1001", "plan_id": "7198765432109876543" }, "error_code": 4001, "error_detail": { "message": "Invalid phone number" } } } ] }

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456790",
      "to": "+6598765433",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234568,
      "status": {
        "message_status": "sent_fail",
        "status_data": {
          "msg_time": 1701234561,
          "message_id": "123456790",
          "current_send_channel": "CHANNEL_B",
          "template_key": "verify_code",
          "business_id": "1001",
          "plan_id": "7198765432109876543"
        },
        "error_code": 4001,
        "error_detail": {
          "message": "Invalid phone number"
        }
      }
    }
  ]
}

このコードブロックはフローティングウィンドウ内に表示されます

メッセージ通知

メッセージ通知とは、システムレベルの業務イベントやアラートを指します。サービスの稼働状況、残高、テンプレート審査などの重要情報に注意を促し、タイムリーな対応とリスク警告を容易にします。

イベント識別子	説明
template_audit_result	テンプレート審査結果の通知

メッセージレスポンス

メッセージレスポンスとは、主にユーザーや外部システムとのやり取りにおけるコールバックのレスポンスイベントを指します。

イベント識別子	説明
uplink_message	ユーザーがSMSなどで返信した上り（受信）メッセージの内容

例

{ "total": 1, "rows": [ { "server": "SMS", "itime": 1741083306, "message_id": "0", "business_id": "0", "response": { "event": "uplink_message", "response_data": { "message_sid": "SM1234567890", "account_sid": "AC1234567890", "from": "+1234567890", "to": "+0987654321", "body": "Hello, it's time to struggle!" } } } ] }

              
              {
    "total": 1,
    "rows": [
        {
            "server": "SMS",
            "itime": 1741083306,
            "message_id": "0",
            "business_id": "0",
            "response": {
                "event": "uplink_message",
                "response_data": {
                    "message_sid": "SM1234567890",
                    "account_sid": "AC1234567890",
                    "from": "+1234567890",
                    "to": "+0987654321",
                    "body": "Hello, it's time to struggle!"
                }
            }
        }
    ]
}

このコードブロックはフローティングウィンドウ内に表示されます

システムイベント

システムイベントは、アカウント、テンプレート、API呼び出しなどに関連する操作行為を対象とします。アカウントログイン、キー変更、API呼び出しといった重要な操作の監視、監査、自動処理を容易にします。

イベント識別子	説明
account_login	アカウントログイン関連操作の通知
key_manage	キーの変更や管理などの操作の通知
template_manage	テンプレートの追加、変更、削除などの操作の通知
api_call	APIインターフェース呼び出し関連操作の通知

コールバックのデータ構造

外側の構造

{ "total": 1, "rows": [ { // System event object } ] }

              
              {
  "total": 1,
  "rows": [
    {
      // System event object
    }
  ]
}

このコードブロックはフローティングウィンドウ内に表示されます

フィールド	型	説明
total	int64	このコールバックのイベント総数
rows	array	システムイベントオブジェクトの配列

システムイベントオブジェクト

フィールド	型	説明
server	string	"SMS" 固定
itime	int64	イベント発生タイムスタンプ（秒）
system_event	object	システムイベントの内容

system_eventオブジェクト

フィールド	型	説明
event	string	イベント種別
data	object	イベントデータ

dataオブジェクト

フィールド	型	説明
business_id	string	ビジネスID
org_id	string	組織ID
operator	object	操作者情報

operatorオブジェクト

フィールド	型	説明
email	string	操作者のメール（ある場合）
api_key	string	API Key（ある場合）
ip_address	string	操作元IP

リクエスト構造

{ "total": 1, "rows": [ { "server": "SMS", "itime": 1694012345, "system_event": { "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "api_key": "api-xxxx", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } } } ] }

              
              {
  "total": 1,
  "rows": [
    {
      "server": "SMS",
      "itime": 1694012345,
      "system_event": {
        "event": "account_login",
        "data": {
          "business_id": "123",
          "org_id": "org-abc",
          "operator": {
            "email": "foo@example.com",
            "api_key": "api-xxxx",
            "ip_address": "1.2.3.4"
          },
          "account_login": {
            "action": "login_success"
          }
        }
      }
    }
  ]
}

このコードブロックはフローティングウィンドウ内に表示されます

アカウントログインイベント

フィールド	型	説明
action	string	ログイン成功／ログイン失敗／ログアウト
fail_reason	string	ログイン失敗の理由。login_failedの場合のみ返される

例

{ "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } }

              
              {
  "event": "account_login",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "account_login": {
      "action": "login_success"
    }
  }
}

このコードブロックはフローティングウィンドウ内に表示されます

テンプレート管理イベント

フィールド	型	説明
action	string	テンプレート作成／テンプレート更新／テンプレート削除
template_id	string	テンプレートID
template_name	string	テンプレート名

例

{ "event": "template_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "template_manage": { "action": "update template", "template_id": "tmpl-456", "template_name": "Verification Code" } } }

              
              {
  "event": "template_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "template_manage": {
      "action": "update template",
      "template_id": "tmpl-456",
      "template_name": "Verification Code"
    }
  }
}

このコードブロックはフローティングウィンドウ内に表示されます

キー管理イベント

フィールド	型	説明
action	string	キー作成／キー更新／キー削除／キー閲覧
api_key	string	API Key
description	string	説明（任意）

例

{ "event": "key_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "key_manage": { "action": "create", "api_key": "apikey-789", "description": "Create key" } } }

              
              {
  "event": "key_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "key_manage": {
      "action": "create",
      "api_key": "apikey-789",
      "description": "Create key"
    }
  }
}

このコードブロックはフローティングウィンドウ内に表示されます

API呼び出しイベント

フィールド	型	説明
api_path	string	APIパス
method	string	HTTPメソッド

例

{ "event": "api_call", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "api_key": "apikey-789", "ip_address": "1.2.3.4" }, "api_call": { "api_path": "/api/v1/messages/send", "method": "POST" } } }

              
              {
  "event": "api_call",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "api_key": "apikey-789",
      "ip_address": "1.2.3.4"
    },
    "api_call": {
      "api_path": "/api/v1/messages/send",
      "method": "POST"
    }
  }
}

このコードブロックはフローティングウィンドウ内に表示されます