Messenger Platform


Customer Matching

Customer Matching allows you to connect existing customers to your bot using their phone number, and optionally their name. You can perform a simple check with the Customer Matching API, or use the Customer Matching functionality in Send API to send a message to the matching user in Messenger.


  1. Availability
  2. Getting Access
  3. Customer Matching API (Closed Beta)
  4. Customer Matching with the Send API


Customer Matching is available only for bots that have a U.S.-based admin for their associated Facebook Page. The phone numbers used to match customers may belong to users in any country.

Getting Access

To gain access to the Customer Matching API and Customer Matching in the Send API, you must do the following:

  • Apply for the pages_messaging_phone_number permission when submitting your bot.
  • Pay a $99 USD fee with a U.S. credit or debit card.
  • Have a United States-based admin for the page your bot is attached to. This admin must make the payment for the fee mentioned above.

During the review process, the Messenger Platform team will ask for more information on how your customers' phone numbers were collected, and how you plan to use the feature.

Customer Matching API (Closed Beta)

The Customer Matching API allows you to check whether one of your customers is also a Messenger user. Customers are matched by sending their phone number, and optionally their name, to the API. Unlike using Customer Matching with the Send API, the Customer Matching API allows you to perform this check without attempting to send a message to the user.

Closed Beta

Access to the Customer Matching API is currently available in limited release for select businesses. To learn more, contact your Facebook partner manager or representative.

Using Customer Matching with the Send API is publicly available for bots that go through the approval process.

Customer Matching with the Send API

Customer Matching with the Send API allows you to send a message using the Send API, but instead of sending the message to a user ID, you can specify a user's phone number and optionally the user's name you have on file.

If a matching user is found, and if the user has not opted-in to your bot, a message request will be shown to the user inside Messenger. The user can then read the message and decide whether to accept. If the user accepts, you can onboard them to your bot's main experience.

Before you begin, please make sure you review and ensure your usage will comply with the usage requirements below. Also, please review the guidelines in Getting Access.


To use Customer Matching with the Send API, your usage must meet the following requirements:

  • The customer has agreed to allow you to send them messages.
  • The content sent using a phone number is non-promotional.
  • The content of messages sent complies with the same Platform Policies that apply for Subscription Messages.

For complete details on acceptable usage, see the Messenger Platform Policies.

Sending Messages with Customer Matching

Refer to the Send API Reference for more on how to pass a phone number and name when sending messages.

After you send the message, Messenger will attempt to match the phone number to a user. Many users bind their number when setting up an account, though a successful match will also require a high level of confidence that this number is still in-use for the given user. Passing an optional name when sending the message will increase the odds of a positive match.

Example Request

    curl -X POST -k -H "Content-Type: application/json"
      -d '{"recipient":{"phone_number":"+1 (555) 857-6309", "name":{"first_name":"Jenny", "last_name":"Doe"}}, "
      message":{"text":"Your package has arrived in Lobby 2."}}'

Reacting When the User Accepts the Message Request

Once a user has accepted your request and interacted with your bot, you no longer need to send messages using their phone number (though you can if you like). After this, your bot may send messages that comply with the Messenger Platform Policy, such as 24+1, templates, and Sponsored Messages, so long as they are not sent using a user's phone number.

After the users taps "Accept", you will receive an optin webhook event.

To distnguish it from other instances where this webhook might be called, the payload will include the following:

  "message_request": "accept"