コールバック設定

概要

EngageLab OTPサービスからビジネスシステムに「メッセージステータス」や「メッセージ通知」のデータコールバックを受信するためのコールバックアドレスを設定し、コールバック情報に基づいてデータ統計、戦略的再送、またはシステムアラートのトリガーを行います。

メッセージステータス: OTPメッセージ送信後のステータス（送信済み、配信済み、既読、検証済みなど）。
メッセージ通知: 主にシステムイベント（例: 検証率の低下や残高不足など）。

コールバックの設定

[設定管理] - [コールバック設定] ページで「コールバックを設定」をクリックし、EngageLab OTPサービスのコールバックを設定します。

EngageLab OTP コールバック設定ボタン

EngageLab OTP コールバック設定詳細

上記のように、「コールバック説明」、「コールバックアドレス」、「ユーザー名」、「認証」、「コールバックイベント」、「メッセージレスポンス」の情報を順に入力します。

コールバックイベントを選択すると、選択したイベントが発生した際に設定したコールバックアドレスに情報がプッシュされます。
右側のメッセージステータスとメッセージレスポンスをクリックして、対応する例を確認できます。

コールバックアドレスの設定

コールバックアドレスを設定すると、EngageLab OTPシステムはこのアドレスにHTTP POSTリクエストを送信します。このアドレスに対応する開発者サービスは、POSTリクエストを受信してから3秒以内にHTTPステータスコード200で応答する必要があります。応答がない場合、システムはアドレスを無効とみなします。

開発者サービスはHTTPステータスコード200で応答するだけでよく、応答メッセージを返す必要はありません。

リクエスト例

設定したコールバックアドレスが https://example.engagelabotp.callback.com であると仮定すると、以下のような空メッセージをこのアドレスに送信します。curlコマンドで表すと以下のようになります:

curl -X POST https://example.engagelabotp.callback.com -d ''

              
              curl -X POST https://example.engagelabotp.callback.com -d ''

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

応答例

このコールバックアドレスに対応する開発者サービスは、POSTリクエストを受信した際に以下のようにHTTPステータスコード200で応答するだけで構いません:

HTTP/1.1 200 OK Content-Length: 0

              
              HTTP/1.1 200 OK
Content-Length: 0

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

コールバックアドレスのセキュリティメカニズム設定

ユーザー名設定

これは任意の操作です。ユーザー名を設定する場合は、シークレットも提供する必要があります。

メッセージの送信元がEngageLabであることを確認するために、POSTデータの送信元に対するセキュリティ認証を選択できます。

ユーザー名とシークレットを設定すると、EngageLabから送信されるデータにはHTTPヘッダー X-CALLBACK-ID が含まれます。 X-CALLBACK-ID の値は timestamp={timestamp};nonce={nonce};username={username};signature={signature} です。

例:

X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b

              
              X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b

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

ここで、timestampはコールバックメッセージのタイムスタンプ（標準）、nonceはランダムな数値、signatureは署名情報です。署名は以下のように計算されます: signature=HMAC-SHA256(secret, timestamp+nonce+username)。

以下はsignatureを計算するPythonコードの例です:

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

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

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

認証設定

これは任意の操作です。EngageLabのリクエストに対してコールバックアドレスが認証を必要とする場合は、ここで認証情報を提供してください。EngageLabはこの認証情報をリクエストに含めます。

コールバックリクエストボディ

コールバックイベントがトリガーされると、EngageLab OTPシステムサービスはデータをコールバックアドレスに送信します。

「メッセージステータス」リクエスト例

メッセージステータス:

plan: 送信予定
sent: 送信済み
sent_failed: 送信失敗
delivered: 配信済み
delivered_failed: 配信失敗
verified: 検証済み
verified_failed: 検証失敗
verified_timeout: 検証タイムアウト

{ "total": 2, // 合計数 "rows": [{ // データ "message_id": "1742442805608914944", // メッセージID "to": "+8615989574757", // 受信者 "server": "otp", // サービス、固定値otp "channel": "otp", // チャンネル、固定値otp "itime": 1704265712, // このデータの作成時間 "status": { // メッセージステータス "message_status": "plan", // メッセージステータス、送信予定はplan、送信済みはsent、送信失敗はsent_failed "status_data": { // ステータスデータ "msg_time": 1704265712, // メッセージ送信時間 "message_id": "1742442805608914944", // メッセージID "current_send_channel": "", // 現在の送信チャンネル、sms、email、voice、whatsappのいずれか; planの場合は空 "template_key": "auto_create_templateu25az170295320745", // テンプレートキー "business_id": "100917676394736" // ビジネスID }, "error_code": 0 } }, { "message_id": "1742442805608914944", "to": "+8615989574757", "server": "otp", "channel": "otp", "itime": 1704265712, "status": { "message_status": "sent_failed", "status_data": { "msg_time": 1704265712, "message_id": "1742442805608914944", "current_send_channel": "whatsapp", "template_key": "auto_create_templateu25az170295320745", "business_id": "100917676394736" }, "error_code":5001, // エラーコード "error_detail":{ // エラー詳細 "message":"sender config is invalid" // エラーメッセージ } } }] }

              
              {
    "total": 2,					// 合計数
    "rows": [{                  // データ
        "message_id": "1742442805608914944",    // メッセージID
        "to": "+8615989574757",            // 受信者
        "server": "otp",                    // サービス、固定値otp
        "channel": "otp",                   // チャンネル、固定値otp
        "itime": 1704265712,                // このデータの作成時間
        "status": {                         // メッセージステータス
            "message_status": "plan",       // メッセージステータス、送信予定はplan、送信済みはsent、送信失敗はsent_failed
            "status_data": {                // ステータスデータ
                "msg_time": 1704265712,     // メッセージ送信時間
                "message_id": "1742442805608914944",    // メッセージID
                "current_send_channel": "",             // 現在の送信チャンネル、sms、email、voice、whatsappのいずれか; planの場合は空
                "template_key": "auto_create_templateu25az170295320745",    // テンプレートキー
                "business_id": "100917676394736"        // ビジネスID
            },
            "error_code": 0
        }
    }, {
        "message_id": "1742442805608914944",
        "to": "+8615989574757",
        "server": "otp",
        "channel": "otp",
        "itime": 1704265712,
        "status": {
            "message_status": "sent_failed",
            "status_data": {
                "msg_time": 1704265712,
                "message_id": "1742442805608914944",
                "current_send_channel": "whatsapp",
                "template_key": "auto_create_templateu25az170295320745",
                "business_id": "100917676394736"
            },
            "error_code":5001,      // エラーコード
            "error_detail":{    // エラー詳細
                "message":"sender config is invalid"        // エラーメッセージ
            }
        }
    }]
}

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

「メッセージ通知」リクエスト例

イベント:

insufficient_balance: 残高がアラート閾値を下回る

{ "total": 1, "rows": [{ "server": "otp", "itime": 1712458844, "notification": { "event": "insufficient_balance", "notification_data": { "business_id": "1744569418236633088", "remain_balance": -0.005, // 現在の残高 "balance_threshold": 2 // アラート閾値 } } }] }

              
              {
    "total": 1,
    "rows": [{
        "server": "otp",
        "itime": 1712458844,
        "notification": {
            "event": "insufficient_balance",
            "notification_data": {
                "business_id": "1744569418236633088",
                "remain_balance": -0.005,                    // 現在の残高
                "balance_threshold": 2                       // アラート閾値
            }
        }
    }]
}

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

「メッセージレスポンス」リクエスト例

イベント:

uplink_message: アップリンクメッセージ

{ "total": 1, "rows": [ { "server": "otp", "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": "otp",
            "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!"
                }
            }
        }
    ]
}

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