Logo Site EngageLab Mark Colored TransparentDocument
SMS
Doc Home
DocumentationAPI Reference
Search
Login
API Reference/Callback Event Reference
API ReferenceCallback Event Reference...

Callback Event Reference

Last updated：5 days ago

Callback URL Configuration and Verification

After configuring the callback URL, EngageLab SMS will automatically send an HTTP POST request to that URL to verify the interface's availability. Your service must return an HTTP 200 status code within 3 seconds, otherwise, the system will consider the URL unavailable.

Note:
To ensure you can receive callback data normally, please add 119.8.170.74 and 114.119.180.30 to your server firewall whitelist.

Request Example

Assuming your callback URL is https://example.engagelabSMS.callback.com, the system will send the following request:

curl -X POST https://example.engagelabSMS.callback.com -d '{}'
              
              curl -X POST https://example.engagelabSMS.callback.com -d '{}'
This code block in the floating window

Response Requirements

Your service only needs to return an HTTP 200 status code and no content. For example:

HTTP/1.1 200 OK Content-Length: 0
              
              HTTP/1.1 200 OK
Content-Length: 0
This code block in the floating window

Note:
Callback URL verification only checks the HTTP status code and does not require returning specific payload content. Make sure your service interface can respond correctly with a 200 within 3 seconds.

Callback Security Mechanisms

To ensure the security and trusted source of callback data, EngageLab SMS supports multiple security verification methods.

Username and Secret Verification (Optional)

  • Optional configuration. If a username is set, a secret must also be set.
  • Once configured, EngageLab adds the X-CALLBACK-ID field to the HTTP Header of every callback request in the following format:
X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
              
              X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
This code block in the floating window
  • Where:
    • timestamp: Timestamp when the callback is sent
    • nonce: Random number
    • username: The username you configured
    • signature: Signature information, calculated as follows

Signature Calculation Method (Python Example)

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()
This code block in the floating window
  • The server can verify the legitimacy of the callback request using the above method.

Authorization Authentication (Optional)

  • If your callback interface requires authentication (such as Basic Auth, Bearer Token, etc.), you can fill in the Authorization information during configuration.
  • EngageLab will automatically include this Authorization field when requesting, making it easy for your service to verify the request's identity.

Callback Event Instructions

Message Status

Message status is used to track the state changes of each message throughout its lifecycle. It provides real-time visibility into the progress of sending, delivery, and verification, facilitating statistical analysis, exception handling, and user experience optimization.

Event Identifier Description
plan Message planned for sending, enters pending queue
target_valid Target number is valid
target_invalid Target number is invalid
sent Message successfully sent
sent_failed Message sending failed
delivered Message delivered to the user's device
delivered_failed Message sent, but failed to deliver to the device

Callback Data Structure

Outer Structure

{ "total": 1, "rows": [ { // ReportLifecycle object } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // ReportLifecycle object
    }
  ]
}
This code block in the floating window
Field Name Type Description
total int Number of data items in this callback
rows array Array of lifecycle status data

ReportLifecycle Object

Field Name Type Description
message_id string Unique message ID
to string Recipient number
server string Service type (e.g., SMS)
channel string Channel type
itime int64 Callback timestamp (seconds)
custom_args object Custom arguments (returned if passed)
status object Status detail object

status Object

Field Name Type Description
message_status string Current status of the message (see table below)
status_data object Status data object
billing object Billing information object (returned if billed)
error_code int Error code, 0 indicates no error
error_detail object Error details (returned when an error occurs)

status_data Object

Field Name Type Description
msg_time int64 Message creation timestamp (seconds)
message_id string Message ID
current_send_channel string Current sending channel name
template_key string Template configuration Key
business_id string Business ID
plan_id string Plan ID

billing Object (Returned if billed)

Field Name Type Description
cost float64 Expense amount
currency string Currency, fixed as "USD"

Generally, only messages in the sent stage contain billing information.

error_detail Object (Returned when an error occurs)

Field Name Type Description
message string Error message description

Example: Message Sent Successfully

{ "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
      }
    }
  ]
}
This code block in the floating window

Example: Message Sending Failed

{ "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"
        }
      }
    }
  ]
}
This code block in the floating window

Message Notification

Message notification refers to system-level business events or alerts. It is used to remind the business to pay attention to service operation status, balance, template review, and other important information, facilitating timely processing and risk warning.

Event Identifier Description
template_audit_result Notification of template review result

Message Response

Message response mainly refers to the callback response events when interacting with users or external systems.

Event Identifier Description
uplink_message Content of upstream messages replied by users via SMS, etc.

Example

{ "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!"
                }
            }
        }
    ]
}
This code block in the floating window

System Events

System events cover operational behaviors related to accounts, templates, API calls, etc. It facilitates monitoring, auditing, and automated processing of key operations like account logins, key changes, API calls, etc.

Event Identifier Description
account_login Notification of account login related operations
key_manage Notification of key changes, management, etc. operations
template_manage Notification of template addition, modification, deletion, etc. operations
api_call Notification of API interface call related operations

Callback Data Structure

Outer Structure

{ "total": 1, "rows": [ { // System event object } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // System event object
    }
  ]
}
This code block in the floating window
Field Type Description
total int64 Total number of events in this callback
rows array Array of system event objects

System Event Object

Field Type Description
server string Fixed as "SMS"
itime int64 Event occurrence timestamp (seconds)
system_event object System event content

system_event Object

Field Type Description
event string Event type
data object Event data

data Object

Field Type Description
business_id string Business ID
org_id string Organization ID
operator object Operator information

operator Object

Field Type Description
email string Operator email (if any)
api_key string API Key (if any)
ip_address string Operating IP

Request Structure

{ "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"
          }
        }
      }
    }
  ]
}
This code block in the floating window

Account Login Event

Field Type Description
action string Login success/Login failed/Logout
fail_reason string Reason for login failure, returned only when login_failed

Example

{ "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"
    }
  }
}
This code block in the floating window

Template Management Event

Field Type Description
action string Create template/Update template/Delete template
template_id string Template ID
template_name string Template name

Example

{ "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"
    }
  }
}
This code block in the floating window

Key Management Event

Field Type Description
action string Create key/Update key/Delete key/View key
api_key string API Key
description string Description (optional)

Example

{ "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"
    }
  }
}
This code block in the floating window

API Call Event

Field Type Description
api_path string API path
method string HTTP method

Example

{ "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"
    }
  }
}
This code block in the floating window
Icon Solid Transparent White Qiyu
Contact Sales