コールバック設定

コールバック設定は、EngageLab NewSMS サービスがリアルタイムの「メッセージステータス」および「メッセージ応答」イベントをプッシュするための、ビジネスシステムのコールバックアドレスを構成するために使用されます。コールバックを利用することで、メッセージトラッキングの自動化、リトライポリシーの実施、システムアラートのトリガー、メッセージ処理効率とシステムのインテリジェンス向上を実現できます。

• メッセージステータス：単一のSMSが送信、配信、閲覧、検証などの各段階でのステータス変化を指します。
• メッセージ応答：ユーザーが返信（上り）したメッセージの内容とイベントを指します。

コールバックリスト

コールバックリストページでは、すべての構成済みコールバック情報とそのヘルスステータスが表示され、統一管理とメンテナンスが容易になります。

• 検索バー：コールバックの説明を使用してリアルタイムでフィルタリングし、ターゲットコールバックを迅速に特定できます。
• コールバックを構成：ボタンをクリックして新しいコールバック設定プロセスに進み、コールバック要件を柔軟に拡張します。

フィールド説明

コールバックを構成

右上の [コールバックを構成] ボタンをクリックしてページに進みます。

上記の図のように、「コールバック説明」、「コールバック URL」、「ユーザー名」、「認証」、「コールバックイベント」および「メッセージ応答」などのフィールドを入力します。

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

設定プロセス

コールバックアドレスを設定する際、EngageLab NewSMS システムは指定されたアドレスに HTTP POST リクエストを送信します。対応するアドレスの開発者サービスは 3 秒以内に HTTP ステータスコード 200 を返す必要があります。そうでない場合、システムはそのアドレスを無効とみなします。

• 開発者サービスは HTTP ステータスコード 200 のみを返す必要があり、レスポンスボディを返す必要はありません。

リクエスト例

設定されたコールバックアドレスが https://example.engagelabSMS.callback.com であると仮定し、システムは以下の空ペイロードをそのアドレスに送信します。curl コマンドを使用した例は以下の通りです：

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

            

レスポンス例

対応するコールバックアドレスの開発者サービスは、以下のように 200 HTTP ステータスコードのみを返す必要があります：

              
              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.encode(), msg='{}{}{}'.format(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='{}{}{}'.format(timestamp, nonce, username).encode(),
          digestmod=hashlib.sha256
      ).hexdigest()
  
              

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

• 認証設定
  これはオプションのステップです。コールバックアドレスが EngageLab のリクエストを認証する必要がある場合、ここで認証情報を提供してください。EngageLab はリクエストにこの Authorization ヘッダーを含めます。

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

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

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

メッセージステータス：

• plan：送信予定。
• sent：送信成功。
• sent_failed：送信失敗。
• delivered：配信成功。
• delivered_failed：配信失敗。

              
              {
    "total": 2,
    "rows": [
        {
            "message_id": "1742442805608914944",
            "to": "+8615989574757",
            "server": "SMS",
            "channel": "SMS",
            "itime": 1704265712,
            "status": {
                "message_status": "plan",
                "status_data": {
                    "msg_time": 1704265712,
                    "message_id": "1742442805608914944",
                    "current_send_channel": "",
                    "template_key": "auto_create_templateu25az170295320745",
                    "business_id": "100917676394736"
                },
                "error_code": 0
            }
        },
        {
            "message_id": "1742442805608914944",
            "to": "+8615989574757",
            "server": "SMS",
            "channel": "SMS",
            "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"
                }
            }
        }
    ]
}

            

「メッセージ応答」リクエスト例

イベント：

• uplink_message：上りメッセージ。

              
              {
    "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!"
                }
            }
        }
    ]
}