Send API Reference

The Send API is the main API used to send messages to users.

Contents

  1. Request
  2. Response
  3. Phone Number
  4. Limits

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

Request

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 for the pages_messaging permission 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:

Example

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

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

Payload

Property Name Required Description

recipient

Yes

recipient object

message

message or sender_action must be set

message object

sender_action

message or sender_action must be set

Message state:

  • typing_on
  • typing_off
  • mark_seen

notification_type

No

Push notification type:

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

Defaults to REGULAR.

tag

No

The message tag string. See Message Tags.

recipient object

Property Name Required Description

id

phone_number or id must be set

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

phone_number

phone_number or id must be set

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.

name

No

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"}

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 Required Description

text

text or attachment must be set

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

attachment

text or attachment must be set

attachment object. Previews the URL. Used to send messages with media or Structured Messages

quick_replies

No

Array of quick_reply to be sent with messages

metadata

No

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

attachment object

The following can be included in the attachment object:

Property Name Required Description

type

Y

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

payload

Y

Payload of attachment

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.

You can alternatively upload these attachments in advance using the Upload API.

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 Required Description

type

Y

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

payload.attachment_id

Y

ID of attachment

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

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.