Callback Settings

The callback settings are used to configure the callback addresses for your business system to receive real-time "Message Status" and "Message Response" events pushed by the EngageLab NewSMS service. By utilizing callbacks, you can automate message tracking, implement retry strategies, trigger system alerts, and enhance message processing efficiency and system intelligence.

• Message Status: Refers to the status changes of individual SMS messages during various stages such as sending, delivery, read, and verification.
• Message Response: Refers to the content and events of user-replied (uplink) messages.

Callback List

The callback list page displays all configured callback information and their health statuses, enabling unified management and maintenance.

• Search Bar: Supports real-time filtering by callback description to quickly locate target callbacks.
• Configure Callback: Click the button to enter the new callback setup process, allowing flexible expansion of callback requirements.

Field Descriptions

Configure Callback

Click the [Configure Callback] button in the upper-right corner to access the page.

As shown in the image above, fill in the fields such as "Callback Description," "Callback URL," "Username," "Authorization," "Callback Events," and "Message Response."

• Select callback events to push information to your configured callback address when the selected events occur.
• Click the message status and message response options on the right to view corresponding examples.

Configuration Process

When configuring the callback address, the EngageLab NewSMS system will send an HTTP POST request to the specified address. The developer service corresponding to this address must respond with an HTTP status code of 200 within 3 seconds; otherwise, the system will consider the address invalid.

• The developer service only needs to respond with an HTTP status code of 200, without returning a response body.

Request Example

Assuming the configured callback address is https://example.engagelabSMS.callback.com, the system will send the following empty payload to the address. Represented using the curl command:

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

            

Response Example

The developer service corresponding to the callback address only needs to respond with a 200 HTTP status code, as shown below:

              
              HTTP/1.1 200 OK
Content-Length: 0

            

Callback Configuration

• Username Configuration
  This is an optional step. If a username is set, a secret key must also be provided.

  To ensure the authenticity of the message source as EngageLab, you can choose to authenticate the source of POST data.

  After configuring the username and secret key, the data sent by EngageLab will include an HTTP header: X-CALLBACK-ID.
  The value of X-CALLBACK-ID is:
  timestamp={timestamp};nonce={nonce};username={username};signature={signature}

  Example:

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

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

  Este bloque de código se muestra en una ventana flotante
  • timestamp: The timestamp of the callback message (standard format).
  • nonce: A random number.
  • signature: The signature information, calculated as:
    signature=HMAC-SHA256(secret, timestamp+nonce+username)

  Below is a Python code example for calculating the signature:

  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()
  
              

  Este bloque de código se muestra en una ventana flotante

• Authorization Configuration
  This is an optional step. If your callback address requires authentication for EngageLab's requests, provide the authentication information here. EngageLab will include this Authorization header in its requests.

Callback Request Body

When a callback event is triggered, the EngageLab SMS system will send data to the callback address.

"Message Status" Request Example

Message Status:

• plan: Planned to send.
• sent: Sent successfully.
• sent_failed: Sending failed.
• delivered: Delivered successfully.
• delivered_failed: Delivery 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"
                }
            }
        }
    ]
}

            

"Message Response" Request Example

Event:

• uplink_message: 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!"
                }
            }
        }
    ]
}