Callback API

ภาพรวม

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

ที่อยู่สำหรับเรียกกลับ

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

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

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

เนื้อหาคำขอ:

{ "echostr": "12345678" }

              
              {
    "echostr": "12345678"
}

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

เนื้อหาการตอบกลับ:

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	จำเป็น	ชื่อบริการข้อความ ค่าที่เป็นไปได้: `WebPush`
`channel`	string	จำเป็น	ช่องทางข้อความ ค่าที่เป็นไปได้: `EngageLab`, `Chrome`, `Firefox`, `Safari`, `Edge`, `Opera`, `Other`
`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`, `7: In-App Message`
`platform`	string	จำเป็น	แพลตฟอร์มการส่ง push ค่าที่เป็นไปได้: `b: Web`
`uid`	int	จำเป็น	UID ของผู้รับข้อความ push
`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`, `Chrome`, `Firefox`, `Safari`, `Edge`, `Opera`, `Other`
`loss_step`	int	ไม่จำเป็น	ขั้นตอนการสูญเสีย ค่าที่เป็นไปได้: `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`	จัดส่งสำเร็จ	จัดส่งตามการเรียกกลับจริง
`click`	ผู้ใช้คลิก	ผู้ใช้คลิกตามที่รายงานโดย SDK
`target_invalid`	เป้าหมายไม่ถูกต้อง	ถือว่าไม่ถูกต้องตามขั้นตอนการสูญเสียที่ 1
`sent_failed`	ส่งไม่สำเร็จ	ถือว่าไม่ถูกต้องตามขั้นตอนการสูญเสียที่ 2
`delivered_failed`	จัดส่งไม่สำเร็จ	ถือว่าล้มเหลวตามขั้นตอนการสูญเสียที่ 3
`no_click`	คลิกไม่สำเร็จ	ถือว่าล้มเหลวตามขั้นตอนการสูญเสียที่ 4 ใช้เฉพาะข้อความในแอป

เนื้อหาการเรียกกลับ

วิธีการเรียกกลับ: POST
Content-Type: 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", // รหัสข้อความฝั่ง Engagelab "from": "", // ผู้ส่ง "to": "", // ผู้รับ, registrationID "server": "WebPush", "channel": "Chrome", "custom_args": {}, // พารามิเตอร์ที่ส่งเมื่อสร้างข้อความนี้ "itime": 1640707579, // เช่น เวลาที่ส่งข้อความ "status": { // ฟิลด์ที่ส่งกลับเมื่อสำเร็จ "message_status": "delivered", // สถานะข้อความ "status_data": { // ข้อมูลที่กำหนดเอง "channel_message_id": "wamid.123321abcdefed==", // ไม่จำเป็น, รหัสข้อความของช่องทางบุคคลที่สาม "ntf_msg": 1, // ประเภทข้อความ "platform": "a", // แพลตฟอร์มการส่ง push "uid": 100, // รหัสผู้ใช้สำหรับการแจ้งเตือน push "app_version": "", // เวอร์ชันแอปที่รวม SDK "channel": "", // ช่องทางแอปที่รวม SDK "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", // รหัสข้อความฝั่ง Engagelab
            "from": "", // ผู้ส่ง
            "to": "", // ผู้รับ, registrationID
            "server": "WebPush",
            "channel": "Chrome",
            "custom_args": {}, // พารามิเตอร์ที่ส่งเมื่อสร้างข้อความนี้
            "itime": 1640707579, // เช่น เวลาที่ส่งข้อความ
            "status": {
                // ฟิลด์ที่ส่งกลับเมื่อสำเร็จ
                "message_status": "delivered", // สถานะข้อความ    
                "status_data": { // ข้อมูลที่กำหนดเอง
                    "channel_message_id": "wamid.123321abcdefed==", // ไม่จำเป็น, รหัสข้อความของช่องทางบุคคลที่สาม
                    "ntf_msg": 1, // ประเภทข้อความ
                    "platform": "a", // แพลตฟอร์มการส่ง push    
                    "uid": 100, // รหัสผู้ใช้สำหรับการแจ้งเตือน push    
                    "app_version": "", // เวอร์ชันแอปที่รวม SDK 
                    "channel": "", // ช่องทางแอปที่รวม SDK   
                    "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`	จัดส่งไม่สำเร็จ

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

เป้าหมายแผน → เป้าหมายที่ถูกต้อง
เป้าหมายที่ถูกต้อง → ส่ง
ส่ง → จัดส่ง
จัดส่ง → คลิก

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

Callback API

ภาพรวม

ที่อยู่สำหรับเรียกกลับ

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

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

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

คำอธิบายฟิลด์การเรียกกลับ

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

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

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

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

เนื้อหาการเรียกกลับ

ตัวอย่าง

ส่วนหัวคำขอ

เนื้อหาคำขอ

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

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

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

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