EN
Tutorial

Facebook Messenger API Send Message Tutorial: Node.js, Python and PHP

Meta's Send API rules in 2026, then one REST call to send from your users' own accounts.

Your App Live
FacebookAnna LeePersonal FacebookNorthwind BakeryPage
Personal chat
Tom BeckerFrom Anna Lee
Can we move the demo?
Thursday 10am works for me.
Seen
Page chat
Maya RossTo Northwind Bakery
Do you deliver on Sundays?
Yes, 9am to noon.
Delivered
GETchats POSTmessages/send POSTchats/send 200 OK
Short answer

There are two ways to send a Facebook Messenger message via API. Meta's Send API sends from a Facebook Page, with a Page access token, only to people who messaged the Page in the last 24 hours. A unified API like Unipile sends from your user's connected account (a personal account or a Page they manage) with one REST call: POST /v2/{account_id}/chats/{chat_id}/messages/send.

POST/{PAGE-ID}/messagesMeta: reply as a Page
POST/v2/{account_id}/chats/{chat_id}/messages/sendUnipile: reply in an existing chat
POST/v2/{account_id}/chats/sendUnipile: write first
With Unipile

Send a Messenger message in three steps

  1. 1

    Connect. Your user links their Facebook account or Page through Hosted Auth. No Meta app, no App Review.

  2. 2

    Send. Call POST /v2/{account_id}/chats/{chat_id}/messages/send with your X-API-KEY and a text.

  3. 3

    Listen. The message.new webhook confirms the send and brings replies.

Choose a path

Two Ways to Send a Messenger Message via API

Meta's Send API acts for a Page your app manages. Unipile acts for the account your end user connected.

CriteriaMeta Send APIUnipile API
SenderA Facebook PageThe user's personal account, or a Page they manage
SetupMeta app, Page token with pages_messaging, App Review to serve other businesses' PagesAPI key and an account_id from Hosted Auth, no Meta app
Who writes firstAlways the personA personal account can; a Page only replies
Window24 hours, up to 7 days after a Click-to-Messenger adNo Send API window; Facebook can refuse a recipient
Sender
Meta Send APIA Facebook Page
Unipile APIThe user's personal account, or a Page they manage
Setup
Meta Send APIMeta app, Page token with pages_messaging, App Review to serve other businesses' Pages
Unipile APIAPI key and an account_id from Hosted Auth, no Meta app
Who writes first
Meta Send APIAlways the person
Unipile APIA personal account can; a Page only replies
Window
Meta Send API24 hours, up to 7 days after a Click-to-Messenger ad
Unipile APINo Send API window; Facebook can refuse a recipient

A bot for your own Page fits Meta's path; a CRM, helpdesk or AI agent in your customers' conversations needs a connected account. For the full map, see how the Facebook APIs fit together.

Meta Send API

How to Send a Message with the Facebook Graph API (Send API)

Meta's official path is the Send API of the Messenger Platform: POST https://graph.facebook.com/v27.0/{PAGE-ID}/messages with a Page access token holding pages_messaging, a recipient.id, a messaging_type and a message object. It only answers people who wrote to your Page.

1

Create a Meta app and link a Page

Add Messenger, connect the Page.

2

Get a Page access token

With pages_messaging; App Review to serve other businesses. See our Facebook API access token guide.

3

Send the request

Address the person by their PSID (Page-scoped ID), read from the messages webhook.

Facebook Send API request
access_tokenPage access token
recipient.idThe person's PSID
messaging_typeRESPONSE, UPDATE or MESSAGE_TAG
message.text"Hello, world!"
responserecipient_id, message_id
POST graph.facebook.com/v27.0/{PAGE-ID}/messages 200 OK
  • RESPONSE: a reply, inside the window.
  • UPDATE: a message you initiate, inside the window.
  • MESSAGE_TAG: outside the window, with a tag and non promotional content.

Where the PSID comes from

1Inbound

A person writes to your Page

Messenger
2POST

Meta calls your webhook

messages event
3PSID

Read the sender ID

messaging[0].sender.id
4POST

Reply with the Send API

recipient.id = PSID

In the messages event, sender.id is the person's PSID and recipient.id is your Page ID. Copy the request from the Meta cURL, Node.js, Python and PHP tabs of the code block below.

Sources: Meta's Send a Message and messages webhook event documentation. Last verified: November 17, 2026.

Rules

The Messenger 24-Hour Window and Message Tags in 2026

The Send API only writes to people who wrote to the Page, for 24 hours after their last message, or up to 7 days after a Click-to-Messenger ad. Past that, HUMAN_AGENT covers a human reply within 7 days, and three update tags have failed with error 100 since April 27, 2026.

Start

The person writes

It opens the standard window.

0 to 24 h

Window open

Send with RESPONSE or UPDATE.

Up to 7 days

Human agent

HUMAN_AGENT tag, for a reply written by a person.

After

Window closed

Wait for a new message.

Retired on April 27, 2026

Requests with the CONFIRMED_EVENT_UPDATE, ACCOUNT_UPDATE or POST_PURCHASE_UPDATE tags now fail with error code 100.

Sources: Meta's Send API reference and Send a Message. Last verified: November 2026.

Tutorial

Send a Facebook Messenger Message from a Connected Account (Node.js, Python, PHP, cURL)

Your user connects their Facebook account once and you get an account_id. List their chats, then send in a chat_id. Requests go to https://api.unipile.com with your key in the X-API-KEY header, through the Facebook Messenger API by Unipile. The Meta tabs send the same reply with Meta's Send API, from a Page you manage.

1

Connect the account

The user signs in on a Hosted Auth page. Details in our Messenger API for personal accounts guide.

2

List the chats

GET /v2/{account_id}/chats returns up to 100 chats per page.

3

Send the message

One POST with a text field.

# 1. List chats
curl --request GET \
     --url 'https://api.unipile.com/v2/acc_123456789/chats?limit=20' \
     --header 'X-API-KEY: YOUR_API_KEY' \
     --header 'accept: application/json'

# 2. Send a message
curl --request POST \
     --url https://api.unipile.com/v2/acc_123456789/chats/CHAT_ID/messages/send \
     --header 'X-API-KEY: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{ "text": "Thanks, your order ships today." }'
// npm i @unipile/sdk
import { UnipileMessaging } from '@unipile/sdk';

const request_options = {
  baseUrl: 'https://api.unipile.com',
  headers: { 'X-API-KEY': 'YOUR_API_KEY' },
  throwOnError: true,
};
const messagingApi = new UnipileMessaging();

// 1. List chats
const chats = await messagingApi.getChatsList({
  ...request_options,
  path: { account_id: 'acc_123456789' },
  query: { limit: 20 },
});

// 2. Send a message
await messagingApi.sendMessage({
  ...request_options,
  path: { account_id: 'acc_123456789', chat_id: 'CHAT_ID' },
  body: { text: 'Thanks, your order ships today.' },
});
import unipile

configuration = unipile.Configuration()
configuration.api_key["apiKey"] = "YOUR_API_KEY"
api_client = unipile.ApiClient(configuration)
messaging_api = unipile.MessagingApi(api_client)

# 1. List chats
chats = messaging_api.get_chats_list("acc_123456789", limit=20)

# 2. Send a message
messaging_api.send_message(
    "CHAT_ID",
    "acc_123456789",
    {"text": "Thanks, your order ships today."},
)
<?php
$base = 'https://api.unipile.com/v2/acc_123456789';
$headers = ['X-API-KEY: YOUR_API_KEY', 'accept: application/json'];

// 1. List chats
$ch = curl_init("$base/chats?limit=20");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
]);
$chats = json_decode(curl_exec($ch), true);
curl_close($ch);

// 2. Send a message
$ch = curl_init("$base/chats/CHAT_ID/messages/send");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => array_merge($headers, ['content-type: application/json']),
    CURLOPT_POSTFIELDS => json_encode(['text' => 'Thanks, your order ships today.']),
    CURLOPT_RETURNTRANSFER => true,
]);
$sent = json_decode(curl_exec($ch), true);
curl_close($ch);
# Meta Send API: reply to a person who messaged your Page
curl -X POST \
     "https://graph.facebook.com/v27.0/PAGE_ID/messages?access_token=PAGE_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "recipient": { "id": "PSID" },
       "messaging_type": "RESPONSE",
       "message": { "text": "Thanks, your order ships today." }
     }'
// Node.js 18+: built-in fetch, no SDK
const url = 'https://graph.facebook.com/v27.0/PAGE_ID/messages'
  + '?access_token=' + process.env.PAGE_ACCESS_TOKEN;

const res = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    recipient: { id: 'PSID' },
    messaging_type: 'RESPONSE',
    message: { text: 'Thanks, your order ships today.' },
  }),
});
const data = await res.json(); // { recipient_id, message_id }
# pip install requests
import requests

resp = requests.post(
    "https://graph.facebook.com/v27.0/PAGE_ID/messages",
    params={"access_token": "PAGE_ACCESS_TOKEN"},
    json={
        "recipient": {"id": "PSID"},
        "messaging_type": "RESPONSE",
        "message": {"text": "Thanks, your order ships today."},
    },
)
print(resp.json())  # {"recipient_id": "...", "message_id": "..."}
<?php
$url = 'https://graph.facebook.com/v27.0/PAGE_ID/messages?access_token=PAGE_ACCESS_TOKEN';
$payload = [
    'recipient' => ['id' => 'PSID'],
    'messaging_type' => 'RESPONSE',
    'message' => ['text' => 'Thanks, your order ships today.'],
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
]);
$sent = json_decode(curl_exec($ch), true); // recipient_id, message_id
curl_close($ch);
200 OK · { "object": "MessageSent", "message_id": "..." }
200 OK · { "recipient_id": "PAGE-SCOPED-ID", "message_id": "AG5Hz2U..." }

The first four tabs call Unipile for a connected account; the same request works for LinkedIn, WhatsApp, Instagram and Telegram. The Meta tabs call Meta's Send API for your own Page, with a Page access token and the person's PSID (how to get the PSID). References: Unipile Facebook, Send messages and Meta Send a Message (v27.0, verified November 17, 2026).

First message

How to Start a New Messenger Conversation by API

When there is no chat yet, call POST /v2/{account_id}/chats/send with the person's ID in users_ids and your text. Meta's Send API cannot do this.

Base URL https://api.unipile.com
POST/v2/{account_id}/chats/sendStart a Chat
users_idsID of a person or a Page
text"Hi Tom, quick question"
attachmentsOptional files
SDK: startChat (Node.js), start_chat (Python) 200 OK

The response returns the new chat_id and the message_id.

If Facebook does not allow the account to message this person, the request fails with provider/access_restricted.

Page inbox limitations

A Page cannot start a conversation (501 api/not_implemented) or delete its messages.

Pages

How to Reply as a Facebook Page by API

A Page the user manages answers through the same account_id: list the inboxes, open the Page inbox, then send with a Page chat ID. How Pages and their tokens work on Meta's side is covered in our Facebook Page API guide.

Facebook Personal inbox · INBOX
Tom BeckerThursday 10am works for me.Personal
chat_id: {chat_id}
Facebook Page inbox · PAGE_<page_id>_INBOX
Maya RossDo you deliver on Sundays?Page
chat_id: PAGE_<page_id>_<thread_key>
GET/v2/{account_id}/inboxesLists the Page inboxes
GET/v2/{account_id}/inboxes/{inbox_id}/chatsLists the Page's chats
POST/v2/{account_id}/chats/PAGE_1357020157484056_100001234567890/messages/sendReplies as the Page

The general chat list only returns personal chats. The PAGE_ prefix makes Unipile act as the Page. Details in the Facebook Pages documentation.

Attachments

Send Images and Files in a Messenger Chat

Add an attachments array to the same send endpoint. For large files, use multipart.

POST/v2/{account_id}/chats/{chat_id}/messages/sendSend a Message
textOptional caption, can be ""
contentThe file encoded in base64
content_type"image/png"
filename"image.png"
Large file: multipart/form-data 200 OK

Encrypted chats. On end-to-end encrypted personal chats, each file is sent as a separate message.

Meta equivalent. The Send API takes an attachment object with a type and a url, up to 30 images per send.

Real time

Confirm Delivery and Receive Replies with Webhooks

A 200 means Facebook accepted the message, not that it was delivered. Delivery is confirmed by the message.new webhook event, which also brings replies.

1POST

Your app sends

messages/send
2Accepted

Unipile answers

200 MessageSent
3Confirmed

Webhook: sent

message.new
4Receipts

Delivered, then read

message.receipt.delivery message.receipt.read
Facebook message.new event
type"message.new"
account_idThe connected account
payloadA Message object: id, chat_id, sender_id, text, timestamp, is_sender

It fires for sent and received messages; see is_sender.

Route Page events by the PAGE_<page_id>_ prefix of their chat_id, which can differ from the API one. Setup in Configure a webhook.

On Meta's side, a Page bot built on the Send API needs its own Messenger webhook. It is also where you read the PSID before replying.

Source: Meta's Messenger webhooks. Last verified: November 17, 2026.

Facebook Meta Messenger webhook
VerifyGET with hub.mode=subscribe and your hub.verify_token: return hub.challenge
SignatureX-Hub-Signature-256: SHA256 of the payload with your App Secret
Fieldsmessages, message_deliveries
Answer200 OK within 5 seconds
Errors

Errors When Sending Messenger Messages

Most sending errors come from a rule: a retry fails again. A token without pages_messaging blocks every Send API call.

ErrorMeaningFix
Meta 100Invalid parameter, or a tag retired on April 27, 2026Check the PSID, drop the tag
Meta 10 / 2018278Message sent outside of the allowed windowWait for a new message, or send a HUMAN_AGENT reply
Meta 200 / 2018028Cannot message people who are not admins, developers or testers of the app: pages_messaging not approved yetFinish App Review, test with app roles meanwhile
Meta 551This person isn't receiving messages from you right nowDo not retry
Meta 613Rate limit exceededSend less often
Unipile provider/access_restrictedFacebook refuses this recipient for the accountDo not retry
Unipile 403 api/insufficient_permissionsPage not activated on the accountActivate it at reconnection
Unipile 501 api/not_implementedA Page started a chat or deleted a messageReply in an existing chat
Meta 100
MeaningInvalid parameter, or a tag retired on April 27, 2026
FixCheck the PSID, drop the tag
Meta 10 / 2018278
MeaningMessage sent outside of the allowed window
FixWait for a new message, or send a HUMAN_AGENT reply
Meta 200 / 2018028
MeaningCannot message people who are not admins, developers or testers of the app: pages_messaging not approved yet
FixFinish App Review, test with app roles meanwhile
Meta 551
MeaningThis person isn't receiving messages from you right now
FixDo not retry
Meta 613
MeaningRate limit exceeded
FixSend less often
Unipile provider/access_restricted
MeaningFacebook refuses this recipient for the account
FixDo not retry
Unipile 403 api/insufficient_permissions
MeaningPage not activated on the account
FixActivate it at reconnection
Unipile 501 api/not_implemented
MeaningA Page started a chat or deleted a message
FixReply in an existing chat

Sources: Meta's Messenger error codes and Unipile's error responses. Last verified: November 17, 2026.

Compliance

Each user sends from their own account

Unipile is an independent company, not an official Meta app and not a Meta Partner. It acts on behalf of authenticated users, who remain bound by Meta's terms. Use it for customer support, CRM and direct conversations.

Send your first message

Meta's Send API suits a bot on your own Page. For a Facebook Messenger API send message flow from your users' own accounts, connect them through Unipile.

European Commission
EU Regulated Digital Markets Act (DMA)

Each user connects their own account, with no profile storage. Unipile is not a Meta Partner. Our Digital Markets Act approach

All Facebook API endpoints in one place

Messages are one part of it. See every Facebook endpoint available with Unipile, from posts and comments to profiles and webhooks, or read the complete Facebook API guide.

Facebook Messenger API Send Message FAQ

Quick answers on sending Messenger messages by API.

No. The Send API only reaches people who messaged your Page, inside the messaging window, and a Page never writes first. A new conversation has to start from a connected personal account, for example with Unipile's POST /v2/{account_id}/chats/send.

Meta lists no official Python SDK for the Send API: POST to /{PAGE-ID}/messages with requests, as in the Meta Python tab above. Unipile provides a Python SDK, imported as unipile, with get_chats_list and send_message.

Send an HTTP POST with cURL or Guzzle: to /{PAGE-ID}/messages on the Graph API with a Page access token (Meta PHP tab), or to /v2/{account_id}/chats/{chat_id}/messages/send on Unipile with your X-API-KEY (PHP tab).

Install @unipile/sdk and call sendMessage with the account_id, chat_id and text, as in the Node.js tab above. For Meta's Send API, POST to /{PAGE-ID}/messages with fetch, as in the Meta Node.js tab.

With the Send API: a closed window (error 10, subcode 2018278), a tag retired on April 27, 2026 (error 100), a token without an approved pages_messaging (error 200, subcode 2018028) or a person who blocks your messages (error 551). With Unipile: provider/access_restricted when Facebook refuses the recipient, or a Page trying to start a conversation.

For a Page bot on Meta's platform, your endpoint answers the GET verification by returning hub.challenge, checks the X-Hub-Signature-256 signature with your App Secret and subscribes to messages; the sender.id of each event is the PSID you reply to. With Unipile, you register one URL and receive message.new events for every connected account.

No. Unipile is an independent company: it is not a Meta Partner and is not endorsed, sponsored or approved by Meta. The Meta tabs on this page call Meta's own public Send API; the other tabs call Unipile's API. Facebook and Messenger are trademarks of Meta Platforms, Inc.

No. The Meta app, the Page token and App Review belong to the Send API path only. With Unipile, your users connect their own Facebook account, or the Pages they manage, through hosted authentication, and you send with an account_id and your API key.

Unipile is designed in the spirit of the Digital Markets Act: each user connects their own account and messages go out on their behalf, in their own conversations, without Unipile storing user profiles. Details on our Digital Markets Act page.

Yes. Every connected account remains bound by Meta's Terms of Service. Send messages for legitimate needs such as support replies, CRM follow-ups and conversations people expect; bulk unsolicited messages and spam can get the account restricted.

Still have questions? Our team is here to help.

Talk to an expert