Sending Messages

Many types of unstructured content can be sent with the Messenger Platform, including text, audio, images, video, and files.

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.

When required by applicable law, automated chat experiences must disclose that a person is interacting with an automated service

• at the beginning of any conversation or message thread,
• after a significant lapse of time, or
• when a chat moves from human interaction to automated experience.

Bots that serve the German market or German users should pay special attention to this requirement. Acceptable disclosures include but are not limited to: “I’m the [Page Name] bot,”“You are interacting with an automated experience,” “You are talking to a bot,” or “I am an automated chatbot.”

Contents

• Message Types
  • Standard Messaging
  • One-time Notification
  • Private Replies
  • Message Tags
  • News Messaging (beta)
  • Sponsored Messages
• Send API Basics
  • Content Types
  • Messaging Types
  • Recipient IDs
  • Batching Requests
• Sending Text
• Sending Attachments
  • Attachment Types
  • URL
  • File
  • Saved Assets (attachment_id)
• API Response
• Rate Limiting
• Best Practices

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 Page a message or starts a conversation via a web plug-in, your app has up to 24 hours to respond. Messages can be sent outside the 24-hour window for specific use cases with message tags.

One-time Notification

One-time Notification allows a Page to get a one message opt in from a person to send a follow-up message after 24-hour messaging window have ended.

Private Replies

When a person creates Post Comments or Visitor Posts on your Page then, Private Replies allows the Page to send a message on Messenger.

Message Tags

Message Tags enable businesses to send important and personally relevant 1:1 updates to users outside the 24 hour Standard messaging window for a set of approved use cases. For example, you may send updates about shipping and delivery, an upcoming reservation or flight, or alerts about a customer’s account.

News Messaging (beta)

News messages allow news publishers to send regular news updates to their subscribers in Messenger. This feature is only available for registered news Pages under the Facebook News Page Index (NPI)

Sponsored Messages

Sponsored messages allow you to reengage open conversation in Messenger outside the Standard Messaging window. Sponsored Messages appear like normal messages in the conversation but are marked 'Sponsored'.

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/v12.0/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!"
}

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.

Messaging Types

The messaging_type property identifies the messaging type of the message being sent, and is a more explicit way to messaging complies with policies for specific messaging types and respecting people's preferences.

The following values for 'messaging_type' are supported:

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 Page a message or interacts with your Page in Messenger 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.

• User Ref: Special case, used to reference the user in the context of the Checkbox Plugin.

• Post of Comment ID: Special case, used to reference the user in the context of Private Replies.

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/v12.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
    

Sending Attachments

The Messenger Platform allows you to attach assets to messages, including audio, video, images, and files. The maximum attachment size is 25 MB. The maximum resolution for images is 85 Megapixel. 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
• template. For more info on this type, see Templates

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/v12.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
  

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/v12.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"  
  

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:

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

API Response

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

{
  "recipient_id": "1008372609250235",
  "message_id": "m_AG5Hz2Uq7tuwNEhXfYYKj8mJEM_QPpz5jdCK48PnKAjSdjfipqxqMvK8ma6AC8fplwlqLP_5cgXIbu7I3rBN0P"
}

Rate Limiting

Page Rate limits are in place to prevent malicious behavior and poor user experiences. Messenger API calls beyond the rate limit below will fail with error code 613.

Since the rate limit is based on the Page audience, it is possible for the same app to hit the rate limit for one Page and not another. For easy debugging of the actual rate limit that applies to the page, see page_messages_total_messaging_connections

For pages with large audiences, we recommend a send rate of 250 requests per second. You should architect your system to distribute any sudden high amounts of load over time and are able to control your throughput should you hit our rate limits.

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

Attachments