Log masukMulakan percubaan percuma
Meta Tech Provider

Mengapa mesej WhatsApp gagal: membaca status gagal dan ralatnya

Webhook status gagal bermakna Meta tidak dapat menghantar atau menyampaikan mesej yang dihantar oleh perniagaan melalui API. Ia tiba pada medan messages dengan status failed dan array errors yang memuat code, title, message, error_data.details dan href. Kod itu memberi sebabnya: 131047 tetingkap khidmat pelanggan tertutup, 131026 tidak boleh dihantar, 131049 had pemasaran, 131050 pemasaran dihentikan, 131042 masalah bayaran.

easyCoexistence menyambungkan nombor aplikasi WhatsApp Business anda kepada Cloud API Meta melalui Coexistence dan menghantar status gagal ke pelayan anda, sama ada secara terus atau sebagai penghantaran ke hadapan yang ditandatangani apabila automasi dihidupkan.

131047

Lebih 24 jam telah berlalu sejak penerima kali terakhir membalas; cara penyelesaian Meta ialah menghantar template sebagai gantinya.

131049

Tidak dihantar bagi memelihara penglibatan ekosistem yang sihat; tunggu sekurang-kurangnya 24 jam sebelum menghantar semula template pemasaran.

131050

Penerima memilih untuk berhenti menerima mesej pemasaran daripada perniagaan; Meta menyatakan supaya tidak cuba semula.

No contacts

Status gagal tidak mengandungi array contacts, jadi padankan kegagalan melalui statuses.id.

Delivered

Meta mengenakan bayaran bagi mesej yang disampaikan, bukan mesej yang hanya dihantar.

Bagaimana rupa status gagal?

Sama seperti mana-mana status, tetapi dengan errors tambahan. Array contacts tiada, recipient_user_id ditinggalkan apabila mesej dihantar ke nombor telefon, dan tiada objek pricing. title dan message membawa teks yang sama, error_data.details menerangkannya dalam satu ayat, dan href menunjuk ke senarai kod ralat Meta. Ini contoh Meta sendiri, template pemasaran yang dihentikan oleh had setiap 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"
        }
      ]
    }
  ]
}

Kod ralat mana yang paling kerap muncul, dan apa maksudnya?

Meta memulangkan ralat dalam respons penghantaran, dalam status gagal, atau dalam kedua-duanya, jadi kod yang sama boleh sampai melalui mana-mana cara, dan pengendali anda perlu membaca kedua-dua tempat. Ini kod yang menerangkan kebanyakan mesej yang tidak sampai, dengan sebab Meta sendiri dan langkah pertama untuk dicuba; senarai penuh terdapat dalam rujukan kod ralat 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 pengendali patut bertindak balas kepada setiap jenis kegagalan?

Kelaskan kod kepada tindakan seterusnya sebelum apa-apa cubaan semula. Cubaan semula secara pukal menukar penarikan diri pemasaran kepada kegagalan berulang dan boleh memanjangkan sekatan, manakala membuang ralat sementara bermakna kehilangan mesej yang sepatutnya berjaya sejurus kemudian.

  • Cuba semula dengan backoff: 131000 tidak diketahui, 131016 perkhidmatan tidak tersedia, 130429 throughput dicapai.
  • Tunggu dahulu: 131049, sekurang-kurangnya 24 jam, kerana cubaan awal boleh menyekat pengguna itu sehingga 24 jam lagi.
  • Tukar mesej: 131047 memerlukan template yang diluluskan, kerana tetingkap 24 jam sudah tertutup.
  • Berhenti untuk pelanggan ini: 131050, sehingga ketibaan user_preferences resume.
  • Betulkan akaun atau kandungan: 131042 bayaran, 131031 akaun disekat, 131053 media.

Kegagalan mana yang hanya muncul sebagai status gagal?

Yang diputuskan Meta selepas ia menerima permintaan. Penghantaran mengembalikan wamid, dan penolakan datang kemudian melalui webhook ini. Meta tidak menghantar template pemasaran kepada pengguna WhatsApp yang menggunakan nombor telefon Amerika Syarikat (+1 dengan kod kawasan AS). Template pemasaran kepada pelanggan yang berhenti menerima mesej pemasaran diproses, kemudian dilaporkan gagal dengan 131050, dan had pemasaran setiap pengguna melaporkan 131049 dengan cara yang sama.

Jika nombor itu tiada destinasi webhook, kegagalan ini tidak kelihatan di mana-mana dan mesej hanya kelihatan telah dihantar. Untuk susunan lengkap semakan apabila pelanggan tidak menerima apa-apa, lihat halaman tentang mesej WhatsApp API yang tidak dihantar.

Apa yang berubah pada nombor Coexistence?

Dua perkara penting. Pertama, tetingkap 24 jam hanya mengikat API. Panduan Coexistence Meta menyatakan mesej yang dihantar dari aplikasi WhatsApp Business tidak tertakluk kepada tetingkap khidmat pelanggan, jadi selepas 131047 pemilik masih boleh membalas pelanggan itu dari telefon, manakala sistem anda menghantar template yang diluluskan.

Kedua, throughput ditetapkan. Nombor yang digunakan serentak dalam aplikasi dan API menghantar paling banyak 20 mesej sesaat, dan melebihi had itu memulangkan 130429. Segala-galanya lain sama seperti nombor Cloud API lain: medan sama, array errors sama, kod sama.

Bagaimana automasi dan AI anda melihat kegagalan?

Ia bergantung pada bila Meta menolak. Penolakan semasa penghantaran, seperti 131047, menggagalkan langkah automasi: larian menunjukkan Failed dengan mesej Meta dalam tab Runs, dan pemilik menerima e-mel supaya mereka boleh menjawab pelanggan itu sendiri. Automasi juga menyemak tetingkap sebelum menghantar balasan teks bebas dan melangkau dengan window_closed, bukan mencuba.

Kegagalan yang Meta laporkan kemudian tiba sebagai status gagal di URL Forward atau destinasi terus anda, dan larian kekal seperti asalnya. AI yang menghantar template melalui penyambung MCP melihat wamid dan "sent: true"; minta sistem anda untuk status wamid itu, atau minta pembantu menjalankan get_number_health apabila banyak mesej gagal serentak.

Kesilapan biasa

  • Mencuba semula 131050 dalam gelung. Pelanggan telah berhenti menerima mesej pemasaran, jadi setiap cubaan gagal dengan cara yang sama sehingga mereka menyambung semula.
  • Menghantar semula template pemasaran 131049 dalam masa beberapa jam. Meta meminta sekurang-kurangnya 24 jam, dan cubaan awal boleh menyekat pengguna itu sehingga 24 jam lagi.
  • Hanya merekod title. error_data.details membawa sebab khusus, jadi simpan code dan details bersama wamid.
  • Beroperasi tanpa destinasi webhook dan menilai penghantaran daripada respons penghantaran, yang hanya menyatakan Meta telah menerima mesej.
Menggunakan EasyCoexistence untuk ini

Apabila balasan automasi ditolak semasa penghantaran, larian menunjukkan ralat Meta dan anda menerima e-mel, dan setiap nombor dipantau 24/7 untuk pemutusan dan penurunan kualiti. Daripada US$ 9 hingga US$ 0.75 setiap nombor sebulan, menurun apabila nombor ditambah, dengan 3 hari pertama percuma.

Soalan lazim

Adakah mesej yang gagal dikenakan bayaran oleh Meta?

Halaman harga Meta menyatakan ia mengenakan bayaran bagi mesej yang disampaikan, bukan mesej yang sekadar dihantar. Status gagal tidak membawa objek pricing. Caj dikenakan kepada WhatsApp Business Account milik perniagaan sendiri; easyCoexistence tidak sekali-kali menambah markup.

Adakah 131026 bermakna pelanggan menyekat perniagaan?

Senarai Meta bagi 131026 menyebut sebab lain: nombor itu tiada di WhatsApp, penerima belum menerima syarat terbaru, atau versi WhatsApp mereka terlalu lama. Meta mencadangkan supaya pelanggan diminta menyemak perkara itu melalui saluran lain.

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

Meta tidak menyertakannya pada status gagal apabila mesej dihantar ke nombor telefon. Apabila anda menghantar ke BSUID pelanggan, kegagalan itu menyertakannya, dan recipient_id mungkin pula yang tiada.

Bolehkah mesej gagal selepas ia telah disampaikan?

Rujukan Meta menerangkan failed sebagai kegagalan untuk menghantar atau menyampaikan. Apabila mesej sudah sampai ke peranti, status seterusnya yang boleh dijangka ialah read, atau played bagi mesej suara.

Teruskan membaca

Sedia untuk bermula?

Sediakan WhatsApp Coexistence dalam beberapa minit, bukan berbulan-bulan. Aplikasi terus berfungsi pada telefon.

Mulakan Percubaan Percuma

Disahkan pada