BotNetwork

Guide 14

Messenger and Instagram bots: Meta Messenger Platform webhooks, messaging windows and setup

Messenger and Instagram Direct share one platform, one webhook format and the same rules about when a business may message a person.

Guide2 min readUpdated

How it fits together

Messenger and Instagram messaging bots are Meta apps that receive webhooks for a Facebook Page or an Instagram professional account linked to a Page. You reply with the Send API using a Page access token. WhatsApp uses a separate product, the WhatsApp Cloud API, even though the webhook verification looks the same.

  1. Create an app in the Meta developer dashboard and add the Messenger product (and Instagram messaging if needed).
  2. Connect the Page and generate a Page access token. Store it as a secret.
  3. Configure the webhook URL and a verify token, then subscribe the Page to fields such as messages and messaging_postbacks.
  4. Test with accounts that have a role on the app. Other people can only use the bot after the required permissions pass app review.

Webhooks

Verification is a GET with hub.mode, hub.verify_token and hub.challenge: compare the token and echo the challenge. Every POST carries an X-Hub-Signature-256 header, an HMAC-SHA256 of the raw body with your app secret. Verify it with a constant-time comparison before parsing. You can generate test signatures with the webhook signature generator.

Respond 200 quickly and do the work asynchronously. Meta retries failed deliveries and may disable a webhook that keeps failing.

Sending messages

curl -X POST "https://graph.facebook.com/v21.0/me/messages" \
  -H "Authorization: Bearer $PAGE_TOKEN" -H "Content-Type: application/json" \
  -d '{"recipient":{"id":"PSID"},"messaging_type":"RESPONSE","message":{"text":"Hi!"}}'

Users are identified by a page-scoped ID (PSID), different for every Page. Graph API versions are dated; pin one and upgrade on purpose.

The 24-hour window

Businesses can message a person freely within 24 hours of that person's last message. Outside the window only specific cases are allowed, such as approved message tags (for example account updates) or flows the platform explicitly supports. Promotional messages outside the window violate the policy and can get the Page restricted. Read the current rules in the Messenger Platform policy documentation.

Useful features

  • Quick replies for short choices and postback buttons for menus.
  • Persistent menu and ice breakers to help people start.
  • Handover protocol to pass a conversation to a human inbox and take it back.
  • m.me links with a ref parameter to attribute where a conversation started. The deep link builder creates them.

Checklist

  • Verify signatures and keep the app secret and Page token out of source control.
  • Store PSIDs, not names, and delete data when a person asks.
  • Offer a clear way to reach a human and to stop messages.
  • Keep a privacy policy URL ready: app review requires it. See legal, terms and privacy.

Check your understanding

1. Outside the 24-hour window, which messages are allowed?
2. Which header proves a webhook came from Meta?