{
  "data": {
    "id": "msg_msgr_abc123",
    "status": "queued",
    "channel": "messenger"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-05-09T00:00:00Z"
  }
}

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

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": "<recipient_psid>",
    "messaging_type": "RESPONSE",
    "message": {
      "text": "Hi! Thanks for messaging us."
    }
  }'

import { Devotel } from '@devotel-orbit/node';

const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY });

// Fully-typed per-channel method — prefer it over the generic send.
const message = await orbit.messages.sendMessenger({
  to: '<recipient_psid>',
  messaging_type: 'RESPONSE',
  message: { text: 'Hi! Thanks for messaging us.' },
});

console.log(message.data.id);      // msg_msgr_abc123
console.log(message.data.status);  // 'queued'

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

# The Python SDK is core-scope — reach Messenger through the generic
# client.request() escape hatch.
message = client.request("POST", "/messages/messenger", json_body={
    "to": "<recipient_psid>",
    "messaging_type": "RESPONSE",
    "message": { "text": "Hi! Thanks for messaging us." },
})
print(message["data"]["id"])      # msg_msgr_abc123
print(message["data"]["status"])  # queued

{
  "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. Full lifecycle below.
Sender personas — named agent identities set from Settings → Channels → Messenger; a send with persona_id renders that identity to the recipient instead of the Page silhouette. Full walkthrough below.
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 — see Inbound webhook envelope for the exact payload shapes.

What fires — and what does not

message.received fires for inbound text and attachment messages; message.sent, message.delivered, message.read, and message.failed cover the outbound lifecycle.
Postbacks (button taps) and referrals (m.me links, Click-to-Messenger ad clicks) are received and processed by Orbit but are not 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 when Meta confirms it reached the recipient’s device, and message.read when the recipient opens the conversation. Delivery receipts are relayed on this channel, so message.delivered can and does fire — treat it, not message.sent, as your delivery signal. message.failed reflects a delivery failure reported by Meta; inspect the accompanying error code and treat it as a genuine send failure.

When a flow must react to a button tap or an ad referral, do the reaction inside Orbit (flow or inbox automation), not in your webhook consumer.

Inbound webhook envelope

Every inbound user message POSTs one JSON object to your registered webhook endpoint. The envelope is the standard Orbit message envelope; scope handling to channel: "messenger". An inbound text message:

{
  "event": "message.received",
  "channel": "messenger",
  "message": {
    "text": "Do you ship internationally?",
    "from": "<sender_psid>"
  },
  "timestamp": "2026-08-27T09:14:03Z"
}

An inbound attachment message:

{
  "event": "message.received",
  "channel": "messenger",
  "message": {
    "attachments": [
      { "type": "image", "url": "https://cdn.example.com/attach/img_001.jpg" }
    ],
    "from": "<sender_psid>"
  },
  "timestamp": "2026-08-27T09:17:41Z"
}

An opt-in plugin event (processed server-side, consent record updated — no outbound webhook is fired):

{
  "event": "message.received",
  "channel": "messenger",
  "message": {
    "text": "Confirm this subscription",
    "from": "<sender_psid>",
    "metadata": { "opt_in": true }
  },
  "timestamp": "2026-08-27T10:02:11Z"
}

Two rules that keep integrators honest:

The sender’s PSID is what you send to. Capture message.from from this inbound event onto the contact — that value is the to of every outbound send.
Route control needs Orbit-side flows, not webhook filters. Postbacks and referrals arrive internally and are processed (button taps become an inbound message in the conversation timeline, ref parameters are attached to attribution), but they never leave Orbit’s envelope. Build reactions to them in flows, not in your webhook consumer.

Consume it — capture the PSID

Subscribe your endpoint to message.received and branch on channel: "messenger". The sender’s PSID sits in message.from — record it on your contact so every outbound send to that user can address them. Signature verification on the receiver is the same HMAC check used everywhere in Orbit; see Build your first webhook receiver for the full verifier.

app.post('/webhooks/orbit', (req, res) => {
  const event = req.body;

  if (event.event === 'message.received' && event.channel === 'messenger') {
    const psid = event.message.from;          // the `to` of all future outbound sends
    const text = event.message.text ?? '';    // empty for attachment-only messages
    const metadata = event.message.metadata ?? {};

    saveInbound({ psid, text, metadata });
  }

  res.sendStatus(200);
});

from flask import Flask, request

app = Flask(__name__)


@app.post("/webhooks/orbit")
def handle_webhook():
    event = request.get_json() or {}

    if event.get("event") == "message.received" and event.get("channel") == "messenger":
        message = event.get("message") or {}
        psid = message.get("from")            # the `to` of all future outbound sends
        text = message.get("text", "")        # empty for attachment-only messages
        metadata = message.get("metadata") or {}

        save_inbound(psid=psid, text=text, metadata=metadata)

    return "", 200

Onboarding

The full ordering — OAuth, Page selection, webhook subscription, personas, token health — is in Messenger onboarding playbook. The steps below are the same flow condensed.

From the dashboard, navigate to Channels → Messenger.
Click Connect Page. Meta’s OAuth dialog requests pages_messaging and pages_show_list.
Select the Page(s) you want to attach. Orbit subscribes the Page to webhooks automatically.

Required scopes

The OAuth dialog asks for two permissions, and both are required:

Scope	Purpose
`pages_messaging`	Read/write messages on behalf of the selected Page
`pages_show_list`	List the Pages your Meta user administers, so the Page-selection step has something to show

If your company routes Meta app review through a central team, pre-approve both scopes before the first connect or the attach step stalls in Meta’s dialog.

Required roles

You must be an admin of the Facebook Page you are attaching. Meta’s Page-selection dialog only lists Pages the signed-in Meta user controls.

Token expiry — reconnect

Page access tokens issued through the long-lived OAuth window rotate roughly every 60 days, and can go stale earlier after a password change, Page-admin removal, or Meta app review. Orbit tracks the token’s remaining lifetime and marks it valid, expiring_soon (7 days or fewer left), or expired on your channel status. When the channel flips to expired — or when you intentionally rotate — do this:

In Channels → Messenger, click Reconnect.
Re-run Meta’s OAuth dialog with the same scopes as on the first connect.
Re-select the same Page(s). Outbound sends resume immediately.

What changes after reconnect: the stored Page access token is replaced and the channel status returns to valid. The Channel status surface’s Reconnect action runs before expiring_soon becomes expired, so flows do not fall back to flat-out failed sends.

Limits

Personas

Each persona you create from Settings → Channels → Messenger is a Meta /me/personas object pinned to the connected Page:

Property	Limit / behaviour
Max personas per Page	Around 100 — relay Meta’s error on a cap hit
`name`	Up to 40 characters
`profile_picture_url`	Public HTTPS URL, fetched by Meta server-side at create time
Scope	Per-Page — a persona on Page A is not usable on Page B
Token rotation	Personas survive reconnect — rotating tokens does not re-create them

A send made with persona_id (the persona’s numeric Meta id, returned when you list personas) renders that persona’s name and avatar to the recipient instead of the default Page silhouette. Manage personas from the dashboard — create, list, and delete — and pass the returned id on your outbound sends. Skip personas for automation-only traffic; they exist for conversational inbox use.

One-Time Notification (OTN)

OTN is the single-message exception to a closed 24-hour window. The lifecycle is:

Request the token. Send an OTN request message to the recipient inside an open window (messaging_type: RESPONSE or MESSAGE_TAG). Meta renders the prompt; the recipient’s tap attaches a token to their PSID.
Spend the token. A subsequent send that references the token can go through even after the 24h window has closed — once. After that the token is consumed.
Expiry. An unused token expires when Meta rotates it; always pair requests with a short window before you intend to spend.

Track token spend server-side in your integration — OTN is for a single follow-up, not a campaign batch. Continuous follow-up outside the window belongs to MESSAGE_TAG or HUMAN_AGENT.

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. Upstream detail is in `details.provider_message`.	Match the variant below; reconnect, re-subscribe, or suppress as indicated.
`RATE_LIMIT_EXCEEDED`	429	Per-tenant send rate limit exceeded.	Honour `Retry-After`; batch via campaigns when possible.

`MESSAGE_SEND_FAILED` variants

MESSAGE_SEND_FAILED bundles different upstream failures behind the same code. Check details.provider_message before deciding the recovery path.

`details.provider_message` contains	Variant	Fix
”Invalid OAuth access token” or “expired”	Expired Page access token	Reconnect from Channels → Messenger → Reconnect and re-attach the Page(s).
”Subscribed app does not match” or “webhook subscription”	Dropped webhook subscription	Click Re-subscribe on the channel detail page, then re-run a test send.
”Cannot message a user who has blocked” or “blocked”	Recipient individually blocked appeals	Suppress the PSID from future sends; unblock needs to happen on the recipient’s side of the thread.
Blocked after spam reports	Recipient blocked by Meta after abuse reports	Treat as genuine failure; never retry. Orbit honours the block — PSIDs cannot be re-enabled via the API.
Other upstream string	Generic rejection	Inspect `details` and include its text when you open a support ticket.

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.

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Send and receive Facebook Messenger conversations

Messenger

Send a message

Capabilities

What fires — and what does not

Inbound webhook envelope

Consume it — capture the PSID

Onboarding

Required scopes

Required roles

Token expiry — reconnect

Limits

Personas

One-Time Notification (OTN)

Common errors

`MESSAGE_SEND_FAILED` variants

Pricing

​Messenger

​Send a message

​Capabilities

​What fires — and what does not

​Inbound webhook envelope

​Consume it — capture the PSID

​Onboarding

​Required scopes

​Required roles

​Token expiry — reconnect

​Limits

​Personas

​One-Time Notification (OTN)

​Common errors

​MESSAGE_SEND_FAILED variants

​Pricing

Messenger

Send a message

Capabilities

What fires — and what does not

Inbound webhook envelope

Consume it — capture the PSID

Onboarding

Required scopes

Required roles

Token expiry — reconnect

Limits

Personas

One-Time Notification (OTN)

Common errors

`MESSAGE_SEND_FAILED` variants

Pricing