Endpoint Callback Status Siklus Hidup

Dokumen ini menjelaskan struktur data dan keterangan field endpoint callback status siklus hidup pesan. Sistem akan melakukan callback informasi status ke URL yang dikonfigurasi pelanggan melalui HTTP POST ketika status pesan berubah.

Cara callback

• Metode request: POST
• Content-Type: application/json
• Respons sukses: status code HTTP 200 atau 204
• Percobaan ulang saat gagal: Jika pelanggan tidak mengembalikan status code sukses, sistem akan otomatis melakukan percobaan ulang

Struktur data

1. Struktur lapisan luar (ReportLifecycles)

              
              {
  "total": 1,
  "rows": [
    {
      // Array objek ReportLifecycle
    }
  ]
}

            

2. Objek ReportLifecycle

Struktur setiap elemen dalam array rows adalah sebagai berikut:

3. Objek Status

Objek informasi detail status:

Catatan: Field berikut digunakan untuk statistik internal dan tidak akan dikirim melalui callback ke pelanggan:

• analysis - field analisis statistik internal

4. Objek StatusData

Data dasar terkait status:

Catatan: Field berikut merupakan informasi sensitif atau field internal, telah difilter dan tidak akan dikirim melalui callback ke pelanggan:

• message_content - konten pesan (informasi sensitif)
• parts - jumlah segmen pesan (field internal)
• msg_type - tipe pesan (field internal)
• protocol_type - tipe protokol (field internal)
• supplier_ids - ID pemasok (informasi sensitif)

5. Objek Billing

Informasi penagihan (hanya dikembalikan jika ada data penagihan):

Catatan: Field berikut merupakan field penagihan internal dan tidak akan dikirim melalui callback ke pelanggan:

• cost10000 - field penagihan internal (satuan sepersepuluh ribu)
• sender_cost10000 - biaya pengirim (satuan sepersepuluh ribu)

6. Objek ErrorDetail

Detail error (hanya dikembalikan saat terjadi error):

7. Objek KwaiExtra

Informasi ekstensi khusus pelanggan Kuaishou (hanya dikembalikan pada status terkirim dan untuk pelanggan Kuaishou):

Penjelasan status pesan

Nilai status pesan yang umum:

Contoh callback

Contoh 1: pesan berhasil terkirim

              
              {
  "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
      }
    }
  ]
}

            

Contoh 2: pengiriman pesan gagal

              
              {
  "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"
        }
      }
    }
  ]
}

            

Contoh 3: penerimaan pesan gagal (dengan informasi penagihan)

              
              {
  "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"
        }
      }
    }
  ]
}

            

Contoh 4: penerimaan pesan voice pelanggan Kuaishou

              
              {
  "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
        }
      }
    }
  ]
}

            

Hal yang perlu diperhatikan

1. Aturan pengembalian field

   • Semua field yang ditandai omitempty tidak akan muncul dalam JSON yang dikembalikan jika nilainya kosong atau bernilai nol
   • Informasi sensitif dan field internal telah difilter atau dikosongkan sebelum callback

2. Keamanan

   • Konten pesan (message_content) tidak akan dikirim melalui callback ke pelanggan
   • Informasi sensitif seperti ID pemasok (supplier_ids) telah difilter
   • Field penagihan internal (cost10000, sender_cost10000) tidak akan dikirim melalui callback

3. Persyaratan penerimaan

   • Endpoint callback pelanggan harus mengembalikan respons dalam 5 detik
   • Harus mengembalikan status code HTTP 200 atau 204 untuk menandakan penerimaan berhasil
   • Jika mengembalikan status code lain atau timeout, sistem akan melakukan percobaan ulang otomatis

4. Mekanisme percobaan ulang

   • Setelah callback gagal akan dilakukan percobaan ulang otomatis
   • Interval percobaan ulang meningkat secara bertahap
   • Selama percobaan ulang data disimpan di Redis

5. Penjelasan timestamp

   • itime: timestamp terjadinya callback, dalam satuan detik
   • msg_time: timestamp pembuatan pesan, dalam satuan detik
   • delivered_time: field khusus Kuaishou, timestamp penerimaan, dalam satuan milidetik

6. Parameter kustom

   • Field custom_args akan mengembalikan apa adanya parameter kustom yang diteruskan saat pengiriman pesan
   • Jika tidak ada parameter kustom yang diteruskan saat pengiriman, field ini tidak akan muncul dalam data callback

Referensi kode error

Penjelasan kode error yang umum (untuk kode error spesifik silakan lihat dokumen kode error):

Penjelasan kode error yang lebih detail silakan lihat dokumen kode error terpisah.

Catatan perubahan

• 2024-01: Versi awal
• Menambahkan field kwai_extra untuk mendukung pelanggan Kuaishou
• Memfilter field informasi sensitif, meningkatkan keamanan