การเรียกกลับ API

อัพเดทล่าสุด ：2025-07-22

API คอลแบ็ค

ภาพรวม

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

ที่อยู่คอลแบ็ค

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

การตรวจสอบความถูกต้องของที่อยู่คอลแบ็ค

เมื่อกำหนดที่อยู่คอลแบ็คในการจัดการหลังบ้านของ Push ภายใต้การตั้งค่าแอปพลิเคชัน จะมีการส่งคำขอ POST พร้อมด้วยพารามิเตอร์ echostr ที่สร้างขึ้นแบบสุ่มเป็นสตริง 8 ตัวอักษรในเนื้อหาคำขอ คุณต้องส่งคืนค่าของ echostr ในตัวตอบกลับดังตัวอย่างด้านล่าง:

เนื้อหาคำขอ (Request Body):

{ "echostr": "12345678" }

              
              {
    "echostr": "12345678"
}

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

เนื้อหาตอบกลับ (Response Body):

12345678

12345678

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

กลไกการรักษาความปลอดภัย

ใช้สำหรับการยืนยันตัวตนของลูกค้า (ไม่บังคับ)

เพื่อให้มั่นใจว่าแหล่งที่มาของข้อความมาจาก EngageLab คุณสามารถเลือกที่จะตรวจสอบแหล่งที่มาของข้อมูล POST ได้ หรือคุณสามารถแยกข้อมูล POST โดยไม่ต้องตรวจสอบตัวตน

วิธีการยืนยันตัวตนคือ:

กำหนดชื่อผู้ใช้คอลแบ็ค (username) และรหัสลับคอลแบ็ค (secret) ในคอนโซลของ EngageLab สำหรับที่อยู่คอลแบ็ค

รับค่า X-CALLBACK-ID จากส่วนหัวของคำขอ ตามตัวอย่างด้านล่าง:

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=HMAC-SHA256(secret, timestamp+nonce+username)

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

กลไกการตอบกลับ

หลังจากที่บริการนักพัฒนารับข้อความคอลแบ็คจาก EngageLab แล้ว จำเป็นต้องตอบกลับภายใน 3 วินาทีตามข้อกำหนดดังนี้:

ได้รับข้อความสำเร็จ: รหัสสถานะ HTTP ควรคืนค่า 200 หรือ 204 และไม่จำเป็นต้องมีข้อความตอบกลับ
ไม่ได้รับข้อความ: รหัสสถานะ HTTP ควรคืนค่า 5XX หรือ 4XX และมีข้อความตอบกลับ ข้อความควรมีรูปแบบดังนี้:

{ "code": 2002, "message": "error" }

              
              {
    "code": 2002,
    "message": "error"
}

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

ฟิลด์	ประเภท	จำเป็น/ไม่จำเป็น	คำอธิบาย
`code`	int	ไม่จำเป็น	รหัสข้อผิดพลาด
`message`	string	ไม่จำเป็น	รายละเอียดข้อผิดพลาด

คำอธิบายฟิลด์คอลแบ็ค

เนื้อหาข้อความ

ชื่อฟิลด์	ประเภท	จำเป็น/ไม่จำเป็น	คำอธิบาย
`total`	int	จำเป็น	จำนวนข้อความที่รวมอยู่ในคอลแบ็คนี้
`rows`	array	จำเป็น	รายการข้อมูลรายละเอียดเกี่ยวกับการเปลี่ยนแปลงสถานะของข้อความ รวมฟิลด์ด้านล่าง:

ฟิลด์ในอาร์เรย์ `rows`

ชื่อฟิลด์	ประเภท	จำเป็น/ไม่จำเป็น	คำอธิบาย
`message_id`	string	จำเป็น	รหัสเฉพาะของข้อความ
`from`	string	ไม่จำเป็น	ผู้ส่ง (ค่าเริ่มต้นคือ appkey)
`to`	string	ไม่จำเป็น	รหัสผู้รับ (เช่น `registrationID`)
`server`	string	จำเป็น	ชื่อบริการข้อความ ค่าที่เป็นไปได้: `AppPush`, `WebPush`
`channel`	string	จำเป็น	ช่องทางข้อความ ค่าที่เป็นไปได้: `EngageLab`, `HuaWei`, `XiaoMi`, `MeiZu`, `OPPO`, `VIVO`, `HONOR`, `FCM`, `APNs`
`custom_args`	object	ไม่จำเป็น	พารามิเตอร์ที่ส่งเพิ่มเติมในระหว่างการสร้างข้อความ จะถูกส่งคืนตามค่าเดิม
`itime`	int	จำเป็น	เวลาที่เกิดเหตุการณ์สถานะของข้อความ สามารถใช้ร่วมกับ `message_status` เพื่อให้ได้เวลาของสถานะข้อความแต่ละสถานะ
`status`	object	จำเป็น	ข้อมูลสถานะข้อความ รวมถึงฟิลด์ด้านล่าง:

ฟิลด์ในอ็อบเจ็กต์ `status`

ชื่อฟิลด์	ประเภท	จำเป็น/ไม่จำเป็น	คำอธิบาย
`message_status`	string	จำเป็น	สถานะข้อความ ค่าที่เป็นไปได้: `target_valid`, `sent`, `delivered`, `click`, `target_invalid`, `sent_failed`, `delivered_failed`, `no_click`
`status_data`	object	ไม่จำเป็น	ข้อมูลสถานะที่กำหนดเอง มีฟิลด์ดังนี้:
`channel_message_id`	string	ไม่จำเป็น	รหัสข้อความจากช่องทางของบุคคลที่สาม
`ntf_msg`	int	จำเป็น	ประเภทข้อความ ค่าที่เป็นไปได้: `1: Notification`, `2: Custom Message`, `5: iOS Real-Time Activity`, `6: iOS VOIP Message`, `7: In-App Message`
`platform`	string	จำเป็น	แพลตฟอร์มของการส่งข้อความ ค่าที่เป็นไปได้: `a: Android`, `i: iOS`, `b: Web`
`uid`	int	จำเป็น	UID ของผู้รับข้อความ
`app_version`	string	จำเป็น	เวอร์ชันของแอปที่รวม SDK ที่ได้รับข้อมูลจากการรายงาน SDK
`channel`	string	จำเป็น	ช่องทางแอปที่รวม SDK ที่ได้รับข้อมูลจากการรายงาน SDK
`msg_time`	int	จำเป็น	เวลาในการส่งข้อความ เวลาเมื่อคำขอ API ส่งข้อความสำเร็จ
`time_zone`	string	จำเป็น	โซนเวลาองค์กร
`loss_valid_type`	int	ไม่จำเป็น	ฟิลด์นี้ไม่มีความสำคัญและไม่จำเป็นต้องประมวลผล
`plan_user_total`	int	ไม่จำเป็น	ฟิลด์นี้ไม่มีความสำคัญและไม่จำเป็นต้องประมวลผล
`callback_type`	int	ไม่จำเป็น	ฟิลด์นี้ไม่มีความสำคัญและไม่จำเป็นต้องประมวลผล
`error_code`	int	ไม่จำเป็น	รหัสข้อผิดพลาด เฉพาะในกรณีที่เกิดความล้มเหลว
`error_detail`	object	ไม่จำเป็น	ข้อมูลข้อผิดพลาดที่ละเอียด เฉพาะในกรณีที่เกิดความล้มเหลว มีฟิลด์ดังนี้:
`message`	string	ไม่จำเป็น	คำอธิบายเหตุผลข้อผิดพลาด ใช้ได้เฉพาะสำหรับช่องทาง FCM
`loss`	object	ไม่จำเป็น	ข้อมูลการสูญเสีย มีฟิลด์ดังนี้:
`loss_source`	string	ไม่จำเป็น	แหล่งที่มาของการสูญเสีย ค่าที่เป็นไปได้: `EngageLab`, `HuaWei`, `XiaoMi`, `MeiZu`, `OPPO`, `VIVO`, `HONOR`, `FCM`, `APNs`
`loss_step`	int	ไม่จำเป็น	ขั้นตอนการสูญเสีย ค

คำอธิบายฟิลด์ Callback

่าที่เป็นไปได้: 1: Plan Target → Valid Target, 2: Valid Target → Sent Quantity, 3: Sent Quantity → Delivered Quantity, 4: Delivered Quantity → Click Quantity |

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

ค่าของสถานะ	ความหมาย	คำอธิบาย
`target_valid`	เป้าหมายที่ใช้ได้	ถือว่าใช้ได้หากมีการใช้งานใน 365 วันที่ผ่านมา
`sent`	ส่งสำเร็จ	ส่งสำเร็จไปยังเซิร์ฟเวอร์
`delivered`	ส่งมอบสำเร็จ	สำหรับ `EngageLab`, `XiaoMi`, `OPPO`, `VIVO` — ส่งมอบตามคอลแบ็คจริง; สำหรับ `FCM` และ `APNs` — ส่งมอบเมื่อส่งไปยังเซิร์ฟเวอร์ของผู้ให้บริการสำเร็จ; สำหรับ `HuaWei`, `MeiZu`, `HONOR`, หากไม่ได้กำหนดคอลแบ็คของผู้ให้บริการ จะถือว่าส่งมอบเมื่อส่งไปยังเซิร์ฟเวอร์ของผู้ให้บริการสำเร็จ; ถ้ากำหนดแล้ว ส่งมอบตามคอลแบ็คจริงจากผู้ให้บริการ
`click`	ผู้ใช้คลิก	ผู้ใช้คลิกตามที่ SDK รายงาน
`target_invalid`	เป้าหมายไม่ใช้ได้	ถือว่าไม่ใช้ได้ตามขั้นตอนการสูญเสีย 1 ที่กำหนดในตารางการสูญเสีย
`sent_failed`	ส่งล้มเหลว	ถือว่าไม่ใช้ได้ตามขั้นตอนการสูญเสีย 2 ที่กำหนดในตารางการสูญเสีย
`delivered_failed`	ส่งมอบล้มเหลว	ถือว่าไม่สำเร็จตามขั้นตอนการสูญเสีย 3 ที่กำหนดในตารางการสูญเสีย
`no_click`	คลิกล้มเหลว	ถือว่าไม่สำเร็จตามขั้นตอนการสูญเสีย 4 ที่กำหนดในตารางการสูญเสีย ใช้กับข้อความในแอปเท่านั้น

คำอธิบายเนื้อหาคอลแบ็ค

วิธีคอลแบ็ค: POST ประเภทเนื้อหา: application/json

ตัวอย่าง

ส่วนหัวคำขอ

POST /developer_define_url HTTP/1.1 Content-Type: application/json

              
              POST /developer_define_url HTTP/1.1
Content-Type: application/json

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

เนื้อหาคำขอ

{ "total": 1, "rows": [ { "message_id": "1666165485030094861", "from": "", "to": "", "server": "AppPush", "channel": "FCM", "custom_args": {}, "itime": 1640707579, "status": { "message_status": "delivered", "status_data": { "channel_message_id": "wamid.123321abcdefed==", "ntf_msg": 1, "platform": "a", "uid": 100, "app_version": "", "channel": "", "msg_time": 1640707579, "time_zone": "+8", "loss_valid_type": 0, "plan_user_total": 0, "callback_type": 0 }, "error_code": 0, "error_detail": { "message": "" }, "loss": { "loss_source": "vivo", "loss_step": 1 } } } ] }

              
              {
    "total": 1,
    "rows": [
        {
            "message_id": "1666165485030094861",
            "from": "",
            "to": "",
            "server": "AppPush",
            "channel": "FCM",
            "custom_args": {},
            "itime": 1640707579,
            "status": {
                "message_status": "delivered",
                "status_data": {
                    "channel_message_id": "wamid.123321abcdefed==",
                    "ntf_msg": 1,
                    "platform": "a",
                    "uid": 100,
                    "app_version": "",
                    "channel": "",
                    "msg_time": 1640707579,
                    "time_zone": "+8",
                    "loss_valid_type": 0,
                    "plan_user_total": 0,
                    "callback_type": 0
                },
                "error_code": 0,
                "error_detail": {
                    "message": ""
                },
                "loss": {
                    "loss_source": "vivo",
                    "loss_step": 1
                }
            }
        }
    ]
}

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

คำอธิบายพารามิเตอร์

ค่าของสถานะ	ความหมาย
`target_valid`	เป้าหมายที่ใช้ได้
`sent`	ส่งสำเร็จ
`delivered`	ส่งมอบสำเร็จ
`click`	ผู้ใช้คลิก
`target_invalid`	เป้าหมายไม่ใช้ได้
`sent_failed`	ส่งล้มเหลว
`delivered_failed`	ส่งมอบล้มเหลว

ขั้นตอนการสูญเสีย

เป้าหมายที่วางแผน → เป้าหมายที่ใช้ได้
เป้าหมายที่ใช้ได้ → ส่ง
ส่ง → ส่งมอบ
ส่งมอบ → คลิก

หมายเหตุ:

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

การเรียกกลับ API

API คอลแบ็ค

ภาพรวม

ที่อยู่คอลแบ็ค

การตรวจสอบความถูกต้องของที่อยู่คอลแบ็ค

กลไกการรักษาความปลอดภัย

กลไกการตอบกลับ

คำอธิบายฟิลด์คอลแบ็ค

เนื้อหาข้อความ

ฟิลด์ในอาร์เรย์ rows

ฟิลด์ในอ็อบเจ็กต์ status

คำอธิบายฟิลด์ Callback

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

คำอธิบายเนื้อหาคอลแบ็ค

ตัวอย่าง

ส่วนหัวคำขอ

เนื้อหาคำขอ

คำอธิบายพารามิเตอร์

ขั้นตอนการสูญเสีย

ฟิลด์ในอาร์เรย์ `rows`

ฟิลด์ในอ็อบเจ็กต์ `status`