Send Messenger messages from a Facebook Page: text, images and files, quick replies, button and card templates, and typing indicators. Look up a person by their Page-scoped ID and read past conversations. The Messenger trigger runs a workflow when someone messages the Page, taps a button or quick reply, reacts, or arrives from an m.me link or ad. Replies go out within 24 hours of the person's last message, or within 7 days from a person using the Human Agent tag.
Get the most recent messages (up to 20) of a Messenger conversation with sender, recipients, text, attachments, and time, newest first.
| Parameter | Type | Required | Description |
|---|
pageAccessToken | string | Yes | Long-lived Page access token from someone who can perform the MESSAGING task on the Page, with pages_messaging, pages_manage_metadata, and pages_read_engagement |
conversationId | string | Yes | Conversation ID from List Conversations |
limit | number | No | Maximum messages to return (1-20; Meta only returns details for the 20 most recent) |
| Parameter | Type | Description |
|---|
messages | array | Messages, newest first |
↳ id | string | Message ID (mid) |
↳ createdTime | string | When the message was sent |
↳ text | string | Message text (empty for attachment-only messages) |
↳ from | object | Sender: the person or the Page |
↳ to | array | Recipients |
↳ attachments | array | Attached files and media |
↳ id | string | Attachment ID |
↳ name | string | File name |
↳ fileUrl | string | File URL |
↳ imageUrl | string | Image URL |
↳ videoUrl | string | Video URL |
Get a Messenger user's name and profile picture (and, with extra permissions, locale, timezone, and gender) by their Page-scoped ID.
| Parameter | Type | Required | Description |
|---|
pageAccessToken | string | Yes | Long-lived Page access token from someone who can perform the MESSAGING task on the Page, with pages_messaging, pages_manage_metadata, and pages_read_engagement |
psid | string | Yes | Page-scoped ID (PSID) of the person, e.g. senderPsid from the Messenger trigger |
fields | string | No | Comma-separated fields: id, name, first_name, last_name, profile_pic, locale, timezone, gender. Defaults to id,name,first_name,last_name,profile_pic. |
| Parameter | Type | Description |
|---|
id | string | PSID |
name | string | First and last name |
firstName | string | First name |
lastName | string | Last name |
profilePic | string | Profile picture URL (the URL expires) |
locale | string | Facebook locale, e.g. en_US |
timezone | number | Timezone offset from GMT in hours |
gender | string | Gender |
profileAvailable | boolean | False when Meta returned no profile data for this person |
List a Facebook Page's Messenger conversations with their participants and last update time, or find the conversation with one person by PSID.
| Parameter | Type | Required | Description |
|---|
pageAccessToken | string | Yes | Long-lived Page access token from someone who can perform the MESSAGING task on the Page, with pages_messaging, pages_manage_metadata, and pages_read_engagement |
pageId | string | No | Facebook Page ID. Defaults to the Page the access token belongs to (me). |
userId | string | No | PSID of a person, to return only the conversation with them |
limit | number | No | Maximum conversations to return (1-100) |
after | string | No | Cursor from a previous call (nextCursor) to fetch the next page |
| Parameter | Type | Description |
|---|
conversations | array | Conversations, most recently updated first |
↳ id | string | Conversation ID; pass it to Get Conversation Messages |
↳ updatedTime | string | When the last message was added |
↳ participants | array | The person and the Page |
nextCursor | string | Pass as After to fetch the next page; null on the last page |
hasMore | boolean | Whether another page is available |
Send an image, audio, video, or file to a person on Messenger from a public URL that Meta downloads.
| Parameter | Type | Required | Description |
|---|
pageAccessToken | string | Yes | Long-lived Page access token from someone who can perform the MESSAGING task on the Page, with pages_messaging, pages_manage_metadata, and pages_read_engagement |
pageId | string | No | Facebook Page ID. Defaults to the Page the access token belongs to (me). |
recipientId | string | Yes | Page-scoped ID (PSID) of the person, e.g. senderPsid from the Messenger trigger |
messagingType | string | No | RESPONSE (default; replying within the standard messaging window), UPDATE (proactive, within the window), or MESSAGE_TAG (outside the window; needs a tag) |
tag | string | No | Message tag for MESSAGE_TAG, e.g. HUMAN_AGENT (a person replying within 7 days of the last user message; needs the Human Agent permission) |
notificationType | string | No | Push notification type: REGULAR (default), SILENT_PUSH, or NO_PUSH |
attachmentType | string | Yes | image, audio, video, or file |
url | string | Yes | Public URL of the media for Meta to download |
isReusable | boolean | No | Save the media so it can be sent again by attachment ID (returns attachmentId) |
| Parameter | Type | Description |
|---|
recipientId | string | PSID the message or action was sent to |
messageId | string | ID (mid) of the sent message |
attachmentId | string | Reusable attachment ID |
senderAction | string | The sender action that was sent |
id | string | PSID of the looked-up person |
name | string | Full name |
firstName | string | First name |
lastName | string | Last name |
profilePic | string | Profile picture URL (expires) |
locale | string | Facebook locale |
timezone | number | Timezone offset from GMT |
gender | string | Gender |
profileAvailable | boolean | Whether Meta returned profile data |
conversations | json | Conversations (id, updatedTime, participants with id, name, email) |
messages | json | Messages, newest first (id, createdTime, text, from, to, attachments) |
nextCursor | string | Cursor for the next page |
hasMore | boolean | Whether another page is available |
Send a Messenger text message with up to 13 quick reply buttons, or buttons that ask for the person's phone number or email.
| Parameter | Type | Required | Description |
|---|
pageAccessToken | string | Yes | Long-lived Page access token from someone who can perform the MESSAGING task on the Page, with pages_messaging, pages_manage_metadata, and pages_read_engagement |
pageId | string | No | Facebook Page ID. Defaults to the Page the access token belongs to (me). |
recipientId | string | Yes | Page-scoped ID (PSID) of the person, e.g. senderPsid from the Messenger trigger |
messagingType | string | No | RESPONSE (default; replying within the standard messaging window), UPDATE (proactive, within the window), or MESSAGE_TAG (outside the window; needs a tag) |
tag | string | No | Message tag for MESSAGE_TAG, e.g. HUMAN_AGENT (a person replying within 7 days of the last user message; needs the Human Agent permission) |
notificationType | string | No | Push notification type: REGULAR (default), SILENT_PUSH, or NO_PUSH |
text | string | Yes | Message text shown above the quick replies |
quickReplies | json | Yes | Array of 1-13 quick replies. Each is a title string (also used as the payload) or { "title": "Yes" (max 20 chars), "payload": "YES" (max 1000 chars), "imageUrl": "https://..." }, or { "contentType": "user_phone_number" } / { "contentType": "user_email" }. |
| Parameter | Type | Description |
|---|
recipientId | string | PSID the message or action was sent to |
messageId | string | ID (mid) of the sent message |
attachmentId | string | Reusable attachment ID |
senderAction | string | The sender action that was sent |
id | string | PSID of the looked-up person |
name | string | Full name |
firstName | string | First name |
lastName | string | Last name |
profilePic | string | Profile picture URL (expires) |
locale | string | Facebook locale |
timezone | number | Timezone offset from GMT |
gender | string | Gender |
profileAvailable | boolean | Whether Meta returned profile data |
conversations | json | Conversations (id, updatedTime, participants with id, name, email) |
messages | json | Messages, newest first (id, createdTime, text, from, to, attachments) |
nextCursor | string | Cursor for the next page |
hasMore | boolean | Whether another page is available |
Show a typing indicator (typing_on, typing_off) or mark the person's messages as seen (mark_seen) in a Messenger conversation.
| Parameter | Type | Required | Description |
|---|
pageAccessToken | string | Yes | Long-lived Page access token from someone who can perform the MESSAGING task on the Page, with pages_messaging, pages_manage_metadata, and pages_read_engagement |
pageId | string | No | Facebook Page ID. Defaults to the Page the access token belongs to (me). |
recipientId | string | Yes | Page-scoped ID (PSID) of the person |
senderAction | string | Yes | typing_on, typing_off, or mark_seen |
| Parameter | Type | Description |
|---|
recipientId | string | PSID the action was shown to |
senderAction | string | The sender action that was sent |
Send a Messenger button template (text with up to 3 URL, postback, or call buttons) or a generic template (a card or carousel of up to 10 cards).
| Parameter | Type | Required | Description |
|---|
pageAccessToken | string | Yes | Long-lived Page access token from someone who can perform the MESSAGING task on the Page, with pages_messaging, pages_manage_metadata, and pages_read_engagement |
pageId | string | No | Facebook Page ID. Defaults to the Page the access token belongs to (me). |
recipientId | string | Yes | Page-scoped ID (PSID) of the person, e.g. senderPsid from the Messenger trigger |
messagingType | string | No | RESPONSE (default; replying within the standard messaging window), UPDATE (proactive, within the window), or MESSAGE_TAG (outside the window; needs a tag) |
tag | string | No | Message tag for MESSAGE_TAG, e.g. HUMAN_AGENT (a person replying within 7 days of the last user message; needs the Human Agent permission) |
notificationType | string | No | Push notification type: REGULAR (default), SILENT_PUSH, or NO_PUSH |
templateType | string | Yes | button or generic |
text | string | No | Button template text shown above the buttons (max 640 characters) |
buttons | json | No | Button template buttons, 1-3, e.g. [{ "type": "web_url", "url": "https://...", "title": "Book" }, { "type": "postback", "title": "Talk to us", "payload": "TALK" }, { "type": "phone_number", "title": "Call", "payload": "+16505551234" }]. Titles max 20 characters. |
elements | json | No | Generic template elements, 1-10, each { "title" (max 80), "subtitle" (max 80), "image_url", "default_action": { "type": "web_url", "url" }, "buttons": [up to 3 buttons] } |
| Parameter | Type | Description |
|---|
recipientId | string | PSID the message or action was sent to |
messageId | string | ID (mid) of the sent message |
attachmentId | string | Reusable attachment ID |
senderAction | string | The sender action that was sent |
id | string | PSID of the looked-up person |
name | string | Full name |
firstName | string | First name |
lastName | string | Last name |
profilePic | string | Profile picture URL (expires) |
locale | string | Facebook locale |
timezone | number | Timezone offset from GMT |
gender | string | Gender |
profileAvailable | boolean | Whether Meta returned profile data |
conversations | json | Conversations (id, updatedTime, participants with id, name, email) |
messages | json | Messages, newest first (id, createdTime, text, from, to, attachments) |
nextCursor | string | Cursor for the next page |
hasMore | boolean | Whether another page is available |
Send a text message from a Facebook Page to a person on Messenger by their Page-scoped ID (PSID).
| Parameter | Type | Required | Description |
|---|
pageAccessToken | string | Yes | Long-lived Page access token from someone who can perform the MESSAGING task on the Page, with pages_messaging, pages_manage_metadata, and pages_read_engagement |
pageId | string | No | Facebook Page ID. Defaults to the Page the access token belongs to (me). |
recipientId | string | Yes | Page-scoped ID (PSID) of the person, e.g. senderPsid from the Messenger trigger |
messagingType | string | No | RESPONSE (default; replying within the standard messaging window), UPDATE (proactive, within the window), or MESSAGE_TAG (outside the window; needs a tag) |
tag | string | No | Message tag for MESSAGE_TAG, e.g. HUMAN_AGENT (a person replying within 7 days of the last user message; needs the Human Agent permission) |
notificationType | string | No | Push notification type: REGULAR (default), SILENT_PUSH, or NO_PUSH |
text | string | Yes | Message text |
replyToMessageId | string | No | Message ID (mid) to reply to, shown as a quoted reply in the thread |
| Parameter | Type | Description |
|---|
recipientId | string | PSID the message or action was sent to |
messageId | string | ID (mid) of the sent message |
attachmentId | string | Reusable attachment ID |
senderAction | string | The sender action that was sent |
id | string | PSID of the looked-up person |
name | string | Full name |
firstName | string | First name |
lastName | string | Last name |
profilePic | string | Profile picture URL (expires) |
locale | string | Facebook locale |
timezone | number | Timezone offset from GMT |
gender | string | Gender |
profileAvailable | boolean | Whether Meta returned profile data |
conversations | json | Conversations (id, updatedTime, participants with id, name, email) |
messages | json | Messages, newest first (id, createdTime, text, from, to, attachments) |
nextCursor | string | Cursor for the next page |
hasMore | boolean | Whether another page is available |
A Trigger is a block that starts a workflow when an event happens in this service.
Trigger workflow when someone messages your Facebook Page on Messenger, taps a button or quick reply, reacts, reads, or arrives from an m.me link or ad
| Parameter | Type | Required | Description |
|---|
messengerVerifyToken | string | Yes | Enter the same string in the Verify Token field of the Messenger webhook in the Meta App Dashboard. |
messengerAppSecret | string | Yes | Used to check the X-Hub-Signature-256 header Meta signs every delivery with. Deliveries that do not match are rejected. |
messengerEventTypes | string | No | Run only for the selected events. Leave empty for everything except read receipts, which fire for every message the person reads. |
messengerIncludeEchoes | boolean | No | Also run for messages your Page sends (Meta marks them is_echo; subscribe to message_echoes). Off by default so a reply sent by this workflow does not trigger it again. |
messengerPageIds | string | No | Page IDs |
| Parameter | Type | Description |
|---|
eventType | string | message, postback, reaction, read, or referral |
pageId | string | Facebook Page ID that received the event |
senderPsid | string | Page-scoped ID (PSID) of the person. Pass it as the Recipient ID of a send operation. For echoes it is your Page ID. |
userRef | string | User ref instead of a PSID, sent for some plugin and Get Started postbacks before the person has a PSID |
recipientId | string | Recipient of the event: your Page ID, or the person for echoes |
text | string | Message text (the tapped quick reply title), or the title of the tapped postback button |
messageId | string | Message ID (mid) of the message or postback, or of the message reacted to |
attachments | json | Message attachments, each { type, url, title, stickerId } (image, audio, video, file, sticker, fallback, ...) |
quickReplyPayload | string | Payload of the tapped quick reply (the phone number or email for those quick replies) |
postbackPayload | string | Payload of the tapped postback button |
postbackTitle | string | Title of the tapped postback button |
referral | json | Referral from an m.me link, Click-to-Messenger ad, or Shops product page: { ref, source, type, adId, refererUri, adsContextData, productId } |
reaction | json | For reactions: { action: react | unreact, reaction, emoji } |
readWatermark | string | For read receipts: every message sent at or before this time (ms) was read |
isEcho | boolean | True when the message was sent by your Page (only with Include Sent Messages) |
timestamp | string | When the event happened (ISO 8601) |
raw | json | This event as Meta sent it: { sender, recipient, timestamp, message | postback | reaction | read | referral } |
events | json | Every matching event in this delivery (Meta can batch several), each with the fields above |
eventCount | number | Number of matching events in this delivery |
delivery | json | The whole webhook payload exactly as Meta sent it: { object, entry } |