Try It – Send a Message with Messenger Platform

Learn how your business can send a message to a customer using the Messenger Platform.

You can use this tutorial to send a message from your app or, if you don't have a fully functional app or just want to explore, you can use our Graph API Explorer.

Before You Start

Requirements

To make a successful call to the Meta social graph to send a message, your app will need:

• The pages_show_list permission and a User access token, requested by you. This allows your app, or the Graph API Explorer, to get your Page ID.
• The pages_messaging permission and a Page access token, requested by a person who can perform the MESSAGING task on your Page, allows your app to get the conversation ID and your Page-scoped ID (PSID)

You can get access tokens 3 different ways:

• Facebook Login in your app
• The App Dashboard in Messenger > Settings
• The Graph API Explorer, (shown below)

Start a Conversation

Login to your Facebook account and send a message to your Page. This step will create a PSID for the customer that is specific for the Page, and a conversation ID representing the conversation between you and that Page.

Use Your App

If you have already subscribed to the messaging Webhooks, you can get the PSID, the conversation ID, and the message text from the Webhook notification, and move to Step 3.

Step 1. Get the IDs

You will need the ID for your Page, the PSID for the person who sent the message (you) and the conversation ID.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/me/accounts
    &access_token=USER-ACCESS-TOKEN"

{
  "data": [
    "access_token": "EAABkWcj...",    // PAGE-ACCESS-TOKEN
      "category": "Pet Service",
      "category_list": [
        {
          "id": "144982405562750",
          "name": "Pet Service"
        }
      ],
      "name": "Cisco Dog Page",
      "id": "4225...",                // PAGE-ID
      "tasks": [
        "ADVERTISE",
        "ANALYZE",
        "CREATE_CONTENT",
        "MESSAGING",
        "MODERATE",
        "MANAGE"
      ]
  ]
}

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?fields=participants
    &access_token=PAGE-ACCESS-TOKEN"

{
  "data": [
    {
      "participants": {
        "data": [
          {
            "name": "CUSTOMER-NAME",
            "email": "PSID@facebook.com",
            "id": "PSID"
          },
          {
            "name": "PAGE-NAME",
            "email": "PAGE-ID@facebook.com",
            "id": "PAGE-ID"
          }
        ]
      },
      "id": "t_10224..."   //Conversation ID
    }
  ]
}

You will need the Page ID, PSID and the Conversation ID for the following steps.

Step 2. Get the Message Text

To get a list messages within a conversation with the customer, send a GET request to the conversation ID endpoint with the messages{messages} field.

Sample Request

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/CONVERSATION-ID
    ?fields=messages{message}
    &access_token=PAGE-ACCESS-TOKEN"

Example Response

On success, your app will receive the following JSON response:

{
  "messages": {
    "data": [
      {
        "message": "This is a mesage to my Page",
        "id": "m_kHTNbg0O5..."  //Message ID
      }
    ]
  }
  "id": "t_10224..."   //Conversation ID
}

Step 3. Send the Customer a Message

To respond to the message a customer sent to your Page, send a POST request to /PAGE-ID/messages endpoint with the recipient parameter set to the customer's PSID, messaging_type parameter set to RESPONSE, and the message parameter set to your response. Note that this must be sent within 24 hours of your Page receiving the customer's message.

Sample Request

curl -i -X POST "https://graph.facebook.com/v14.0/PAGE-ID/messages
    ?recipient={id:PSID}
    &message={text:'You did it!'}
    &messaging_type=RESPONSE
    &access_token=PAGE-ACCESS-TOKEN"

On success, your app will receive the following JSON response:

{
  "recipient_id": "1008...",    // The customer's PSID
  "message_id": "m_AG5Hz2..."}  // The message ID

Use the Graph API Explorer Tool

If you have already subscribed to the messaging Webhooks, you can get the PSID, the conversation ID, and the message text from the Webhook notification, and move to Step 3.

Step 1. Get the IDs

You will need the ID for your Page, the Page-scoped ID (PSID) for the person who sent the message (you) and the conversation ID.

Open the Graph API Explorer in a new browser tab or window.

The explorer loads with a default query with the GET method, the lastest version of the Graph API, the /me node and the id and name fields in the Query String Field, and your Facebook App. If you would like to run this default query, you can click Generate Access Token then Submit. This query will create a User access token and return your name and User ID.

The me endpoint is a special endpoint that represents the ID for the User, Page, or App that is requesting the access token. In the following example, you will use a User access token in the request so me will represent your User ID. In Step 4, me will represent your Page since are using a Page access token.

To get the Page ID for your Page:

1. Replace the Query String Field string with either me/accounts or /USER-ID/accounts. If you ran the default query, you can click the ID in the response and it will automatically be moved to the Query String Field.
2. Go the Add a permission dropdown menu in the right side panel and select the pages_show_list permission then click Generate Access Token.
3. The popup window allows you to agree that the app can access the list of your Pages.
4. Click Submit to run the query.

Something Went Wrong

We're having trouble playing this video.

Learn more

To get the Conversation ID and the PSID:

1. Click the Page ID in the response to move it to the Query String Field and add /conversations?fields=participants to the query.
2. Go to the Add a Permission dropdown menu and select the pages_messaging permissionthen click Generate Access Token.
3. Another popup window will ask you to agree that the app can access the conversations of your Pages.
4. Click Submit to run the query.
5. Copy the PSID so you can paste in the next query.

Something Went Wrong

We're having trouble playing this video.

Learn more

Step 2. Get the Message Text

To get a list messages within a conversation with the customer:

1. Click the Conversation ID in the response to move it to the Query String Field and add /conversations?fields=messages{message} to the query.
2. Click Submit to run the query.

Something Went Wrong

We're having trouble playing this video.

Learn more

Step 3. Send the Customer a Message

To respond to the message the customer sent to your Page:

1. In the upper left, switch the method from GET to POST.
2. Delete the query string and replace it with the me and click Submit.
   This will give you the Page ID. You can continue with me in the query or click on the ID in the response to replace me with the ID in the query string.
3. In the Node Field Viewer to the left of the Response Window, click the + Add parameter under the Params tab. Add the following parameters and values:
   • recipient set to {id:PSID}
   • messaging_type set to RESPONSE
   • message set to {text:'Hello, new customer!'}
4. Click Submit.

Note that when using the RESPONSE message type, the message must be sent within 24 hours of your Page receiving the customer's message or an error will occur.

Something Went Wrong

We're having trouble playing this video.

Learn more

Next Steps

• Attach Media Assets to your Message
• Send a customer a message after the 24-hour messaging window
• Create a Message Template

Learn More

• Graph API
• Graph API Explorer Tool
• Page Access Tokens
• Page Permissions and Tasks
• Page/Messages Reference