IngiaAnza kipindi cha majaribio bila malipo
Meta Tech Provider

Hali za webhook za WhatsApp: sent, delivered, read na failed

Webhook za hali hueleza kilichotokea kwa ujumbe ambao biashara ilituma kupitia WhatsApp Cloud API. Zinafika kwenye uwanja wa messages zikiwa na statuses array badala ya messages array: sent (alama moja ya kukagua), delivered (alama mbili), read (alama mbili za bluu), played kwa ujumbe wa sauti, na failed zenye errors array. Linganisha statuses[].id na wamid uliorudishwa na ombi lako la kutuma.

easyCoexistence inaunganisha nambari ya programu ya WhatsApp Business unayotumia tayari na Cloud API ya Meta kupitia Coexistence.

5

Thamani za hali ambazo Meta hutuma: sent, delivered, read, played (mara ya kwanza ujumbe wa sauti unapochezwa) na failed.

3

Webhook tofauti za hali ambazo ujumbe mmoja unaotoka unaweza kuzalisha: sent, delivered na read.

v24.0

Kuanzia toleo hili la Graph API, kitu cha conversation kinaachwa, isipokuwa kwa jumbe zilizo ndani ya dirisha la kuingia bila malipo.

0

Hakuna API za kuchota data ya webhook ya zamani; Meta inakuomba kunasa na kuhifadhi payload kadri zinavyofika.

messages

Header ya X-EC-Event kwenye hali iliyopelekwa mbele: hali husafiri ndani ya matukio ya messages, chini ya value.statuses.

Webhook za hali za WhatsApp zinafika wapi?

Kwenye uwanja uleule wa messages unaobeba kile wateja wanachotuma, katika muundo uleule wa entry na changes. Tofauti iko ndani ya value: ujumbe unaoingia una array ya messages, hali ina array ya statuses. Kishughulikiaji kinachosoma value.messages pekee kitapoteza kila hali bila hitilafu yoyote. metadata.phone_number_id inaonyesha ni nambari yako ipi iliyotuma ujumbe, na array ya contacts yenye jina la wasifu wa mteja, wa_id na BSUID inakuja pamoja nayo, isipokuwa kwenye hali za failed na hali ya sent ya ujumbe wa kikundi. Hiki ni mfano wa Meta wa kiolezo cha ujumbe wa masoko kilichotoka kwenye seva za Meta:

Meta's example: a marketing message with status sent
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo M."
                },
                "wa_id": "16505551234",
                "user_id": "US.13491208655302741918"
              }
            ],
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
                "status": "sent",
                "timestamp": "1750030073",
                "recipient_id": "16505551234",
                "recipient_user_id": "US.13491208655302741918",
                "conversation": {
                  "id": "72b14d6bd5407799e66f64d1b338e567",
                  "expiration_timestamp": "1750116480",
                  "origin": {
                    "type": "marketing"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "PMP",
                  "type": "regular",
                  "category": "marketing"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Kila thamani ya hali inamaanisha nini?

Kila thamani inalingana na alama ambayo mteja angeiona kwenye WhatsApp. Hali ya read inahesabiwa tu baada ya ujumbe kufika (delivered). Mteja anapopokea ujumbe wakati mazungumzo tayari yamefunguliwa, Meta hutuma read bila webhook ya delivered kwanza, kama uboreshaji wa ndani. Kwa hiyo kifuatiliaji kinapaswa kukubali read hata kama delivered haikuja kamwe, na kupanga hali kwa kiwango cha hali iliyofikiwa badala ya kutarajia kila moja kwa mpangilio maalum.

sentLeft Meta's servers. One gray check in WhatsApp.
deliveredReached the customer's device. Two gray checks.
readDisplayed in an open chat on the device. Two blue checks.
playedFirst play of voice messages. Blue microphone.
failedCould not be sent or delivered. Red error triangle, plus an errors array.

Kitu cha hali kina sehemu zipi?

Ni chache kuliko ujumbe, na kadhaa zina masharti. Mwongozo wa kumbukumbu wa Meta unaorodhesha wakati kila moja inapokuwepo:

  • id: wamid ya ujumbe uliotuma, ufunguo wa kulinganisha.
  • status na timestamp: thamani na muda wa Unix webhook ilipoanzishwa, kama string.
  • recipient_id: nambari ya simu au kitambulisho cha kikundi, huachwa unapotuma kwa BSUID na nambari haipatikani.
  • recipient_user_id: BSUID ya mteja, huachwa kwenye hali ya failed unapotuma kwa nambari ya simu.
  • recipient_type na recipient_participant_id: kwa ujumbe uliotumwa kwa kikundi pekee.
  • biz_opaque_callback_data: kwa kesi ukiiweka kwenye ombi la kutuma pekee.
  • pricing: kwenye sent na mojawapo ya delivered au read pekee. errors: kwenye failed pekee.

Unalinganishaje hali na ujumbe uliotuma?

Kwa wamid. Ombi la kutuma hujibu kwa messages[0].id, na kila hali ya ujumbe huo hubeba thamani ileile kwenye statuses[].id. Ihifadhi karibu na rekodi yako mwenyewe unapotuma, kisha isasishe rekodi hali zinapofika, ukiweka hali ya juu zaidi iliyofikiwa, ili delivered iliyochelewa isifute read. Hali ambayo wamid yake haijulikani kwako ilitumwa na kitu kingine kwenye nambari hiyo, kama automation, na inaweza kupuuzwa au kuandikwa kwenye kumbukumbu.

statuses.mjs: apply status webhooks to your sends (Node.js)
// statuses.mjs: apply Meta status webhooks to the messages your system sent
const RANK = { sent: 1, delivered: 2, read: 3, played: 4 };

// value: change.value of a "messages" webhook; sends: Map of wamid -> your record
export function applyStatuses(value, sends) {
  for (const s of value.statuses ?? []) {
    const rec = sends.get(s.id); // the wamid your send request returned
    if (!rec) continue; // sent by something else, such as an automation
    if (s.status === "failed") {
      rec.status = "failed";
      rec.error = s.errors?.[0]?.code; // for example 131049, 131050 or 131026
    } else if ((RANK[s.status] ?? 0) > (RANK[rec.status] ?? 0)) {
      rec.status = s.status; // read arriving before delivered is fine; never step back
    }
    rec.updatedAt = Math.max(rec.updatedAt ?? 0, Number(s.timestamp));
  }
}

Ni nini kinachobadilika kwenye nambari ya Coexistence?

Hali zinaeleza kinachotumwa kupitia API: majibu kutoka kwenye automations zako, ujumbe ambao AI yako ilituma kupitia MCP connector, na chochote ambacho msimbo wako mwenyewe ulituma. Kile ambacho mmiliki anaandika kwenye programu ya WhatsApp Business hufika kwa programu kwa njia tofauti, kama smb_message_echoes, ambayo Meta inaiandika kama kioo cha ujumbe uliotumwa kwenye programu. Ujumbe uliohamishwa kupitia uingizaji wa historia wa mara moja hubeba hali yao ndani ya webhook ya historia, zenye thamani kama delivered, read, played, pending na error.

Hali huenda kokote ambapo sehemu ya messages ya nambari inaenda. Kwa destination ya moja kwa moja, Meta huzituma moja kwa moja kwenye endpoint yako, kwa sababu messages ni sehemu ambayo Meta inaruhusu destination kuibadilisha. Ukiwasha automations na kuweka Forward URL, hali hufika kwenye URL hiyo kama matukio ya messages.

AI yako au automation inajuaje kama ujumbe ulifikishwa?

Kupitia destination yako, si kupitia utumaji wenyewe. Msaidizi wa AI anapoita send_template au send_message, matokeo ya zana hubeba wamid na kusema Meta imekubali ujumbe; uwasilishaji unathibitishwa baadaye, kwenye kifaa cha mteja, na kuripotiwa kama hali. easyCoexistence haihifadhi historia ya hali ambayo unaweza kuuliza, na hakuna zana ya MCP inayosoma hali, kwa hiyo wakala anayehitaji uthibitisho wa uwasilishaji anapaswa kutuma kupitia mfumo wako au kusoma hali ambazo Forward URL yako inapokea.

Vivyo hivyo kwa automations: run kwenye kichupo cha Runs huonyesha hatua ya kujibu imekamilika Meta ikishakubali ujumbe, na hitilafu inayoripotiwa baadaye huonekana tu kama hali ya failed kwenye destination yako.

Makosa ya kawaida

  • Kutafuta uwanja tofauti wa statuses. Hali zinakuja kwenye messages, kwa hiyo kishughulikiaji kinachosoma value.messages pekee kinazipoteza bila hitilafu yoyote.
  • Kudai delivered kabla ya read. Meta huruka webhook ya delivered ujumbe ukisomwa papo hapo unapofika.
  • Kuchukulia jibu la utumaji kuwa ni uwasilishaji. Wamid inamaanisha Meta imekubali ombi; hitilafu inaweza kufuata dakika chache baadaye kama hali ya failed.
  • Kuwatambua wateja kwa recipient_id pekee. Huachwa unapotuma kwa BSUID na nambari ya simu haipatikani; recipient_user_id hubeba BSUID.
Kufanya hili ukitumia EasyCoexistence

Hali za kile automations zako, AI yako au msimbo wako unachotuma hufika kwenye seva yako: moja kwa moja kutoka Meta katika hali ya moja kwa moja, au kupelekwa kwenye Forward URL yako na kusainiwa kwa X-EC-Signature ukiwasha automations, na hazihifadhiwi kwa chaguo-msingi. Kuanzia US$ 9 hadi US$ 0.75 kwa kila nambari iliyounganishwa kwa mwezi, kadri unavyoongeza nambari, pamoja na siku 3 za kwanza bila malipo.

Maswali yanayoulizwa mara kwa mara

Je, webhook za hali zinajumuisha maandishi ya ujumbe?

Hapana. Hali inabeba wamid, hali yenyewe, mpokeaji, nyakati, na inapohusika, bei na hitilafu. Weka nakala yako ya kile ulichotuma, ukiipanga kwa wamid, ikiwa unahitaji kuionyesha karibu na hali yake.

Je, naweza kuchota hali za zamani kutoka Meta baadaye?

Hapana. Mwongozo wa webhook wa Meta unasema hakuna API za kuchota data ya webhook ya kihistoria, kwa hiyo hali ambayo endpoint yako haikunasa haipatikani tena mara Meta inapoacha kujaribu tena, ambayo ni hadi siku 7 baadaye.

biz_opaque_callback_data ni ya nini?

Ni thamani ya maandishi unayoweka unapotuma, kama nambari yako ya agizo au tiketi. Meta inairudisha kwenye statuses za ujumbe huo, kwa hiyo unaweza kulinganisha hali na rekodi yako bila kutafuta wamid kwanza.

Je, lazima nijibu webhook za hali kwa 200?

Ndiyo, kama webhook yoyote ya POST. Meta inachukulia jibu lolote lingine kama uwasilishaji ulioshindwa na kujaribu tena, na hiyo ndiyo mojawapo ya njia ambazo hali hiyo hiyo hukufikia mara mbili.

Endelea kusoma

Uko tayari kuanza?

Sanidi WhatsApp Coexistence kwa dakika chache, si miezi. Programu inaendelea kufanya kazi kwenye simu.

Anza kipindi cha majaribio bila malipo

Imethibitishwa kwenye