ข้อมูลอ้างอิงเหตุการณ์ Callback

การกำหนดค่าและการตรวจสอบ URL Callback

หลังจากกำหนดค่า URL Callback แล้ว EngageLab SMS จะส่งคำขอ HTTP POST ไปยัง URL ดังกล่าวโดยอัตโนมัติหนึ่งครั้ง เพื่อตรวจสอบความพร้อมใช้งานของอินเทอร์เฟซ บริการของคุณต้องส่งกลับรหัสสถานะ HTTP 200 ภายใน 3 วินาที มิฉะนั้นระบบจะถือว่า URL ดังกล่าวไม่สามารถใช้งานได้

หมายเหตุ:
เพื่อให้แน่ใจว่าสามารถรับข้อมูล Callback ได้ตามปกติ โปรดเพิ่ม 119.8.170.74 และ 114.119.180.30 เข้าในไวต์ลิสต์ของไฟร์วอลล์เซิร์ฟเวอร์ของคุณ

ตัวอย่างคำขอ

สมมติว่า URL Callback ของคุณคือ 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 Callback จะพิจารณาเฉพาะรหัสสถานะ HTTP เท่านั้น ไม่กำหนดให้ต้องส่งเนื้อหาข้อความที่เจาะจง โปรดตรวจสอบให้แน่ใจว่าอินเทอร์เฟซบริการของคุณสามารถตอบกลับด้วยรหัส 200 ได้อย่างถูกต้องภายใน 3 วินาที

กลไกความปลอดภัยของ Callback

เพื่อรับประกันความปลอดภัยของข้อมูล Callback และความน่าเชื่อถือของแหล่งที่มา EngageLab SMS รองรับวิธีการตรวจสอบความปลอดภัยหลายรูปแบบ

การตรวจสอบชื่อผู้ใช้และคีย์ลับ (ไม่บังคับ)

  • เป็นการตั้งค่าแบบไม่บังคับ หากตั้งค่าชื่อผู้ใช้ จะต้องตั้งค่าคีย์ลับด้วยพร้อมกัน
  • หลังจากกำหนดค่าแล้ว EngageLab จะเพิ่มฟิลด์ X-CALLBACK-ID ในส่วนหัว HTTP ของคำขอ Callback ทุกครั้ง โดยมีรูปแบบดังนี้:
X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
              
              X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}

            
โค้ดนี้โชว์เป็นหน้าต่างลอย
  • โดยที่:
    • timestamp: ประทับเวลาที่ส่ง Callback
    • nonce: ตัวเลขสุ่ม
    • 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()

            
โค้ดนี้โชว์เป็นหน้าต่างลอย
  • ฝั่งเซิร์ฟเวอร์สามารถใช้วิธีข้างต้นในการตรวจสอบความถูกต้องของคำขอ Callback ได้

การยืนยันตัวตนด้วย Authorization (ไม่บังคับ)

  • หากอินเทอร์เฟซ Callback ของคุณต้องการการยืนยันตัวตน (เช่น Basic Auth, Bearer Token เป็นต้น) คุณสามารถกรอกข้อมูล Authorization ขณะกำหนดค่าได้
  • EngageLab จะแนบฟิลด์ Authorization ดังกล่าวมาพร้อมกับคำขอโดยอัตโนมัติ เพื่อให้บริการของคุณตรวจสอบตัวตนของคำขอได้สะดวก

คำอธิบายเหตุการณ์ Callback

สถานะข้อความ

สถานะข้อความใช้สำหรับติดตามการเปลี่ยนแปลงสถานะของข้อความแต่ละรายการตลอดวงจรชีวิต ใช้เพื่อทราบความคืบหน้าในแต่ละขั้นตอนของการส่ง การนำส่ง และการยืนยันข้อความแบบเรียลไทม์ ช่วยให้สะดวกต่อการวิเคราะห์เชิงสถิติ การจัดการข้อยกเว้น และการปรับปรุงประสบการณ์ผู้ใช้

ตัวระบุเหตุการณ์ คำอธิบาย
plan ข้อความถูกกำหนดให้ส่ง เข้าสู่คิวรอการส่ง
target_valid หมายเลขปลายทางถูกต้อง
target_invalid หมายเลขปลายทางไม่ถูกต้อง
sent ส่งข้อความสำเร็จ
sent_failed ส่งข้อความล้มเหลว
delivered ข้อความถูกนำส่งถึงอุปกรณ์ผู้ใช้
delivered_failed ส่งข้อความแล้ว แต่ไม่สามารถนำส่งถึงอุปกรณ์ผู้ใช้ได้

โครงสร้างข้อมูล Callback

โครงสร้างชั้นนอก

{ "total": 1, "rows": [ { // ออบเจ็กต์ ReportLifecycle } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // ออบเจ็กต์ ReportLifecycle
    }
  ]
}

            
โค้ดนี้โชว์เป็นหน้าต่างลอย
ชื่อฟิลด์ ประเภท คำอธิบาย
total int จำนวนข้อมูลที่รวมอยู่ใน Callback ครั้งนี้
rows array อาร์เรย์ข้อมูลสถานะวงจรชีวิต

ออบเจ็กต์ ReportLifecycle

ชื่อฟิลด์ ประเภท คำอธิบาย
message_id string ID เฉพาะของข้อความ
to string หมายเลขผู้รับ
server string ประเภทบริการ (เช่น SMS)
channel string ประเภทช่องทาง
itime int64 ประทับเวลา Callback (วินาที)
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 การแจ้งเตือนผลการตรวจสอบเทมเพลต

การตอบกลับข้อความ

การตอบกลับข้อความหมายถึงเหตุการณ์การตอบกลับแบบ Callback ในการโต้ตอบกับผู้ใช้หรือระบบภายนอกเป็นหลัก

ตัวระบุเหตุการณ์ คำอธิบาย
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

โครงสร้างข้อมูล Callback

โครงสร้างชั้นนอก

{ "total": 1, "rows": [ { // ออบเจ็กต์เหตุการณ์ระบบ } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // ออบเจ็กต์เหตุการณ์ระบบ
    }
  ]
}

            
โค้ดนี้โชว์เป็นหน้าต่างลอย
ฟิลด์ ประเภท คำอธิบาย
total int64 จำนวนเหตุการณ์ทั้งหมดที่รวมอยู่ใน Callback ครั้งนี้
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": "สร้างคีย์ใหม่" } } }
              
              {
  "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": "สร้างคีย์ใหม่"
    }
  }
}

            
โค้ดนี้โชว์เป็นหน้าต่างลอย

เหตุการณ์การเรียกใช้ API

ฟิลด์ ประเภท คำอธิบาย
api_path string เส้นทางอินเทอร์เฟซ
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"
    }
  }
}

            
โค้ดนี้โชว์เป็นหน้าต่างลอย
Icon Solid Transparent White Qiyu
ติดต่อฝ่ายขาย