Kirjaudu sisäänAloita ilmainen kokeilu
easyCoexistence Viralliset API:t

Messenger-webhook Facebook-sivuille: viestit ja maininnat

Facebook-sivujen webhookien messages-kenttä laukeaa, kun henkilö lähettää sivulle Messenger-viestin. Se toimittaa messaging-taulukon, jossa ovat lähettäjän sivukohtainen ID, sivun ID, aikaleima sekä viestin mid ja sen teksti tai liitteet. Mention-kenttä ilmoittaa sivua koskevista uusista maininnoista julkaisuissa ja kommenteissa. Meta allekirjoittaa molemmat X-Hub-Signature-256-otsakkeella.

easyCoexistence välittää jokaisen yhdistetyn Facebook-sivun Messenger-viestit ja maininnat HTTPS-päätepisteeseesi heti niiden saavuttua, allekirjoitettuna sivukohtaisella salaisuudella, eikä kopiota säilytetä.

5 seconds

Kuinka nopeasti Messenger-webhookin päätepisteen pitää vastata jokaiseen ilmoitukseen 200 OK -vastauksella.

1 hour

Kun toimitukset ovat epäonnistuneet tämän ajan, Meta lopettaa sovelluksen tilaamisen sivun webhookeista, kunnes sovellus tilaa ne uudelleen.

PSID

Lähettäjän sivukohtainen ID messages-tapahtumassa, ainutlaatuinen jokaiselle henkilön ja sivun parille.

Workplace only

Miten Metan ohjeet merkitsevät maininta-tapahtuman sender-kentän.

No history

Aiempia webhook-ilmoituksia ei voi kysellä jälkikäteen, joten vastaanottajan on tallennettava tarvitsemansa tiedot.

Mitä messages-kenttä lähettää?

Ilmoituksen, kun henkilö lähettää sivulle Messenger-viestin. Meta lähettää tekstimuotoisia viestejä tai viestejä liitteillä, jotka voivat olla kuvia, äänitiedostoja, videoita, tiedostoja tai tarroja muiden tyyppien ohella, ja jaettu linkki voi saapua varaliitteenä. Aiempaan viestiin vastaus sisältää reply_to-kentän, jossa on sen viestin mid, ja pikavastaus sen payloadin.

Miltä messages-tapahtuma näyttää?

Toisin kuin syötemuutokset, viesti saapuu sivun entryn sisällä olevaan messaging-taulukkoon. Jokaisella tapahtumalla on sender, eli henkilön sivukohtainen ID; recipient, eli sivu; aikaleima; ja message, jossa on mid sekä teksti tai liitteet, joilla on tyyppi ja payload-URL:

A messages event, as Meta sends it
{
  "object": "page",
  "entry": [
    {
      "id": "<PAGE_ID>",
      "time": 1458692752478,
      "messaging": [
        {
          "sender": { "id": "<PSID>" },
          "recipient": { "id": "<PAGE_ID>" },
          "timestamp": 1458692752478,
          "message": {
            "mid": "<MESSAGE_ID>",
            "text": "hello, world!"
          }
        }
      ]
    }
  ]
}

Mitä mention-kenttä lähettää?

Muutoksen, jonka kenttä on mention. Se ilmoittaa, kun sivu mainitaan julkaisussa tai kommentissa. Mukana ovat post_id tai comment_id, viesti, mahdollinen linkki, kuva tai video sekä item ja verb. Meta varoittaa, että osaa julkaisu- ja kommentti-ID:istä ei voi kysellä, koska lupa puuttuu tai yksityisyyssyistä, ja sen ohjeiden mukaan sender-kenttä koskee vain Workplacea. Maininta voi siis saapua ilman tekijäänsä.

Mitä Messenger-kenttiä ei välitetä?

easyCoexistence tilaa sivut messages-kenttään, ei message_echoes-, messaging_postbacks-, message_reads- tai message_deliveries-kenttiin. Sivun lähettämiä viestejä, painikkeiden napautuksia ja luku- tai toimituskuittauksia ei siis välitetä. send_social_dm-kutsulla lähetetty vastaus palauttaa oman viesti-ID:nsä.

Miten tapahtumat saavuttavat päätepisteesi?

Meta toimittaa sivujen webhookit sovellukselle, jonka sivu on asentanut, yhden koko sovelluksen kattavan takaisinkutsu-URL:n kautta. easyCoexistence tarkistaa Metan X-Hub-Signature-256 -allekirjoituksen jokaisesta toimituksesta, vastaa Metalle heti ja välittää jokaisen yhdistetyn sivun entryn asettamaasi HTTPS-päätepisteeseen, allekirjoitettuna kyseisen sivun omalla salaisella avaimella. Aseta se set_social_webhook_destination-työkalulla Claudesta tai ChatGPT:stä, tai PUT-pyynnöllä osoitteeseen /channels/:id/webhook Partner API:ssa. Salainen avain näytetään kerran, uudelleen asettaminen luo uuden, ja null-URL pysäyttää välityksen.

Miltä välitetty tapahtuma näyttää?

POST-pyyntö, joka sisältää alustan, account_id:n, jonka list_social_accounts palauttaa sivun yhteydelle, sivun ID:n external_id-kentässä sekä entry, eli Metan sivua koskeva entry muuttumattomana. sender.id on sama kuin recipient_id, jonka send_social_dm hyväksyy vastaukseen 24 tunnin ikkunassa:

A forwarded messages event
{
  "platform": "facebook",
  "account_id": "<ACCOUNT_ID>",
  "external_id": "<PAGE_ID>",
  "entry": {
    "id": "<PAGE_ID>",
    "time": 1793318400000,
    "messaging": [
      {
        "sender": { "id": "<PSID>" },
        "recipient": { "id": "<PAGE_ID>" },
        "timestamp": 1793318399000,
        "message": { "mid": "<MESSAGE_ID>", "text": "<MESSAGE_TEXT>" }
      }
    ]
  }
}

Miten välitetty tapahtuma varmennetaan?

Jokaisessa välitetyssä POST-pyynnössä on X-EC-Signature-otsake muodossa t=<unix>,v1=<hex>. v1 on aikaleiman, pisteen ja raakarungon HMAC-SHA256, avaimena sivun allekirjoitussalaisuus. Laske se rungosta täsmälleen sellaisena kuin se saapui, vertaa vakioajassa ja hylkää aikaleima, joka on yli 5 minuuttia vanha.

Node.js: verifying X-EC-Signature
import crypto from "node:crypto";

// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
  const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  if (!sig.t || !sig.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(sig.t + "." + rawBody)
    .digest("hex");
  return expected.length === sig.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}

Yritetäänkö toimitus uudelleen?

Ei. easyCoexistence välittää jokaisen entryn kerran muistissa, eikä kopiota säilytetä uudelleenyritystä varten. Välitys odottaa vastausta 8 sekuntia, ei seuraa uudelleenohjauksia ja menee vain HTTPS-osoitteeseen, joka ratkeaa julkiseksi IP-osoitteeksi. Meta huomauttaa, ettei aiempia ilmoituksia voi kysellä jälkikäteen, joten tallenna tarvitsemasi heti saapuessaan. Meta yrittää epäonnistunutta toimitusta uudelleen muutaman kerran heti, joten sama viesti voi harvoin tulla sinulle kahdesti: tunnista kaksoiskappaleet mid-tunnuksen perusteella.

Yleiset virheet

  • Työn tekeminen ennen vastausta. Välitys ei yritä uudelleen, joten palauta 2xx heti ja käsittele tapahtuma myöhemmin.
  • Allekirjoituksen tarkistaminen jäsennetystä JSON:ista. Laske HMAC raakarungosta täsmälleen sellaisena kuin se saapui.
  • Oletus, että viestissä on aina teksti. Tarra, kuva tai jaettu linkki saapuu liitteinä, eikä siinä ole tekstikenttää.
  • Duplikaattien ohittaminen tarkistamatta. Meta voi toimittaa tapahtuman uudelleen virheen jälkeen, joten tunnista mid-tunnuksen perusteella ennen toimimista.
Näin teet tämän EasyCoexistencen avulla

send_social_dm vastaa 24 tunnin ikkunassa. Ota välitys käyttöön set_social_webhook_destination-työkalulla tai Partner API:lla. US$ 9:stä US$ 0,75:een yhteydeltä kuukaudessa, hinta laskee yhteyksiä lisättäessä, ja ensimmäiset 3 päivää ovat ilmaisia.

Usein kysytyt kysymykset

Mihin webhook-kenttiin easyCoexistence tilaa Facebook-sivun?

messages Messengeriä varten ja mention maininnoille, lisäksi feed sivun julkaisuille ja kommenteille.

Tuleeko Messenger-tarrassa tai kuvassa teksti mukana?

Ei. Tarra, kuva tai jaettu linkki saapuu liitteinä, joista jokaisella on tyyppi ja payload-URL, eikä viestissä ole tekstikenttää.

Kuinka nopeasti Messenger-webhookin päätepisteen pitää vastata?

200 OK -vastauksella 5 sekunnin kuluessa. Kun toimitukset ovat epäonnistuneet tunnin ajan, Meta lopettaa sovelluksen tilaamisen sivun webhookeista.

Miten vastaan välitettyyn viestiin?

Kutsu send_social_dm-työkalua ja anna tapahtuman sender.id recipient_id-kentässä 24 tunnin kuluessa henkilön viestistä.

Lue lisää

Yhdistä ensimmäinen kanavasi kahdessa minuutissa.

Ei alustojen tarkastuksia odotettavana. Yhdistä WhatsApp, Instagram, TikTok tai jokin muu kanava, pyydä sitten tekoälyäsi julkaisemaan, vastaamaan tai raportoimaan ja seuraa, kun se hoitaa homman.

  • 3 päivää ilmaiseksi
  • Peruuta milloin tahansa
  • Vain viralliset API:t
  • Valvottu 24/7

Vahvistettu