Sending Messages

Breaking Change Notice - messaging_type Property Required (Effective May 7, 2018)


As of the release of Messenger Platform v2.2, we are requesting developers to include the messaging_type property in all message sends.

Beginning May 7, 2018, this property will be required for all message sends. After this date, message sends that do not include messaging_type will return an error and not be delivered.

For more information on the messaging_type property, see Messaging Types below.

Many types of unstructured content can be sent with the Messenger Platform, including text, audio, images, video, and files. You can also attach any supported asset type to a text message.

There are also a number of pre-defined message templates available that allow you to send structured messages for a richer experience. For more information, see Templates.

For a complete list of API calls and request properties, see the Send API Reference.

Contents

Message Types

To send messages to someone on Messenger, the conversation must be initiated by the user. Messages sent with the Messenger Platform are classified as one of three different message types. Each message type has different policies and guidelines for what types of content and under what conditions they can be sent.

The following is a brief overview of each message type. For more details, see the Messenger Platform Policy Overview.

  • Standard Messaging: When a person sends your bot a message or opts-in to receive messages via a web plug-in, your bot has up to 24 hours to respond. Your bot may send one additional message after the 24-hour time limit has expired. This is commonly referred to as the '24 + 1 policy'. Messages can be sent outside the 24-hour window for specific use cases with message tags.

  • Subscription Messaging: Allows you to send recurring messages for specific use cases that are not subject to the 24-hour standard messaging window. To send subscription messages, you must apply for the pages_messaging_subscriptions permission for your bot. If your bot has subscription messaging permission, users automatically opt-in to receive subscription messages when they start a conversation; however, it is highly recommended that your bot ask permission to send subscription messages to ensure a positive user experience.

  • Sponsored Messaging: A type of ad that sends a message directly to all conversations currently open with your bot or to a custom list of PSIDs that currently have open conversations with your bot. Sponsored Messages appear like normal messages in the conversation but are marked 'Sponsored'.

Content Types

The Messenger Platform supports sending many types of content in messages, including:

  • Text
  • Audio
  • Images
  • Video
  • Files

You can send all of these types of content as individual messages, or you can attach an asset, such as a image or file, to a text message.

Send API Basics

All messages are sent by submitting a POST request to the Send API with your page access token appended to the URL query string:

https://graph.facebook.com/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN>

The body of the HTTP request is sent in JSON format and requires three properties:

  • messaging_type: Identifies the purpose of the message send.
  • recipient: Identifies the intended recipient of the message.
  • message: Defines the message to be sent.

Here's a simple example of the body of a request to send a text message:

"messaging_type": "<MESSAGING_TYPE>"
"recipient":{
  "id":"<PSID>"
},
"message":{
  "text":"hello, world!"
}

Messaging Types

Breaking Change Notice

Beginning May 7, 2018 the messaging_type property will be required and all messages sent without it will not be delivered.

The messaging_type property identifies the messaging type of the message being sent, and is a more explicit way to ensure bots are complying with policies for specific messaging types and respecting people's preferences. The following values for 'messaging_type' are supported:

Messaging TypeDescription

RESPONSE

Message is in response to a received message. This includes promotional and non-promotional messages sent inside the 24-hour standard messaging window or under the 24+1 policy. For example, use this tag to respond if a person asks for a reservation confirmation or an status update.

UPDATE

Message is being sent proactively and is not in response to a received message. This includes promotional and non-promotional messages sent inside the the 24-hour standard messaging window or under the 24+1 policy.

MESSAGE_TAG

Message is non-promotional and is being sent outside the 24-hour standard messaging window with a message tag. The message must match the allowed use case for the tag.

NON_PROMOTIONAL_SUBSCRIPTION

Message is non-promotional, and is being sent under the subscription messaging policy by a bot with the pages_messaging_subscriptions permission.

Recipient IDs

Any time you send a message, you must identify the message recipient in the body of the request. The Messenger Platform supports two ways to identify message recipients:

  • Page-scoped ID (PSID): Any time someone sends your bot a message or interacts with your bot for the first time, the sender's page-scoped ID will be included in the sender.id property of the event. The PSID is unique for a given page. Please note that user ID's from Facebook Login integrations are app-scoped and will not work with the Messenger platform.

  • Phone number: If you know a user's phone number, you can specify recipient.phone_number in the API request. This will send a message request to the recipient, without requiring them to interact with your page first. Sending messages to phone numbers requires the pages_messaging_phone_number permission. For more information, see Customer Matching.

Batching Requests

The Graph API supports request batching, which allows you to send up to 50 messages with a single API request. Each request in a batch is counted toward the Send API rate limit. For more information, see Making Multiple Requests.

Sending Text

To send a basic text message, submit a POST request to the Send API, with message.text set in the request body:

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

For a complete list of API calls and request properties, see the Send API Reference.

Sending Attachments

The Messenger Platform allows you to attach assets to messages, including audio, video, images, and files. There are three ways to attach an asset to a message:

  • URL
  • File
  • attachment_id

Attachment Types

The Messenger Platform supports the following attachment types, specified in the attachment.type property of the message:

  • audio
  • video
  • image
  • file

Attaching from URL

To send an attachment from a URL, submit a POST request to the Send API, with message.attachment set in the request body. The attachment object includes the asset type (image, audio, video, or file), and a payload that includes the asset url:

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{
    "id":"1254459154682919"
  },
  "message":{
    "attachment":{
      "type":"image", 
      "payload":{
        "url":"http://www.messenger-rocks.com/image.jpg", 
        "is_reusable":true
      }
    }
  }
}' "https://graph.facebook.com/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

For a complete list of API calls and request properties, see the Send API Reference.

Attaching from File

To send an attachment from file, submit a POST request to the Send API with the message details as form data, with the following fields:

  • recipient: A JSON object identifying the message recipient.
  • message: A JSON object describing the message. Includes the asset type, and a payload. The payload is either empty, or sets the is_reusable property.
  • filedata:The location of the asset on your file system and MIME type.
curl  \
  -F 'recipient={"id":"<PSID>"}' \
  -F 'message={"attachment":{"type":"<ASSET_TYPE>", "payload":{"is_reusable"=true}}}' \
  -F 'filedata=@/tmp/shirt.png;type=image/png' \
  "https://graph.facebook.com/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

For a complete list of API calls and request properties, see the Send API Reference.

Attaching Saved Assets

The Messenger Platform supports saving assets via the Send API and Attachment Upload API. This allows you reuse assets, rather than uploading them every time they are needed. For information on saving assets, see Saving Assets.

To attach a saved asset to a message, specify the attachment_id of the asset in the payload.attachment_id property of the message request:

Only attachments that were uploaded with the is_reusable property set to true can be sent to other message recipients.

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

For a complete list of API calls and request properties, see the Send API Reference.

API Response

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

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

Rate Limiting

The 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.

Best Practices

Text Messages

Keep it short. Consider screen size and scrolling behavior; compact messages are easier for people to follow. Try sending a few separate messages instead of one long one.

Don't use text as a substitute for images, tables, charts, and images. Structured messages or even a webview might suit your needs better.

Don't write lengthy exchanges. If you need to communicate multiple things, try sending a few separate messages instead of one long one.

Attachments

Pay attention to quality. Use colorful images with high resolution to make your messages stand out.

Consider aspect ratio. Review how your image may get cropped when it appears in the message bubble.

Don't put large amounts of text in your image. Use a text message instead, or combine images and text with a generic template.