ข้อมูลอ้างอิงเหตุการณ์ 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 '{}'
ข้อกำหนดของการตอบกลับ
บริการของคุณเพียงแค่ส่งกลับรหัสสถานะ HTTP 200 โดยไม่ต้องส่งเนื้อหาใด ๆ ตัวอย่างเช่น:
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}
- โดยที่:
timestamp: ประทับเวลาที่ส่ง Callbacknonce: ตัวเลขสุ่ม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()
- ฝั่งเซิร์ฟเวอร์สามารถใช้วิธีข้างต้นในการตรวจสอบความถูกต้องของคำขอ 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 | 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": "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!"
}
}
}
]
}
เหตุการณ์ระบบ
เหตุการณ์ระบบครอบคลุมพฤติกรรมการดำเนินการที่เกี่ยวข้องกับบัญชี เทมเพลต การเรียกใช้ API เป็นต้น เพื่อความสะดวกในการตรวจสอบ การตรวจสอบย้อนหลัง และการประมวลผลอัตโนมัติสำหรับการดำเนินการสำคัญ เช่น การเข้าสู่ระบบบัญชี การเปลี่ยนแปลงคีย์ และการเรียกใช้ API
| ตัวระบุเหตุการณ์ | คำอธิบาย |
|---|---|
| account_login | การแจ้งเตือนการดำเนินการที่เกี่ยวข้องกับการเข้าสู่ระบบบัญชี |
| key_manage | การแจ้งเตือนการดำเนินการที่เกี่ยวข้องกับการเปลี่ยนแปลงและจัดการคีย์ |
| template_manage | การแจ้งเตือนการดำเนินการ เช่น การเพิ่ม แก้ไข ลบเทมเพลต |
| api_call | การแจ้งเตือนการดำเนินการที่เกี่ยวข้องกับการเรียกใช้อินเทอร์เฟซ API |
โครงสร้างข้อมูล Callback
โครงสร้างชั้นนอก
{
"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
| ฟิลด์ | ประเภท | คำอธิบาย |
|---|---|---|
| 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"
}
}
}
}
]
}
เหตุการณ์การเข้าสู่ระบบบัญชี
| ฟิลด์ | ประเภท | คำอธิบาย |
|---|---|---|
| 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"
}
}
}
เหตุการณ์การจัดการเทมเพลต
| ฟิลด์ | ประเภท | คำอธิบาย |
|---|---|---|
| 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"
}
}
}
เหตุการณ์การจัดการคีย์
| ฟิลด์ | ประเภท | คำอธิบาย |
|---|---|---|
| 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": "สร้างคีย์ใหม่"
}
}
}
เหตุการณ์การเรียกใช้ 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"
}
}
}










