อินเทอร์เฟซการเรียกกลับสถานะวงจรชีวิต

เอกสารนี้อธิบายโครงสร้างข้อมูลและคำอธิบายฟิลด์ของอินเทอร์เฟซการเรียกกลับสถานะวงจรชีวิตของข้อความ ระบบจะเรียกกลับข้อมูลสถานะไปยัง URL ที่ลูกค้าตั้งค่าไว้ผ่านวิธี HTTP POST เมื่อสถานะข้อความมีการเปลี่ยนแปลง

วิธีการเรียกกลับ

• เมธอดคำขอ: POST
• Content-Type: application/json
• การตอบกลับสำเร็จ: สถานะ HTTP 200 หรือ 204
• การลองใหม่เมื่อล้มเหลว: หากลูกค้าไม่คืนสถานะสำเร็จ ระบบจะลองใหม่โดยอัตโนมัติ

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

1. โครงสร้างชั้นนอก (ReportLifecycles)

              
              {
  "total": 1,
  "rows": [
    {
      // ReportLifecycle 对象数组
    }
  ]
}

            

2. ออบเจ็กต์ ReportLifecycle

แต่ละสมาชิกในอาเรย์ rows มีโครงสร้างดังนี้:

3. ออบเจ็กต์ Status

ออบเจ็กต์ข้อมูลรายละเอียดสถานะ:

หมายเหตุ: ฟิลด์ต่อไปนี้ใช้สำหรับสถิติภายใน จะไม่ถูกเรียกกลับไปยังลูกค้า:

• analysis - ฟิลด์การวิเคราะห์สถิติภายใน

4. ออบเจ็กต์ StatusData

ข้อมูลพื้นฐานที่เกี่ยวข้องกับสถานะ:

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

• message_content - เนื้อหาข้อความ (ข้อมูลที่ละเอียดอ่อน)
• parts - จำนวนชิ้นส่วนข้อความ (ฟิลด์ภายใน)
• msg_type - ประเภทข้อความ (ฟิลด์ภายใน)
• protocol_type - ประเภทโปรโตคอล (ฟิลด์ภายใน)
• supplier_ids - ID ผู้ให้บริการ (ข้อมูลที่ละเอียดอ่อน)

5. ออบเจ็กต์ Billing

ข้อมูลการเรียกเก็บเงิน (คืนค่าเฉพาะเมื่อมีข้อมูลการเรียกเก็บเงิน):

หมายเหตุ: ฟิลด์ต่อไปนี้เป็นฟิลด์การเรียกเก็บเงินภายใน จะไม่ถูกเรียกกลับไปยังลูกค้า:

• cost10000 - ฟิลด์การเรียกเก็บเงินภายใน (หน่วยหนึ่งในหมื่น)
• sender_cost10000 - ต้นทุนฝั่งผู้ส่ง (หน่วยหนึ่งในหมื่น)

6. ออบเจ็กต์ ErrorDetail

รายละเอียดข้อผิดพลาด (คืนค่าเฉพาะเมื่อเกิดข้อผิดพลาด):

7. ออบเจ็กต์ KwaiExtra

ข้อมูลส่วนขยายเฉพาะสำหรับลูกค้า Kwai (คืนค่าเฉพาะเมื่ออยู่ในสถานะนำส่งและเป็นลูกค้า Kwai):

คำอธิบายสถานะข้อความ

ค่าสถานะข้อความที่พบบ่อย:

ตัวอย่างการเรียกกลับ

ตัวอย่าง 1: นำส่งข้อความสำเร็จ

              
              {
  "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": "delivered",
        "status_data": {
          "msg_time": 1701234560,
          "message_id": "123456789",
          "current_send_channel": "CHANNEL_A",
          "template_key": "verify_code",
          "business_id": "1001"
        },
        "billing": {
          "cost": 0.005,
          "currency": "USD"
        },
        "error_code": 0
      }
    }
  ]
}

            

ตัวอย่าง 2: ส่งข้อความล้มเหลว

              
              {
  "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"
        },
        "error_code": 4001,
        "error_detail": {
          "message": "Invalid phone number",
          "channel_code": "INVALID_NUMBER",
          "channel_message": "The phone number format is invalid"
        }
      }
    }
  ]
}

            

ตัวอย่าง 3: นำส่งข้อความล้มเหลว (พร้อมข้อมูลการเรียกเก็บเงิน)

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456791",
      "to": "+6598765434",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234570,
      "custom_args": {
        "campaign": "new_year_promo"
      },
      "status": {
        "message_status": "delivered_fail",
        "status_data": {
          "msg_time": 1701234562,
          "message_id": "123456791",
          "current_send_channel": "CHANNEL_C",
          "template_key": "marketing",
          "business_id": "1001"
        },
        "billing": {
          "cost": 0.0045,
          "currency": "USD"
        },
        "error_code": 5002,
        "error_detail": {
          "message": "Phone number unreachable",
          "channel_code": "UNREACHABLE",
          "channel_message": "Subscriber absent"
        }
      }
    }
  ]
}

            

ตัวอย่าง 4: นำส่งข้อความ Voice ของลูกค้า Kwai

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456792",
      "to": "+6598765435",
      "server": "voice",
      "channel": "voice",
      "itime": 1701234575,
      "status": {
        "message_status": "delivered",
        "status_data": {
          "msg_time": 1701234565,
          "message_id": "123456792",
          "current_send_channel": "VOICE_CHANNEL_A",
          "template_key": "voice_verify",
          "business_id": "2001"
        },
        "billing": {
          "cost": 0.012,
          "currency": "USD"
        },
        "error_code": 0,
        "kwai_extra": {
          "delivered_time": 1701234575000,
          "parts": 1,
          "duration": 45
        }
      }
    }
  ]
}

            

ข้อควรทราบ

1. กฎการคืนค่าฟิลด์

   • ฟิลด์ทั้งหมดที่ทำเครื่องหมายเป็น omitempty จะไม่ปรากฏใน JSON ที่คืนค่า เมื่อค่าว่างหรือเป็นค่าศูนย์
   • ข้อมูลที่ละเอียดอ่อนและฟิลด์ภายในถูกกรองหรือเคลียร์ก่อนการเรียกกลับ

2. ความปลอดภัย

   • เนื้อหาข้อความ (message_content) จะไม่ถูกเรียกกลับไปยังลูกค้า
   • ข้อมูลที่ละเอียดอ่อน เช่น ID ผู้ให้บริการ (supplier_ids) ถูกกรองออกแล้ว
   • ฟิลด์การเรียกเก็บเงินภายใน (cost10000、sender_cost10000) จะไม่ถูกเรียกกลับ

3. ข้อกำหนดการรับ

   • อินเทอร์เฟซการเรียกกลับของลูกค้าต้องตอบกลับภายใน 5 วินาที
   • ต้องคืนสถานะ HTTP 200 หรือ 204 เพื่อแสดงว่ารับสำเร็จ
   • หากคืนสถานะอื่นหรือหมดเวลา ระบบจะลองใหม่โดยอัตโนมัติ

4. กลไกการลองใหม่

   • หลังจากการเรียกกลับล้มเหลว ระบบจะลองใหม่โดยอัตโนมัติ
   • ช่วงเวลาการลองใหม่จะเพิ่มขึ้นทีละขั้น
   • ในระหว่างการลองใหม่ ข้อมูลจะถูกบันทึกไว้ใน Redis

5. คำอธิบาย timestamp

   • itime: timestamp ที่เกิดการเรียกกลับ หน่วยเป็นวินาที
   • msg_time: timestamp การสร้างข้อความ หน่วยเป็นวินาที
   • delivered_time: ฟิลด์เฉพาะของ Kwai, timestamp การนำส่ง หน่วยเป็นมิลลิวินาที

6. พารามิเตอร์ที่กำหนดเอง

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

เอกสารอ้างอิงรหัสข้อผิดพลาด

คำอธิบายรหัสข้อผิดพลาดที่พบบ่อย (สำหรับรหัสข้อผิดพลาดเฉพาะ โปรดดูเอกสารรหัสข้อผิดพลาด):

สำหรับคำอธิบายรหัสข้อผิดพลาดที่ละเอียดยิ่งขึ้น โปรดดูเอกสารรหัสข้อผิดพลาดแยกต่างหาก

บันทึกการอัปเดต

• 2024-01: เวอร์ชันแรก
• เพิ่มฟิลด์ kwai_extra เพื่อรองรับลูกค้า Kwai
• กรองฟิลด์ข้อมูลที่ละเอียดอ่อน เพิ่มความปลอดภัย