Meta

Messenger Platform (Meta)

Send Messenger texts, quick replies, images, templates and typing indicators, set Get Started, greeting and menu, and wire up webhooks.

CommunicationGuided#messenger#facebook#meta#chatbot#send-api#webhooks

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

The Messenger Platform lets a business answer and message people who contact its Facebook Page in Messenger, from its own software: text, quick replies, images and files, structured templates with buttons, typing indicators and reactions, plus the Page's welcome screen (Get Started button, greeting) and persistent menu. Sends go through the Send API (POST /{page-id}/messages) on the Graph API, authenticated with a Page access token, and everything people send you arrives by webhook. This guided collection covers that core flow end to end.

Set up, step by step

  1. Register as a Meta developer at developers.facebook.com and have a Facebook Page you can manage (a test Page is fine).
  2. In the App Dashboard choose Create app and add the use case Engage with customers on Messenger from Meta; attach a business portfolio when asked.
  3. Open Dashboard > Customize that use case. pages_messaging, pages_show_list, pages_manage_metadata, business_management and public_profile are required and already there; add optional ones you need, such as pages_user_locale, pages_user_timezone, pages_user_gender or the Business Asset User Profile Access feature for profile fields.
  4. In Messenger API Setup > Generate access tokens, click Connect and pick your Page. Under Configure webhooks enter your HTTPS callback URL and a verify token, then Add subscriptions for messages and messaging_postbacks.
  5. Get tokens: in the Graph API Explorer select your app, add pages_show_list, pages_messaging and pages_manage_metadata, click Generate Access Token and paste it into userAccessToken. The person generating it must be able to do the MESSAGING (and, for webhooks, MODERATE) task on the Page.
  6. Going live: publish the app (privacy policy URL, data deletion URL, icon). With Standard Access only people with a role on the app (admins, developers, testers) can message the bot and appear in webhooks; to serve the public, request Advanced Access in Review > App Review and complete Business verification. Meta's overview notes App Review is not needed when a business only messages for its own Page.

Tokens and permissions

All Messenger calls use a Page access token; the collection keeps it in pageAccessToken and sends it as Authorization: Bearer. The user token is used once, to fetch the Page token from /me/accounts. Each request description names its permission: pages_messaging for sending, sender actions and the Messenger profile; pages_manage_metadata for webhook subscriptions; profile fields need the Business Asset User Profile Access feature or the pages_user_* permissions.

The 24-hour standard messaging window

People always start the conversation. Their action (a message, Get Started, a reaction, an m.me link to an existing thread, a Page comment) opens a window of usually 24 hours (up to 7 days after a Click-to-Messenger ad). Inside it, send anything with messaging_type RESPONSE or UPDATE. Outside it, only non-promotional message tags (MESSAGE_TAG, e.g. HUMAN_AGENT within 7 days), utility templates, marketing messages or sponsored messages are allowed. Since April 27, 2026 the tags CONFIRMED_EVENT_UPDATE, ACCOUNT_UPDATE and POST_PURCHASE_UPDATE return error 100.

Base URL and version

https://graph.facebook.com/v27.0. v27.0 is the current Graph API version (released November 4, 2026, per the Graph API changelog); change graphVersion to move every request.

How to use this collection

  1. Fill in userAccessToken, run 1. Start here: it stores pageId, pageAccessToken, then (after you message your Page) recipientPsid and incomingMessageId, and subscribes the Page to webhooks.
  2. Try 2. Send messages, 3. Attachments (uploads store attachmentId), 4. Templates and 5. Sender actions.
  3. 6. User profile needs approved profile access; 7. Messenger profile sets Get Started, greeting and menu (set Get Started before the menu); 8. Webhooks tests your verification endpoint.

Limits

Sends are limited per Page (roughly 300 calls per second for text, 10 for audio and video), the Messenger Profile API to 10 calls per 10 minutes per Page, and overall usage scales with the number of people the Page can message. Very high volume can freeze the Page inbox. See rate limits. Sponsored messages are bought as ads.

Common errors

Code / subcodeMeaningWhat to do
190Access token invalid or expiredGet a new Page token from /me/accounts.
10 / 200Permission missing, or app not live for this person (200 / 2018028)Add pages_messaging; test with people who have a role on the app, or get Advanced Access.
10 / 2018278, 2534022Sent outside the standard messaging windowWait for the person to message again, or use an allowed message tag.
100Invalid parameter (2018001 no matching user; retired message tag)Check the PSID belongs to this Page and the body fields.
100 / 2018008, 2018047, 2018074Attachment fetch failed, wrong type, or bad attachment IDUse a public HTTPS URL, match type to the file, upload again.
551, 1545041Person not available (blocked the Page or unreachable)Stop sending to this PSID.
2018300Another app controls the conversationWait for a messaging_handovers pass_thread_control event.
613, 4Rate limitedSlow down and retry later.
2018218, 2018247No profile for this user / missing profile permissionSkip profile data or request the field's permission.

Errors come back as {"error": {"message", "type", "code", "error_subcode", "fbtrace_id"}}.

Links

Endpoints 27

1. Start here

  • GETList my Pages (and Page tokens)/me/accounts?fields=id,name,category,tasks,access_tokenLists the Facebook Pages your user can work on, each with its Page access token and the tasks you may perform there. The Send API only accepts a Page token…
  • GETFind the person's PSID (conversations)/{{pageId}}/conversations?fields=participants,messages{id,message}Lists the Page's Messenger conversations with their participants and latest messages. Use it to find the Page-scoped ID (PSID) of the person you want to…
  • POSTSubscribe the Page to messaging webhooks/{{pageId}}/subscribed_apps?subscribed_fields=messages,messaging_postbacks,message_deliveries,message_readsInstalls your app on the Page for webhooks and picks the Messenger fields the Page should send you. The same fields must also be ticked in App Dashboard >…
  • GETList the Page's subscribed apps/{{pageId}}/subscribed_appsShows which apps are installed on the Page for webhooks and the subscribed_fields of each. Run it to confirm the previous request; an empty data list means no…

2. Send messages

  • POSTSend a text message/{{pageId}}/messagesSends plain text to recipientPsid. Use messaging_type RESPONSE when you answer something the person sent; this is the first request to try after Find the…
  • POSTSend a proactive update (UPDATE, silent)/{{pageId}}/messagesSends a message that is not a reply, for example a status change you noticed on your side, while the 24-hour window is still open. messaging_type UPDATE…
  • POSTReply to a specific message (reply_to)/{{pageId}}/messagesSends a message that quotes an earlier message in the thread, so the person sees which question you are answering. Set reply_to.mid to a message ID: either…
  • POSTSend quick replies/{{pageId}}/messagesShows up to 13 buttons above the person's keyboard; they vanish once one is tapped, and the tapped title is posted as a normal message. Your webhook then…
  • POSTSend after the window (HUMAN_AGENT tag)/{{pageId}}/messagesSends a message outside the standard messaging window by declaring messaging_type MESSAGE_TAG and a tag. Tagged messages must be non-promotional (no deals,…

3. Attachments

  • POSTSend an image by URL/{{pageId}}/messagesSends one image that Meta downloads from payload.url. Use the same shape with type audio, video or file for other media. Leave is_reusable out (or false) when…
  • POSTSend several images at once/{{pageId}}/messagesSends up to 30 images in one message using message.attachments (an array, plural). Only image is allowed in this form. Permission: pages_messaging. Returns…
  • POSTUpload an attachment from a URL (Attachment Upload API)/{{pageId}}/message_attachmentsUploads a file without sending it and returns an attachment_id. Do this for assets you send often (a logo, a size chart, a welcome video) so Meta does not…
  • POSTUpload an attachment from a file/{{pageId}}/message_attachmentsSame as the previous request but sends the file itself as multipart form data: a message field holding the attachment JSON and a filedata file field. Pick the…
  • POSTSend an image by attachment_id/{{pageId}}/messagesSends a file you uploaded earlier, by payload.attachment_id instead of a URL. Run one of the upload requests first; they store attachmentId. type must match…

4. Templates

  • POSTSend a generic template (carousel)/{{pageId}}/messagesSends cards with a title, optional subtitle and image, an optional default_action (what tapping the card opens) and up to 3 buttons each. Put up to 10…
  • POSTSend a button template/{{pageId}}/messagesSends text (up to 640 characters) with 1 to 3 buttons below it. Good for a question with a few fixed answers or a mix of a link and an action. A postback…

5. Sender actions

  • POSTMark as seen/{{pageId}}/messagesMarks the conversation as read by the Page, so the person sees the seen indicator. Send it when your webhook receives a message. A sender action request…
  • POSTShow the typing indicator/{{pageId}}/messagesShows the typing bubble in the person's thread while you prepare an answer. It disappears when you send a message or typing_off, or after a short time on its…
  • POSTHide the typing indicator/{{pageId}}/messagesRemoves the typing bubble without sending a message, for example when you decide not to answer automatically and hand over to a person. A sender action…
  • POSTReact to a message/{{pageId}}/messagesAdds an emoji reaction from the Page to a message in the thread. payload.message_id is the message to react to (incomingMessageId), payload.reaction any…

6. User profile

  • GETGet a person's profile/{{recipientPsid}}?fields=first_name,last_name,profile_picReads profile fields for a PSID: GET /{psid}?fields=... with the Page token. Only ask for fields you were approved for. profile_pic is a temporary URL:…

7. Messenger profile (Get Started, greeting, menu)

  • GETGet the Messenger profile/me/messenger_profile?fields=get_started,greeting,persistent_menu,ice_breakersReads the current values of the listed properties. Run it before and after the next requests to see what changed. Properties that were never set are simply…
  • POSTSet the Get Started button/me/messenger_profileAdds a Get Started button to the welcome screen people see before their first message. Tapping it opens the standard messaging window and sends your webhook a…
  • POSTSet the greeting text/me/messenger_profileSets the greeting shown on the welcome screen. greeting is an array of {locale, text} objects: include one with locale default (used when no other locale…
  • POSTSet the persistent menu/me/messenger_profileSets the menu that stays available in the conversation. Each entry in persistent_menu is one locale (one must be default) with up to 20 call_to_actions of…
  • DELETEDelete profile properties/me/messenger_profileRemoves the properties named in fields; everything else stays. This example removes the persistent menu and the greeting. Delete the menu before you delete…

8. Webhooks

  • GETTest your webhook verification handshake{{webhookUrl}}?hub.mode=subscribe&hub.verify_token={{verifyToken}}&hub.challenge=1158201444Imitates Meta's verification request so you can test your own endpoint before saving it in the App Dashboard. It calls webhookUrl with hub.mode=subscribe,…

API details

Base URL
https://graph.facebook.com/v27.0
Authentication
A bearer token in the Authorization header
Operations
27 operations on 27 pathsPOST 20GET 6DELETE 1
Main resources
1. Start here 42. Send messages 53. Attachments 54. Templates 25. Sender actions 46. User profile 17. Messenger profile (Get Started, greeting, menu) 58. Webhooks 1
Description format
Swastik Codes guided collection, API version checked against the docs on 2026-11-17

How to test the Messenger Platform (Meta) in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Messenger Platform (Meta) collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “List my Pages (and Page tokens)” (GET /me/accounts?fields=id,name,category,tasks,access_token), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Messenger Platform (Meta)?

Send Messenger texts, quick replies, images, templates and typing indicators, set Get Started, greeting and menu, and wire up webhooks. It is listed under Communication and has 27 endpoints.

Who publishes the Messenger Platform (Meta)?

It is listed from Meta's public API description (an OpenAPI document), not published by Meta on Swastik Codes. Anyone who controls facebook.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Messenger Platform (Meta)?

Requests go to https://graph.facebook.com/v27.0. Endpoint paths are added to this base URL.

How do I authenticate with the Messenger Platform (Meta)?

With A bearer token in the Authorization header.

How many endpoints does the Messenger Platform (Meta) have?

27 operations on 27 paths (20 POST, 6 GET, 1 DELETE). The largest groups are 1. Start here, 2. Send messages, 3. Attachments, 4. Templates.

Is forking the Messenger Platform (Meta) free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.