Messenger Platform

Send API Reference

The Send API is the main API used to send messages to users, including text, attachments, structured message templates, sender actions, and more.

Permissions

A page access token with pages_messaging permission is required to interact with this endpoint.

Apps in Development Mode, are restricted to message people that have a role in the app. Additionally Pages in unpublished status will only be allowed to message people with a role on the Page.

Contents

For error codes and their meanings, refer to this page.

Request URI

https://graph.facebook.com/v3.3/me/messages?access_token=<PAGE_ACCESS_TOKEN>

Example Request

curl -X POST -H "Content-Type: application/json" -d '{
  "messaging_type": "<MESSAGING_TYPE>",
  "recipient": {
    "id": "<PSID>"
  },
  "message": {
    "text": "hello, world!"
  }
}' "https://graph.facebook.com/v3.3/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

Properties

Property Type Description

messaging_type

String

The messaging type of the message being sent.


For supported types and more information, see Sending Messages - Messaging Types

recipient

Object

recipient object

message

Object

message object. Cannot be sent with sender_action.

sender_action

String

Message state to display to the user:

  • typing_on: display the typing bubble
  • typing_off: remove the typing bubble
  • mark_seen: display the confirmation icon

Cannot be sent with message. Must be sent as a separate request.


When using sender_action, recipient should be the only other property set in the request.

notification_type

String

Optional. Push notification type:

  • REGULAR: sound/vibration
  • SILENT_PUSH: on-screen notification only
  • NO_PUSH: no notification

Defaults to REGULAR.

tag

String

Optional. The message tag string. See Message Tags.

recipient

Description of the message recipient. All requests must include one of id, phone_number, or user_ref.

Property Type Description

recipient.id

String

Either PSID, phone_number, or user_ref of the message recipient.

recipient.phone_number

String

Optional. Phone number of the recipient with the format +1(212)555-2368.


Your bot must be approved for Customer Matching to send messages this way.

recipient.user_ref

String

Optional. user_ref from the checkbox plugin.

recipient.name

Object

Optional. Used only if phone_number is set. Specifies the person's name in the format:


{"first_name":"John", "last_name":"Doe"}

Providing a name increases the odds of a successful match.

The id must be an ID that was retrieved through the Messenger entry points or through the Messenger webhooks (e.g., a person may discover your business in Messenger and start a conversation from there.

These IDs are page-scoped IDs (PSID). This means that the IDs are unique for a given page.

If you have an existing Facebook Login integration, user IDs are app-scoped and will not work with the Messenger platform.

message

Property Type Description

text

String

Message text. Previews will not be shown for the URLs in this field. Use attachment instead. Must be UTF-8 and has a 2000 character limit. text or attachment must be set.

attachment

Object

attachment object. Previews the URL. Used to send messages with media or Structured Messages. text or attachment must be set.

quick_replies

Array<quick_reply>

Optional. Array of quick_reply to be sent with messages

metadata

String

Optional. Custom string that is delivered as a message echo. 1000 character limit.

attachment object

The following can be included in the attachment object:

Property Type Description

type

String

Type of attachment, may be image, audio, video, file or template. For assets, max file size is 25MB.

payload

Object

Payload of attachment

Response

A successful Send API request returns a JSON string containing identifiers for the message and its recipient.

Example

Breaking Change Notice

Effective February 20, 2018, the Send API no longer includes recipient_id in the response for message sends that use recipient.user_ref or recipient.phone_number to identify the message recipient.

{
  "recipient_id": "1254477777772919",
  "message_id": "AG5Hz2Uq7tuwNEhXfYYKj8mJEM_QPpz5jdCK48PnKAjSdjfipqxqMvK8ma6AC8fplwlqLP_5cgXIbu7I3rBN0P"
}

Properties

Property Name Description

recipient_id

Unique ID for the user

message_id

Unique ID for the message

Rate Limits

Messenger Platform supports a high rate of calls to the Send API.

However, you should architect your system such that you distribute any sudden high amounts of load over time and are able to control your throughput should you hit our rate limits.

Rate limits are in place to prevent malicious behavior and poor user experiences.

Be sure to catch any errors returned by the Send API including the one indicating that you've reached the rate limit.

High Volume Messages

When a Page experiences high volume of messages over a short period of time or is constantly sending or receiving messages with a large number of threads concurrently, it can trigger our system and change it into a high-MPS Page (messages per second). See Pages with High Volume Messages