> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # Messenger > Send and receive Facebook Messenger conversations via the Orbit Messaging API # Messenger Facebook Messenger lets your business reach the \~1B monthly Messenger users from the same unified Orbit Messaging API used for SMS, WhatsApp, and email. Outbound replies are delivered through the Pages messaging surface; inbound user messages are POSTed to your webhook in real time. ## Send a message ```bash theme={null} curl -X POST https://api.orbit.devotel.io/api/v1/messages/messenger \ -H "X-API-Key: dv_live_sk_..." \ -H "Content-Type: application/json" \ -d '{ "to": "", "messaging_type": "RESPONSE", "message": { "text": "Hi! Thanks for messaging us." } }' ``` ### Response ```json theme={null} { "data": { "id": "msg_msgr_abc123", "status": "queued", "channel": "messenger" }, "meta": { "request_id": "req_xyz789", "timestamp": "2026-05-09T00:00:00Z" } } ``` ## Capabilities * **Text, media, files** — text, image, video, audio, generic file attachments. * **Buttons** — `postback`, `web_url`, and `phone_number` button types via the structured-message body. * **Generic templates** — single + multi-card carousels with title, subtitle, image, and up to 3 buttons per card. * **One-time notifications (OTN)** — request and consume OTN tokens for a single follow-up outside the 24-hour window. * **Persistent menu + greeting text** — configured directly through Meta's Graph API against your connected Page. Orbit does not manage these from the dashboard. * **Webhook events** — `message.received` fires for inbound text and attachment messages; `message.sent`, `message.delivered`, `message.read`, and `message.failed` cover the outbound lifecycle. Postbacks and referrals (button taps, m.me links, ad clicks) are received and processed by Orbit but are **not** currently dispatched to your webhook, so do not build automations that expect a `message.received` event for them. Opt-in plugin events update the recipient's consent record server-side rather than firing a webhook. Messenger reports delivery status to Orbit using the same status mapping as WhatsApp: `message.sent` fires when Meta accepts the outbound message, `message.delivered` fires when Meta confirms the message reached the recipient's device, and `message.read` fires when the recipient opens the conversation. Delivery receipts are relayed on this channel, so `message.delivered` can and does fire — you can use it as your delivery signal rather than treating `message.sent` (acceptance only) as confirmation. `message.failed` reflects a delivery failure reported by Meta; inspect the accompanying error code and treat it as a genuine send failure. ## Onboarding flow 1. From the dashboard, navigate to **Channels → Messenger**. 2. Click **Connect Page**. Meta's OAuth dialog requests `pages_messaging` and `pages_show_list`. 3. Select the Page(s) you want to attach. Orbit subscribes the Page to webhooks automatically. 4. (Optional) Add sender **personas** from **Settings → Channels → Messenger** to reply as named agent identities (for example, "Sarah, Sales") on the same Page. Persistent menu and greeting text are configured directly through Meta's Graph API — Orbit does not manage them from the dashboard. ## Messaging windows | Tag | Window | Allowed content | | ----------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------- | | Standard 24h | Within 24h of the user's last message | Any allowed content | | `HUMAN_AGENT` | 7 days | Replies from a human agent only | | `MESSAGE_TAG` (CONFIRMED\_EVENT\_UPDATE / POST\_PURCHASE\_UPDATE / ACCOUNT\_UPDATE) | Anytime | Tagged transactional content only | | One-time notification (OTN) | One message per token | Promotional and re-engagement content | ## Common errors | Code | HTTP | Cause | Fix | | ------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `INVALID_RECIPIENT` | 422 | The recipient PSID in `to` is missing or empty. | Supply a valid Page-Scoped ID (PSID) for the recipient. | | `MESSAGING_WINDOW_CLOSED` | 422 | A `RESPONSE`/`UPDATE` message — or a `MESSAGE_TAG` message sent without a `tag` — was sent more than 24h after the user's last inbound message. The response `details` include `hours_since_last_inbound` and `last_inbound_at`. | Switch to `messaging_type: MESSAGE_TAG` with a Meta-approved `tag`, use a `HUMAN_AGENT` window, consume an OTN token, or wait for the user to message you again. | | `MESSAGE_SEND_FAILED` | 502 | Meta's Send API rejected the request — expired Page access token (Meta rotates \~every 60 days), dropped webhook subscription, or an invalid/blocked recipient. Upstream detail is in `details.provider_message`. | If the token expired, reconnect from **Channels → Messenger → Reconnect**; if the subscription dropped, click **Re-subscribe** on the channel detail page; otherwise inspect `details`. | | `RATE_LIMIT_EXCEEDED` | 429 | Per-tenant send rate limit exceeded. | Honour `Retry-After`; batch via campaigns when possible. | ## Pricing Messenger is always \$0 on Orbit's side. Because you connect your own Meta Page with your own credentials, Orbit hosts the integration but is not the provider of record — every Messenger message (inbound, outbound within the 24-hour window, `MESSAGE_TAG`, `HUMAN_AGENT`, and OTN) is free on the platform and never deducts from your wallet. Any charges for Messenger volume are billed by Meta directly to your Meta account under Meta's own pricing, not through Orbit. See the [pricing page](https://orbit.devotel.io/pricing).