Terima tanda terima pesan untuk pesan MT dengan menentukan URL HTTP - Chat App Message Service

Ikhtisar

ChatAppStatus adalah webhook callback yang mengirimkan pembaruan status secara real-time untuk pesan Mobile Terminated (MT) yang dikirim melalui Chat App Message Service. Saat Anda mengirim pesan ke penerima, layanan ini melacak perkembangannya dan mengirimkan laporan status ke URL callback yang telah Anda konfigurasi melalui HTTP POST.

Setiap laporan status memberi tahu apakah pesan telah dikirim, diterima, dibaca, atau gagal. Anda dapat menggunakan tanda terima pengiriman ini untuk memantau pengiriman pesan, mendeteksi kegagalan, serta memicu aksi lanjutan di aplikasi Anda.

Parameter	Description
Protocol	HTTP + JSON
Encoding	UTF-8

Message status lifecycle

Pesan melewati status berikut:

Sent --> Delivered --> Read
 |
 +--> Failed (terminal)

Sent: Pesan telah dikirim.
Delivered: Pesan telah diterima oleh perangkat penerima.
Read: Pesan telah dibaca oleh penerima.
Failed: Pengiriman pesan gagal. Saat status ini dilaporkan, ErrorCode dan ErrorDescription memberikan detail kegagalan.
Deleted: Pesan telah dihapus.

Status Deleted tidak tersedia. WhatsApp tidak mendorong status ini ke Chat App Message Service.

Prasyarat

Anda telah mendaftarkan Akun Alibaba Cloud dan membuat Pasangan Kunci Akses. Untuk informasi lebih lanjut, lihat Create an AccessKey pair.
Anda telah meninjau overview and configuration of message receipts dan memahami mode, jenis, serta proses konfigurasinya. Konfigurasikan tanda terima pesan sebelum menggunakan callback ini.

Request format

Layanan mengirimkan pembaruan status ke URL callback Anda sebagai permintaan HTTP POST. Setiap badan permintaan berupa array JSON yang berisi satu atau beberapa objek laporan status.

Contoh: status pesan templat

[
    {
    "Status":"Failed",
    "ErrorDescription":"131026:Receiver is incapable of receiving this message(Message Undeliverable.)",
    "MsgFrameType":"template",
    "TaskId":"202307030171*******9",
    "From":"86131*******8",
    "Timestamp":1691043638000,
    "OriginPhoneNumber":"86130*******8",
    "TemplateCode":"820561547132813184",
    "Type":"TEMPLATE",
    "Language":"id",
    "TemplateName":"wa_otp_v_0_0_3",
    "To":"86138*******8",
    "ErrorCode":"131026",
    "MessageId":"2023078469463703*******3"
    },
    {
    "Status":"Failed",
    "ErrorDescription":"131026:Receiver is incapable of receiving this message(Message Undeliverable.)",
    "MsgFrameType":"template",
    "TaskId":"202307030171*******9",
    "From":"86131*******8",
    "Timestamp":1691043638000,
    "OriginPhoneNumber":"86130*******8",
    "TemplateCode":"820561547132813184",
    "Type":"TEMPLATE",
    "Language":"id",
    "TemplateName":"wa_otp_v_0_0_3",
    "To":"86137*******8",
    "ErrorCode":"131026",
    "MessageId":"2023078469463703*******3"
    }
]

Contoh: status pesan bebas

[
    {
    "Status":"Read",
    "MsgFrameType":"message",
    "Type":"INTERACTIVE",
    "TaskId":"2023068473353098*******8",
    "From":"86131*******8",
    "To":"86138*******8",
    "Timestamp":1691132091000,
    "OriginPhoneNumber":"86131*******8",
    "MessageId":"2023038470553398*******8",
    "ConversationId":"72222201111****",
    "ConversationType": "service"
    },
    {
    "Status":"Read",
    "MsgFrameType":"message",
    "Type":"INTERACTIVE",
    "TaskId":"2023068473353098*******8",
    "From":"86131*******8",
    "To":"86138*******1",
    "Timestamp":1691132091000,
    "OriginPhoneNumber":"86131*******8",
    "MessageId":"2023038470553398*******8",
    "ConversationId":"72222201111****",
    "ConversationType": "service"
    }
]

Field reference

Required fields

Field	Type	Description
MessageId	String	Identifier unik pesan. Contoh: `"2023078469463703*******3"`
From	String	Nomor telepon pengirim. Contoh: `"86131*******8"`
To	String	Nomor telepon penerima. Contoh: `"86138*******8"`
Timestamp	Long	Unix timestamp saat pesan dikirim, dalam milidetik. Contoh: `1691043638000`
Status	String	Status pengiriman. Nilai yang valid: `Sent`, `Delivered`, `Read`, `Failed`, `Deleted`. Lihat Message status lifecycle.
StatusDescription	String	Deskripsi status.
MsgFrameType	String	Jenis pesan. Nilai yang valid: `message` (bebas), `template` (templat yang telah disetujui). Lihat MsgFrameType values.

Optional fields

Field	Type	Description
ErrorCode	String	Kode error saat pengiriman gagal. Contoh: `"131026"`
ErrorDescription	String	Deskripsi error. Contoh: `"131026:Receiver is incapable of receiving this message(Message Undeliverable.)"`. Untuk daftar lengkapnya, lihat Error codes.
ConversationType	String	Kategori percakapan. Nilai yang valid: `service`, `utility`, `marketing`, `authentication`. Lihat ConversationType values.
ConversationId	String	Identifier unik percakapan. Contoh: `"72222201111****"`
ConversationExpirationTime (deprecated)	Long	Waktu kedaluwarsa percakapan. Bidang ini sudah tidak digunakan dan tidak berpengaruh dalam model penagihan per pesan saat ini.
Type	String	Jenis konten pesan. Nilai yang valid: `image`, `video`, `document`, `audio`, `none`. Lihat Type values.
TaskId	String	Identifier task kustom. Secara default bernilai `MessageId` jika tidak ditentukan saat mengirim pesan.
OriginPhoneNumber	String	Nomor telepon asli pengirim. Contoh: `"86130*******8"`
TemplateCode	String	Kode templat pesan. Hanya ada jika `MsgFrameType` bernilai `template`. Contoh: `"820561547132813184"`
Language	String	Kode bahasa templat pesan. Hanya ada jika `MsgFrameType` bernilai `template`. Contoh: `"id"`
TemplateName	String	Nama templat pesan. Hanya ada jika `MsgFrameType` bernilai `template`. Contoh: `"wa_otp_v_0_0_3"`

MsgFrameType values

Value	Description
message	Pesan bebas. Anda hanya dapat mengirim jenis pesan ini dalam waktu 24 jam setelah pesan terakhir dari pengguna.
template	Templat pesan yang telah disetujui dari Konsol. Anda dapat mengirim jenis pesan ini kapan saja.

ConversationType values

Value	Description
service	Percakapan yang diprakarsai pengguna.
utility	Pesan transaksional.
marketing	Pesan pemasaran.
authentication	Pesan otentikasi.

Type values

Value	Description
image	Pesan gambar.
video	Pesan video.
document	Pesan dokumen.
audio	Pesan audio.
none	Pesan teks biasa.

Response format

Untuk mengonfirmasi penerimaan callback, titik akhir Anda harus mengembalikan kode status HTTP 200 dalam waktu 3 detik. Badan respons harus berupa objek JSON dengan format berikut. Jika respons tidak ada, rusak, atau tidak dikembalikan dalam waktu 3 detik, sistem menganggap pengiriman gagal dan mencoba ulang.

{
  "code" : 0,
  "msg" : "Success"
}

Field	Type	Required	Description
code	Number	Yes	Kode respons. Kembalikan `0` untuk menunjukkan keberhasilan.
msg	String	No	Pesan deskriptif.

Retry policy

Jika upaya pengiriman awal gagal, layanan akan mencoba ulang sesuai jadwal berikut:

Attempt	Timing
1st attempt	Immediate (initial delivery)
2nd attempt	1 minute after the first attempt
3rd attempt	5 minutes after the second attempt

Upaya pengiriman dianggap gagal jika titik akhir Anda mengembalikan kode status HTTP selain 200 atau jika permintaan mengalami timeout. Setelah tiga kali upaya gagal, layanan berhenti mencoba ulang untuk callback tersebut.