Customer Matching

Customer Matching lets you connect existing customers to your bot using their phone number.

  1. How It Works
  2. What's New
  3. Getting Access
  4. Sending a Message
  5. Handling Webhook Postback

How it Works

With Customer Matching, you simply send a message using the Send API. But instead of sending it to a user ID, you can specify their phone number (and optionally the name you have on file for them).

After that, if the match was successful, and if the user has not opted in to your bot, it will appear as a message request inside Messenger. The user can read the message and decide whether to accept. When they do, you can onboard them to your bot's main experience.

What's New

In the Messenger Platform v1.4, we've made the following enhancements to this feature:

  • Can specify an optional name parameter when sending to increase odds of a successful match.

  • Developers now receive a webhook event when the user has accepted the message request, increasing the odds of a successful match.

Getting Access

Access to Customer Matching requires paying a $99 USD fee and applying for the pages_messaging_phone_number permission when submitting your bot.

In order to use Customer Matching, the page your bot is attached to must have a United States address or have at least one admin who is in the United States. However, the phone numbers passed may belong to users in any country.

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

Once approved, you will be able to send messages using phone number.

When sending these messages, however, you should also be aware that that the content of these messages is governed under the same Platform Policies that apply for Subscription Messages. We also require that the user has actually signed up with you in the past for SMS alerts. Be sure that any content sent using a phone number is non-promotional and respects the guidelines.

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 point, your bot may now send messages allowed under other areas of Messenger Platform Policy, such as 24+1, templates, and Sponsored Messages, so long as they are not sent using a user's phone number.

Sending Messages

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.

A complete request passing a phone number and name looks like this:

    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

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"