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

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

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

• วิธีการร้องขอ: 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 - รหัสผู้ให้บริการ (ข้อมูลที่ละเอียดอ่อน)

5. วัตถุ Billing

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

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

• cost10000 - ฟิลด์การเรียกเก็บเงินภายใน (หน่วย: หนึ่งในหมื่น)
• sender_cost10000 - ค่าใช้จ่ายผู้ส่ง (หน่วย: หนึ่งในหมื่น)

6. วัตถุ ErrorDetail

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

7. วัตถุ KwaiExtra

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

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

ค่าของสถานะข้อความทั่วไป:

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

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

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456789",
      "to": "+8613800138000",
      "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": "+8613800138001",
      "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": "+8613800138002",
      "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: ข้อความเสียงของลูกค้า Kwai ส่งสำเร็จ

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456792",
      "to": "+8613800138003",
      "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) จะไม่รวมอยู่ในการเรียกกลับไปยังลูกค้า
   • ข้อมูลที่ละเอียดอ่อน เช่น รหัสผู้ให้บริการ (supplier_ids) ถูกกรองออกไป
   • ฟิลด์การเรียกเก็บเงินภายใน (cost10000, sender_cost10000) จะไม่รวมอยู่

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

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

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

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

5. คำอธิบายเวลา

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

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

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

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

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

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

บันทึกการเปลี่ยนแปลง

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