MasukMulai uji coba gratis
Meta Tech Provider

Mengapa pesan WhatsApp gagal: membaca status failed dan kesalahannya

Webhook status failed berarti Meta tidak bisa mengirim atau mengantarkan pesan yang dikirim bisnis melalui API. Webhook ini tiba di field messages dengan status failed dan array errors yang berisi code, title, message, error_data.details, dan href. Kode menunjukkan alasannya: 131047 jendela layanan pelanggan tertutup, 131026 tidak dapat dikirimkan, 131049 batas marketing, 131050 marketing dihentikan, 131042 masalah pembayaran.

easyCoexistence menghubungkan nomor aplikasi WhatsApp Business Anda ke Cloud API Meta melalui Coexistence dan meneruskan status failed ke server Anda, langsung atau sebagai forward bertanda tangan saat otomatisasi aktif.

131047

Sudah lebih dari 24 jam sejak penerima terakhir membalas; anjuran Meta adalah mengirim template sebagai gantinya.

131049

Tidak dikirimkan agar keterlibatan ekosistem tetap sehat; tunggu minimal 24 jam sebelum mengirim ulang template marketing.

131050

Penerima memilih berhenti menerima pesan marketing dari bisnis; Meta menyatakan jangan mencoba kembali.

No contacts

Status failed tidak menyertakan array contacts, jadi kaitkan kegagalan melalui statuses.id.

Delivered

Yang ditagih Meta: pesan dikenai biaya saat berhasil sampai ke penerima, bukan saat dikirim.

Seperti apa status failed?

Seperti status lainnya, ditambah errors. Array contacts tidak ada, recipient_user_id dihilangkan saat pesan dikirim ke nomor telepon, dan tidak ada objek pricing. title dan message berisi teks yang sama, error_data.details menjelaskannya dalam satu kalimat, dan href mengarah ke daftar kode kesalahan Meta. Ini contoh dari Meta sendiri, sebuah template marketing yang dihentikan oleh batas per pengguna:

Meta's example: a message that failed with 131049
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",
                "status": "failed",
                "timestamp": "1751142888",
                "recipient_id": "16505551234",
                "errors": [
                  {
                    "code": 131049,
                    "title": "This message was not delivered to maintain healthy ecosystem engagement.",
                    "message": "This message was not delivered to maintain healthy ecosystem engagement.",
                    "error_data": {
                      "details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
                    },
                    "href": "/documentation/business-messaging/whatsapp/support/error-codes"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Kode kesalahan apa yang paling sering muncul, dan artinya?

Meta mengembalikan kesalahan di respons pengiriman, di status failed, atau keduanya, jadi kode yang sama bisa sampai lewat salah satu jalur, dan handler Anda harus membaca kedua tempat. Berikut kode yang menjelaskan sebagian besar pesan yang tidak pernah sampai, dengan alasan dari Meta sendiri dan langkah pertama yang bisa dicoba. Daftar lengkapnya ada di referensi kode kesalahan Meta:

131026Undeliverable: not a WhatsApp number, terms not accepted, or an outdated WhatsApp version on the recipient's phone.
131047More than 24 hours since the customer last wrote. Send an approved template instead.
131049Held back to keep engagement healthy, usually the per-user marketing limit. Wait 24 hours or more.
131050The customer stopped marketing messages from you. Do not retry.
131042A problem with the payment method on the WhatsApp Business Account.
130472Not sent because the recipient is part of Meta's marketing message experiment.
131053Media could not be uploaded, often an unsupported file type.
131000Unknown error. Try again; if it persists, open a Direct Support ticket.

Bagaimana handler sebaiknya bereaksi pada setiap jenis kegagalan?

Kelompokkan kode ke dalam langkah berikutnya sebelum apa pun dicoba kembali. Mencoba kembali semua kode tanpa dipilah mengubah opt-out marketing menjadi kegagalan berulang dan bisa memperpanjang blokir, sementara membuang kesalahan sementara berarti kehilangan pesan yang sebenarnya akan sampai semenit kemudian.

  • Mencoba kembali dengan jeda bertahap: 131000 tidak diketahui, 131016 layanan tidak tersedia, 130429 throughput tercapai.
  • Tunggu dahulu: 131049, minimal 24 jam, karena percobaan terlalu dini bisa memblokir pengguna itu hingga 24 jam lagi.
  • Ganti jenis pesan: 131047 memerlukan template yang disetujui, karena jendela layanan pelanggan 24 jam sudah tertutup.
  • Hentikan untuk pelanggan ini: 131050, sampai event user_preferences resume diterima.
  • Perbaiki akun atau konten: 131042 pembayaran, 131031 akun dibatasi, 131053 media.

Kegagalan mana yang hanya muncul sebagai status failed?

Kegagalan yang diputuskan Meta setelah menerima permintaan. Respons pengiriman mengembalikan wamid, dan penolakannya datang belakangan lewat webhook ini. Meta tidak mengantarkan template marketing ke pengguna WhatsApp dengan nomor telepon AS (+1 dengan kode area AS). Template marketing ke pelanggan yang berhenti menerima pesan marketing tetap diproses, lalu dilaporkan gagal dengan 131050. Batas marketing per pengguna melaporkan 131049 dengan cara yang sama.

Jika nomor tidak punya tujuan webhook, kegagalan ini tidak terlihat di mana pun dan pesan tampak terkirim begitu saja. Untuk urutan pemeriksaan lengkap saat pelanggan tidak menerima apa-apa, lihat halaman tentang pesan WhatsApp API yang tidak terkirim.

Apa yang berubah pada nomor Coexistence?

Ada dua hal yang penting. Pertama, jendela 24 jam hanya berlaku untuk API. Panduan Coexistence dari Meta menyatakan bahwa pesan yang dikirim dari aplikasi WhatsApp Business tidak tunduk pada jendela layanan pelanggan. Jadi setelah 131047, pemilik tetap bisa membalas pelanggan itu dari ponsel, sementara sistem Anda mengirim template yang disetujui.

Kedua, throughput-nya tetap. Nomor yang dipakai di aplikasi dan API sekaligus hanya mengirim paling banyak 20 pesan per detik, dan melewati batas itu mengembalikan 130429. Selebihnya sama seperti nomor Cloud API mana pun: field yang sama, array errors yang sama, dan kode yang sama.

Bagaimana otomatisasi dan AI Anda melihat sebuah kegagalan?

Tergantung kapan Meta menolak. Penolakan saat pengiriman, seperti 131047, menggagalkan langkah otomatisasi. Run menampilkan Failed beserta pesan dari Meta di tab Runs, dan pemilik mendapat email agar bisa membalas pelanggan itu sendiri. Otomatisasi juga memeriksa jendela sebelum mengirim balasan teks bebas, dan melewati pengiriman dengan window_closed alih-alih mencoba.

Kegagalan yang dilaporkan Meta setelahnya tiba sebagai status failed di Forward URL atau tujuan langsung Anda, dan run tetap seperti semula. AI yang mengirim template lewat konektor MCP melihat wamid dan “sent: true”. Tanyakan status wamid itu ke sistem Anda, atau minta asisten menjalankan get_number_health saat banyak pesan gagal sekaligus.

Kesalahan umum

  • Mencoba kembali 131050 berulang kali. Pelanggan berhenti menerima pesan marketing, jadi setiap percobaan gagal dengan cara yang sama sampai mereka mengaktifkannya kembali.
  • Mengirim ulang template marketing 131049 dalam hitungan jam. Meta meminta minimal 24 jam, dan percobaan terlalu dini bisa memblokir pengguna itu hingga 24 jam lagi.
  • Hanya mencatat title. error_data.details memuat alasan spesifik, jadi simpan kode dan details bersama wamid.
  • Berjalan tanpa tujuan webhook dan menilai pengiriman dari respons pengiriman, yang hanya menyatakan bahwa Meta menerima pesan.
Melakukan ini dengan EasyCoexistence

Saat balasan otomatisasi ditolak saat pengiriman, run menampilkan kesalahan Meta dan Anda mendapat email. Setiap nomor dipantau 24/7 untuk pemutusan koneksi dan penurunan kualitas. US$ 9 turun hingga US$ 0.75 per nomor per bulan, makin turun seiring penambahan nomor, dengan 3 hari pertama gratis.

Pertanyaan yang sering diajukan

Apakah pesan yang gagal dikenai biaya oleh Meta?

Halaman harga Meta menyatakan biaya dikenakan untuk pesan yang berhasil sampai, bukan untuk pesan yang hanya dikirim. Status failed tidak membawa objek pricing. Tagihan masuk ke WhatsApp Business Account milik bisnis itu sendiri, dan easyCoexistence tidak pernah menambahkan markup.

Apakah 131026 berarti pelanggan memblokir bisnis?

Daftar Meta untuk 131026 menyebut alasan lain: nomor tidak ada di WhatsApp, penerima belum menyetujui syarat terbaru, atau versi WhatsApp mereka terlalu lawas. Meta menyarankan untuk memeriksa hal-hal itu dengan menanyakan pelanggan lewat saluran lain.

Mengapa recipient_user_id muncul pada sebagian kegagalan dan tidak pada yang lain?

Meta menghilangkannya pada status failed saat pesan dikirim ke nomor telepon. Saat Anda mengirim ke BSUID pelanggan, kegagalan menyertakannya, dan yang mungkin tidak ada adalah recipient_id.

Bisakah pesan gagal setelah sampai?

Referensi Meta menggambarkan failed sebagai kegagalan mengirim atau mengantarkan. Setelah pesan sampai ke perangkat, status berikutnya yang bisa diharapkan adalah read, atau played untuk pesan suara.

Lanjut membaca

Siap memulai?

Konfigurasikan WhatsApp Coexistence dalam hitungan menit, bukan bulan. Aplikasi tetap berfungsi di ponsel.

Mulai uji coba gratis

Diverifikasi pada