Kirjaudu sisäänAloita ilmainen kokeilu
Meta Tech Provider

WhatsApp-webhookien tilat: lähetetty, toimitettu, luettu ja epäonnistunut

Tila-webhookit kertovat, mitä WhatsApp Cloud API:n kautta lähetetylle viestille tapahtui. Ne saapuvat messages-kenttään statuses-taulukon kanssa messages-taulukon sijaan: sent (yksi valintamerkki), delivered (kaksi valintamerkkiä), read (kaksi sinistä valintamerkkiä), played ääniviesteille ja failed errors-taulukon kanssa. Sovita statuses[].id lähetyspyyntösi palauttamaan wamid-tunnisteeseen.

easyCoexistence yhdistää jo käyttämäsi WhatsApp Business -sovelluksen numeron Metan Cloud API:in Coexistence-yhteyden kautta.

5

Metan lähettämät tilat: sent, delivered, read, played (ääniviestien ensimmäinen toisto) ja failed.

3

Erilliset tilawebhookit, jotka yksi lähtevä viesti voi tuottaa: sent, delivered ja read.

v24.0

Tästä Graph API -versiosta lähtien keskusteluobjekti jätetään pois, paitsi viesteille ilmaisen sisäänkäyntipisteen ajanjaksolla.

0

Menneen webhook-datan hakemiseen ei ole API-rajapintoja; Meta pyytää tallentamaan payloadit heti, kun ne saapuvat.

messages

Välitetyn tilan X-EC-Event-otsake: statuses kulkee messages-tapahtumien sisällä, kentän value.statuses alla.

Mistä WhatsApp-tilawebhookit saapuvat?

Samaan messages-kenttään, joka kuljettaa asiakkaiden lähettämät viestit, samassa objektissa, entry- ja changes-rakenteessa. Ero on value-objektin sisällä: saapuvalla viestillä on messages-taulukko, tilalla statuses-taulukko. Käsittelijä, joka lukee vain value.messages-kenttää, pudottaa kaikki tilat virheilmoitusta antamatta. metadata.phone_number_id kertoo, mikä numerosi lähetti viestin, ja mukana tulee contacts-taulukko asiakkaan profiilinimen, wa_id:n ja BSUID:n kanssa. Poikkeuksena ovat epäonnistuneet tilat ja ryhmäviestien sent-tila. Tämä on Metan esimerkki markkinoinnin viestipohjasta, joka lähti Metan palvelimilta:

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

Mitä kukin tilan arvo tarkoittaa?

Jokainen arvo vastaa merkkiä, jonka asiakas näkee WhatsAppissa. Tila lasketaan luetuksi vasta, kun viesti on toimitettu. Kun asiakas saa viestin jo avoimen keskustelun aikana, Meta lähettää read-tilan ilman delivered-webhookia ensin sisäisenä optimointina. Seurannan pitää siksi hyväksyä read, vaikka delivered jäisi tulematta, ja järjestää tilat paremmuusjärjestykseen sen sijaan, että odottaisi niitä yksi kerrallaan kiinteässä järjestyksessä.

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.

Mitä kenttiä tilaobjekti sisältää?

Vähemmän kuin viesti, ja useat kentät ovat ehdollisia. Metan viitteessä kerrotaan, milloin kukin on mukana:

  • id: lähettämäsi viestin wamid, jonka mukaan sovitetaan.
  • status ja timestamp: arvo ja webhookin laukaisuhetki Unix-aikana merkkijonona.
  • recipient_id: puhelinnumero tai ryhmän tunnus; puuttuu, kun lähetit BSUID:lle eikä numero ole saatavilla.
  • recipient_user_id: asiakkaan BSUID; puuttuu epäonnistuneesta tilasta, kun lähetit puhelinnumerolle.
  • recipient_type ja recipient_participant_id: vain ryhmään lähetetyille viesteille.
  • biz_opaque_callback_data: vain, jos asetit sen lähetyspyyntöön.
  • pricing: vain sent-tilassa ja joko delivered- tai read-tilassa. errors: vain failed-tilassa.

Miten tila yhdistetään lähettämääsi viestiin?

wamid-tunnisteella. Lähetyspyyntö palauttaa messages[0].id:n, ja jokaisella tilalla tuolle viestille on sama arvo statuses[].id:ssä. Tallenna se omaan tietueeseesi lähettäessäsi ja päivitä tietue, kun tilat saapuvat. Pidä korkein saavutettu tila, jotta myöhään saapuva delivered ei ylikirjoita read-tilaa. Tila, jonka wamid on tuntematon, on lähetetty jonkin muun toimesta numerolla, esimerkiksi automaatiolla, ja sen voi jättää huomiotta tai kirjata.

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));
  }
}

Mitä muuttuu Coexistence-numerolla?

Tilat kuvaavat API:n kautta lähetettyjä: automaatioidesi vastauksia, tekoälysi MCP-liittimellä lähettämiä viestejä ja oman koodisi lähettämiä viestejä. Se, mitä omistaja kirjoittaa WhatsApp Business -sovelluksessa, välittyy ohjelmistoon eri tavalla, smb_message_echoes-kenttänä, jonka Meta dokumentoi sovelluksesta lähetettyjen viestien peilinä. Kertaluonteisen historiatuonnin viestit kantavat oman tilansa historia-webhookin sisällä, arvoilla kuten delivered, read, played, pending ja error.

Tilat kulkevat aina sinne, minne numeron messages-kenttä kulkee. Suoralla kohteella Meta lähettää ne suoraan päätepisteeseesi, koska messages on kenttä, jonka Meta sallii kohteen ohittaa. Kun automaatiot ovat käytössä ja Forward URL on asetettu, ne saapuvat siihen URL:iin messages-tapahtumina.

Miten tekoälysi tai automaatiosi saa tietää, että viesti toimitettiin?

Kohteesi kautta, ei lähetyksen kautta. Kun assistentti kutsuu send_template- tai send_message-työkalua, työkalun tulos sisältää wamid-tunnisteen ja kertoo, että Meta hyväksyi viestin. Toimitus vahvistetaan myöhemmin asiakkaan laitteella ja raportoidaan tilana. easyCoexistence ei säilytä tilahistoriaa, josta voisi kysellä, eikä mikään MCP-työkalu lue tiloja. Agentin, joka tarvitsee toimitusvahvistuksen, kannattaa siksi lähettää viesti omaa järjestelmääsi kautta tai lukea tilat, joita Forward URL vastaanottaa.

Sama pätee automaatioihin: Runs-välilehden ajo näyttää vastausvaiheen valmiiksi, kun Meta on hyväksynyt viestin, ja myöhemmin ilmoitettu virhe näkyy kohteessasi vain epäonnistuneena tilana.

Yleiset virheet

  • Erillisen statuses-kentän etsiminen. Tilat tulevat messages-kenttään, joten käsittelijä, joka lukee vain value.messages-kenttää, menettää ne ilman virhettä.
  • delivered-tilan vaatiminen ennen read-tilaa. Meta jättää delivered-webhookin pois, kun viesti luetaan heti saapuessaan.
  • Lähetysvastauksen käsittely toimituksena. wamid tarkoittaa, että Meta hyväksyi pyynnön; virhe voi seurata minuuteissa epäonnistuneena tilana.
  • Asiakkaiden tunnistaminen pelkällä recipient_id:llä. Kenttä puuttuu, kun lähetit BSUID:lle eikä puhelinnumero ole saatavilla; BSUID on recipient_user_id:ssä.
Näin teet tämän EasyCoexistencen avulla

Automaatioidesi, tekoälysi tai koodisi lähettämien viestien tilat menevät palvelimellesi: suoraan Metalta suoralla kohteella tai välitettynä Forward URL:iin allekirjoitettuna X-EC-Signature-otsakkeella, kun automaatiot ovat käytössä. Niitä ei tallenneta oletuksena. US$ 9:stä US$ 0,75:een numeroa kohden kuukaudessa, hinta laskee numeroiden lisääntyessä. Ensimmäiset 3 päivää ilmaiseksi.

Usein kysytyt kysymykset

Sisältävätkö tilawebhookit viestin tekstin?

Eivät. Tila sisältää wamid-tunnisteen, tilan, vastaanottajan, aikaleimat ja tarvittaessa hinnoittelun ja virheet. Säilytä oma kopiosi lähettämästäsi viestistä, avainnettuna wamid-tunnisteella, jos haluat näyttää sen tilan vieressä.

Voinko hakea menneet tilat Metalta myöhemmin?

Et. Metan webhook-oppaan mukaan historiallisen webhook-datan hakemiseen ei ole API-rajapintoja, joten tila, jota päätepisteesi ei tallentanut, on poissa, kun Meta lopettaa uudelleenyritykset, enintään 7 päivän kuluttua.

Mihin biz_opaque_callback_data on tarkoitettu?

Se on merkkijono, jonka asetat lähetyksessä, esimerkiksi oman tilaus- tai tikettitunnuksesi. Meta palauttaa sen kyseisen viestin statuses-taulukossa, joten voit yhdistää tilan omaan tietueeseesi katsomatta ensin wamid-tunnistetta.

Pitääkö tila-webhookeihin vastata 200:lla?

Kyllä, kuten mihin tahansa webhook-POST-pyyntöön. Meta pitää muuta vastausta epäonnistuneena toimituksena ja yrittää uudelleen, mikä on yksi tapa, jolla sama tila saapuu kahdesti.

Lue lisää

Valmis aloittamaan?

Ota WhatsApp Coexistence käyttöön minuuteissa, ei kuukausissa. Sovellus toimii edelleen puhelimessa.

Aloita ilmainen kokeilu

Vahvistettu