Customer Matching

Closed Beta

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

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.



Customer Matching is available under closed beta, 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.

Customer Matching with the Send API

Customer Matching with the Send API allows you to send a message but instead of sending to a PSID, you specify a user's phone number and optionally their first and last name.

If a matching user is found and they have not previously 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.


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

Example Response

Breaking Change Notice

Effective February 20, 2018, the Send API no longer includes recipient_id in the response for message sends that use recipient.user_ref or recipient.phone_number to identify the message recipient.

  "message_id": "mid.$cAAJsujCd2ORj_1qmrFdzhVa-4cvO"

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"

Handling the User's Response

If the user responds to your message, the appropriate event (messages, messaging_postbacks, etc.) will be sent to your webhook, with a prior_message object appended. The prior_message object includes the source of the message the user is responding to, as well as the phone_number used for the original message send.

For example, the following messages event would be sent to your webhook if the user responded with a text message:

    "text":"Thanks for messaging me!"
  "prior_message": {

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.