How to Create a Facebook Messenger Bot with a Verified Webhook

What you need before building

Prove the Page, app, permission, and policy path before polishing dialogue. A local webhook can be correct while the provider setup still blocks every real user.

• Meta developer and Page ownership: Use an owned Meta developer account, create or select the correct Meta app, and record the Facebook Page, Business, app roles, Page tasks, and responsible operator. Do not build around a personal profile inbox.
• One bounded conversation: Choose one user-initiated job with a human fallback. This fixture accepts an order reference, returns a fictional status, and supports `HUMAN`; it does not collect payment, identity documents, health data, or an open-ended marketing opt-in.
• Public HTTPS and durable state: Plan one stable HTTPS callback, a raw-body request path, a unique constraint on provider message identity, a pending-work table or queue, bounded logs, and a worker retry path before subscribing the Page.
• Policy, privacy, and access decision: Read the current Messenger policies, decide retention and deletion ownership, document the 24-hour response boundary and human handoff, and identify whether public users trigger Advanced Access or review.

Credentials and access

Meta Messenger Platform constraints

• A Facebook Page is required, and the person must initiate the conversation. Meta describes the inbound webhook and 24-hour reply flow in the current overview.
• Standard Access is initially limited to people with an app or claimed-Page role. Serving people without those roles can require Advanced Access, App Review, and Business Verification. Test access does not prove public access.
• The Page access token must come from a person with the required Page task. The app needs the current permissions for its exact flow, including `pages_messaging`; do not request every Page or business permission by default.
• Messaging rules, access terms, rate limits, review requirements, dashboard paths, and Graph API versions change. Re-check first-party Meta documentation before implementation and again immediately before publication.
• Meta currently describes the Messenger Platform itself as free to use. Playcode, hosting, review work, monitoring, support operations, and any external provider still have their own cost and plan boundaries.

Official references: Messenger Platform overview, Messenger webhooks, Messenger Send API, Messenger policy and usage guidelines, Meta Messenger Platform API collection

Choose where the reply work happens

Meta needs a prompt webhook acknowledgement, while your business needs durable, retryable effects. The choice is not webhook versus polling here; Messenger uses webhooks for inbound Page events. The real choice is whether you perform work inside the request or claim it and continue from a worker.

Recommended:Persist the authenticated `message.mid` and safe fingerprint under a unique constraint, create pending work, return HTTP 200, then let a bounded worker authorize and send. Use a transactional outbox when one business write and one outbound reply must remain coordinated across a crash.

Create the Messenger Page-support bot in eight steps

The sequence separates provider ownership, callback authentication, message identity, business authorization, outbound sending, testing, and live delivery so one green check cannot hide another missing boundary.

if (query['hub.mode'] !== 'subscribe') return forbidden()
if (!safeEqual(query['hub.verify_token'], env.MESSENGER_VERIFY_TOKEN)) return forbidden()
return text(query['hub.challenge'], { status: 200 })

const rawBody = await readRawBody(request)
const expected = 'sha256=' + hmacSha256(env.META_APP_SECRET, rawBody)
if (!safeEqual(request.headers.get('x-hub-signature-256'), expected)) return unauthorized()
const payload = JSON.parse(rawBody.toString('utf8'))

await fetch(`https://graph.facebook.com/${GRAPH_VERSION}/${PAGE_ID}/messages`, {
  method: 'POST',
  headers: { authorization: `Bearer ${PAGE_ACCESS_TOKEN}`, 'content-type': 'application/json' },
  body: JSON.stringify({
    recipient: { id: senderPsid },
    messaging_type: 'RESPONSE',
    message: { text: safeReply },
  }),
})

What the result can look like

Test the webhook, retry, authorization, and live provider boundary

A green callback check proves only one boundary. Keep local deterministic handler evidence separate from Page ownership, access approval, subscription, Send API delivery, and the two-account production smoke.

Common Facebook Messenger bot failures

Diagnose callback ownership, POST authentication, Page subscription, access level, business authorization, response-window rules, and Send API delivery separately. They fail for different reasons and need different fixes.

Operate the bot as a Page-support system

Deploy

Deploy one stable HTTPS callback with separate verification-token, App-Secret, and Page-access-token configuration. Pin a current Graph API version and record the owner, purpose, Page, app, environment, and rotation date for each credential.

Subscribe only after the record-before-ack path, pending worker, authorization check, retry controls, human handoff, retention, deletion, and bounded observability are ready. A green GET verification is not a release decision.

Monitor

Track GET failures, signature failures, accepted and duplicate message IDs, invalid event classes, pending age, worker attempts, authorization denials, Send API status and request IDs, response latency, rate-limit signals, handoff age, and policy incidents.

Use hashed or redacted identifiers and bounded error context. Do not log verification tokens, App Secrets, Page access tokens, Authorization headers, full PSIDs, raw webhooks, customer messages, or order data by default.

Recover

Recover acknowledged but unfinished work by scanning durable pending records. Do not assume Meta will retry after your service returned HTTP 200, and do not create a new message record merely because the worker restarts.

For a credential exposure, identify which credential leaked, rotate only the affected boundary, confirm old access is revoked, reverify or resubscribe when required, and rerun signed fixtures plus a controlled two-account provider smoke.

Use record repair or worker replay for a bounded message problem. A whole-app saved-point restore also moves the message database backward and can make an already processed provider event appear new unless identity and post-checkpoint reconciliation are handled.

Protect secrets, Page access, customer data, and message consent

A valid Meta signature authenticates the delivery from the configured app. It does not prove that the Page is entitled to reveal an order, that a customer owns the supplied reference, or that an outbound message is allowed now.

• Keep the verification token, Meta App Secret, Page access token, app ID, Page ID, and Graph API version as separate named configuration values with different responsibilities and rotation paths.
• Verify HMAC on raw bytes before parsing, validate the intended Page, claim each provider message ID once before HTTP 200, and process effects from recoverable pending state.
• Derive business authorization from server state. Never let the Page-scoped sender ID, a message-supplied order ID, or model output authorize access or an external action by itself.
• Minimize stored message text and customer data, bound input length, redact routine logs, define retention and deletion owners, and protect list, detail, export, replay, handoff, and correction paths on the server.
• Respect user initiation, the current reply window, human-agent and automated-message rules, opt-out where applicable, review state, rate limits, Platform Terms, Messenger policies, and Community Standards. Do not build unsolicited bulk messaging.
• Use the official Messenger Platform. Do not automate a personal Facebook account, scrape inboxes, share tokens between customers, or bypass app, Page, review, verification, or access controls.

Facebook Messenger bot questions