Fb Message Laravel Package

Getting Started

• Install with composer require mortezamasumi/fb-message. v5.2.0 adds Laravel 13 support; the package tracks Laravel's major releases closely, so pin to ^5.2 if you're on Laravel 13 and to ^5.1 on Laravel 11/12 if you want to defer the upgrade.
• Publish the config first: php artisan vendor:publish --tag=fb-message-config. This is the single most important file — it holds the page access token, app secret, verify token, and webhook path.
• Set the credentials in .env (FB_PAGE_ACCESS_TOKEN, FB_VERIFY_TOKEN, FB_APP_SECRET) rather than editing the config directly, so per-environment pages work without code changes.
• Point your Meta app's Messenger webhook at the route the package registers (or your own controller calling into it), and use the same verify token you set in .env for the subscription handshake.
• First use case: an echo bot. Verify the webhook returns the hub_challenge, then reply to an incoming messages event with a plain text send. Once that round-trips, everything else (templates, buttons, attachments) is incremental.
• Look at the package's event/entry-point classes before writing a controller — most of the payload decoding is already done for you, and fighting that is the usual cause of a slow first day.

Implementation Patterns

• Webhook in, worker out. Accept the webhook, verify the signature, dispatch a job per messaging event, and return 200 immediately. Facebook retries aggressively on slow responses, and retries plus a synchronous handler means duplicate replies.
• One handler per event type. Route message, postback, quick_reply, and optin payloads to small dedicated classes. A single switch on entry[0].messaging[0] grows into an unmaintainable blob within a week.
• Keep the send layer behind your own abstraction. Wrap the package's send calls in a small Messenger service or a Laravel notification channel. When you need to add multi-page routing or a fallback provider, you change one class instead of fifty call sites.
• Multi-page support via config resolution. If you run several Facebook pages, resolve the token per page at runtime rather than relying on the single configured token. Keep page IDs in your database and pass tokens explicitly on send.
• Use queued jobs with per-conversation throttling. Facebook's send API rate limits are per-page, and a burst of replies from a job queue will hit them. A Redis::throttle or rate-limited queue middleware keyed by page ID is cheap insurance.
• Test with Http::fake(). Assert on the outgoing request body rather than mocking the package internals — the payload shape is the actual contract with Meta, and it's what silently breaks between versions.
• Local development: tunnel with expose or ngrok and keep a scratch Meta app separate from production. Webhook subscriptions are sticky and easy to break for real users while debugging.

Gotchas and Tips

• The 24-hour messaging window is the number-one source of production surprises. Outside the window, standard sends fail; you need message tags or a human-agent tag. Build the failure path before launch, not after your first "why did replies stop" page.
• Webhook verification is a GET, delivery is a POST. They are different code paths. A route that only handles POST will fail Meta's initial subscription check with a confusing error.
• Exempt the webhook route from CSRF. It's an external POST with no token; forgetting this yields 419s that look like signature failures.
• Verify X-Hub-Signature-256 against the raw body. Using $request->all() re-encoded will not match. Read getContent() before any middleware mutates it.
• Return 200 even on internal errors you've already logged — or better, only for events you've durably queued. Non-200 responses trigger retries and eventual subscription disablement.
• Version upgrades are usually just framework support — v5.2.0 is exactly that, a Laravel 13 compatibility bump with no API changes. Still, run your Http::fake() assertions after upgrading; framework major bumps occasionally change how the HTTP client serializes payloads.
• Config caching bites in CI. php artisan config:cache freezes the token; a .env change without re-caching silently does nothing.
• Debugging tip: log the full inbound webhook payload at debug level with a short retention. When Meta changes a field or adds a new event type, that log is the only evidence you'll have.
• Extension point: the config file's route and middleware settings are the sanctioned way to graft in auth, logging, or IP allowlisting. Prefer them over editing vendor code, which will be lost on the next composer update.