Send API Reference

Send messages to users.

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

Request

The Graph API version should be set to 2.6 or greater.

When your app is in Development Mode, the Send API will only work for admins, developers and testers of the app. After your app is approved and public, it will work for the general public.

To send a message, make a POST request to https://graph.facebook.com/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN> with your page access token. The payload must be provided in JSON format as described below:

The Send API requires the pages_messaging permission.

Example

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient": {
    "id": "USER_ID"
  },
  "message": {
    "text": "hello, world!"
  }
}' "https://graph.facebook.com/v2.6/me/messages?access_token=PAGE_ACCESS_TOKEN"

Payload

Property Name Description Required

recipient

recipient object

Yes

message

message object

message or sender_action must be set

sender_action

Message state: typing_on, typing_off, mark_seen

message or sender_action must be set

notification_type

Push notification type: REGULAR, SILENT_PUSH, or NO_PUSH

No

  • message or sender_action must be set
  • notification_type details: REGULAR will emit a sound/vibration and a phone notification; SILENT_PUSH will just emit a phone notification, NO_PUSH will not emit either
  • notification_type is optional; by default, messages will be REGULAR push notification type

recipient object

Property Name Description Required

id

Page-scoped user ID of the recipient. This is the field most developers will commonly use to send messages.

phone_number or id must be set

phone_number

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.

phone_number or id must be set

name

If passing a phone number, also passing the user's name that you have on file will increase the odds of a successful match. Specify it as an object with the format:

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

optional

  • phone_number or id must be set

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 object

Property Name Description Required

text

Message text

text or attachment must be set

attachment

attachment object

text or attachment must be set

quick_replies

Array of quick_reply to be sent with messages

N

metadata

Custom string that is delivered as a message echo.

N

  • text or attachment must be set
  • text and attachment are mutually exclusive
  • text is used when sending a text message, must be UTF-8 and has a 640 character limit
  • attachment is used to send messages with images or Structured Messages
  • metadata has a 1000 character limit

attachment object

Property Name Description Required

type

Type of attachment, may be image, audio, video, file or template

Y

payload

Payload of attachment

Y

We support multiple types multimedia and templates attachments:

Attachment Reuse

You can optimize sending multimedia by reusing attachments. If you're sending the same attachments repeatedly, you should consider reusing them. Attachment reuse works with sending images, audio clips, videos and files.

Add the is_reusable flag and set it to true when calling the Send API with an attachment.

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient": {
    "id": "USER_ID"
  },
  "message": {
    "attachment": {
      "type": "image",
      "payload": {
      	"url": "https://petersapparel.parseapp.com/img/shirt.png",
        "is_reusable": true
      }
    }
  }
}' "https://graph.facebook.com/me/messages?access_token=PAGE_ACCESS_TOKEN"

The response will contain an attachment_id. Please note that this ID is private and only the page that originally sent the attachment can reuse it.

{
  "recipient_id": "USER_ID",
  "message_id": "mid.1473372944816:94f72b88c597657974",
  "attachment_id": "1745504518999123"
}

On subsequent calls to the Send API, use the attachment_id to send the same attachment. You can send an attachment to any user for a given page.

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient": {
    "id": "USER_ID"
  },
  "message": {
    "attachment": {
      "type": "image",
      "payload": {
        "attachment_id": "1745504518999123"
      }
    }
  }
}' "https://graph.facebook.com/me/messages?access_token=PAGE_ACCESS_TOKEN"

attachment object

Property Name Description Required

type

Type of reused attachment, may be image, audio, video, or file

Y

payload.attachment_id

ID of attachment

Y

Response

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

Example

{
  "recipient_id": "1008372609250235",
  "message_id": "mid.1456970487936:c34767dfe57ee6e339"
}

Fields

Property Name Description

recipient_id

Unique ID for the user

message_id

Unique ID for the message

Phone Number

See Also: Customer Matching Guide

If you know a user's phone number, your bot can send them a Message Request without requiring them to first interact with your page. To do this, send a message as usual, but specify a phone_number parameter.

When messages are sent to phone numbers, we will only send the message if we have a certain level of confidence of expected delivery. Passing an optional name attribute will increase the odds of a match with the required level of confidence being made.

If you find that during testing you cannot message your own phone number, re-verify it under Facebook user settings and wait 24 hours. At that point, you should be able to successfully send a message to your own phone.

Sending a message to phone numbers requires the pages_messaging_phone_number permission.

In order to use Customer Matching, the Page must have a United States address or have at least one admin who is in the United States. However, user phone numbers you are matching can be in any country.

Limits

Calls to the Send API

We support a high rate of calls to the Send API. However, you should architect your systems 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.