It is possible to send messages to users using phone numbers they've associated with their Messenger accounts. As it is you who initiated the conversation, the user will receive your message as pending and will be asked to either confirm or decline your message.

Requirements

• 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.

How it works

To match a customer with a phone number the user has to have a phone number set in the Messenger profile. The customer decides whether he accepts or decline a messages you've sent. If your request is accepted you will receive an acknowledgment on the Opt-in webhook.

🚧

Customer Matching

Keep in mind that there might be people who haven't associated a phone number with Facebook Messenger account.

1. User receives request - push notification

2. User sees it as pending request in messenger

3. User accepts the request

4. User receives the message

Prerequisites

• Pay a 99 USD one time fee for Facebook page associated with your Messenger account. Payment has to be processed using payment card issued in USA (contact us at [email protected] if you need help with this).
• Your Facebook app must have pages_messaging_phone_number permission (only if you use Custom Facebook App).

📘

Contact us at [email protected] to help with the payment or any other setup needed.

Setup

1. Send Message

Sending message to Facebook Messenger is synchronous. Therefore, you will immediately see if the message was sent (HTTP response 201) or if the message could not be sent due to the fact that this phone number has no Facebook Messenger assigned (HTTP response 422). Note that the phone number in response is in E.164 format.

{
  "contact": {
    "phone_number": "+1 (555) 857-6309"
  },
  "channel": {...},
  "content": {...}
}

{
  "id": "...",
  "contact": {
    "id": "15234390803083474",
    "phone_number": "15558576309"
  },
  "channel": {...},
  "content": {...}
}

See API reference for full documentation.

🚧

Contact Id

Each existing contact has it's unique amio id. You can use this id to send any consequent messages, however phone number would work also.

2. Listen to Opt-in Webhook

Once a user has accepted your request, you will receive an opt-in webhook. This gives you higher permissions by Facebook policies so Amio gets user's details like name and gender for you. You can also use messages Tags to use broader range of different use cases to contact the user beyond subscription policies which are required when contacting the user using phone number.

{
  "event": "opt_in",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "channel": {
      "id": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "opt_in": {
      "type": "phone_number"
    }
  }
}

See Opt-in Webhook for full documentation.

3. Listen to Message Delivered Webhook

Keep in mind that Opt-in webhook is delivered only once when the user accepts the first message. Therefore, you should also listen to message delivered webhook in case you've already sent the message to this contact.

{
  "event": "messages_delivered",
  "timestamp" : "2016-10-06T13:42:48Z",
  "data" : {
    "channel": {
      "id": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "messages": [
      { "id": "6456078996108088196" }
    ],
    "delivered_timestamp": "2016-10-06T13:40:01Z"
  }
}

See Messages Delivered webhook for full documentation.