Sending and receiving Facebook Messenger Messages

For a Business or its clients looking to consume Facebook Messenger service, Syniverse provides access through its SCG APIs that allows Businesses to provide communication services between their application and a Facebook Messenger user. The SCG APIs provides access to Facebook Messenger’s service that includes the ability to trigger Standard messages that includes sending and receiving 2- way (MO/MT) messages with the following content type - Text, Audio, Images, Video and Files. Currently Syniverse’s SCG API does not support Message Tags, Sponsored messages or one-time notification message, we hope to bring this functionalities in the near future. The initial Facebook messenger uses will be limited to Standard messaging.

Standard Messaging - Businesses will have up to 24-hours to respond to a user. Messages sent within the 24-hour window may contain promotional content. We know people expect businesses to respond quickly, and businesses that respond to users in a timely manner achieve better outcomes. We highly encourage businesses to respond to people’s messages as soon as possible.

 

Sending and receiving a Facebook messenger message

Businesses are encouraged to make sure their applications outline how users can engage with them including making sure user’s consent is captured and how to they opt out of receiving messages from the business.

On the Syniverse CPaaS platform, Businesses have 2 ways of engaging FB messenger users, this article explores using the Omni-channel API

Engagement using the Omni-channel API

Prior to being able to use the Omni-channel API for Facebook, customers need to have already created a valid Sender ID for their application. If you need to learn how to do this, please see the article here. Also if you are not yet familiar with our API, please see the API reference guide for details.

As outlined in Facebook’s policy, the user needs to initiate the engagement before a Business can response/engage with the user. Once the end-user sends a message to your account, the 24-hr window will open and you will be able to capture the user’s details that is needed to construct the recipient’s address. This message is called MO (Mobile originated) message.

Sample MO (Receiving a message from a user):

When the user engages your application, a message is sent to your webhook with details like this:

{
"topic": "SCG-Message",
"attempt": 1,
"event": {
   "fld-val-list": {
     "sender_id_alias": "wBhtqqR2CDgd9N9g5oQ3K4",
     "mo_price": 0,
     "company-id": 15xx,
     "sender_id_id": "wBhtqqR2CDgd9N9g5oQ3K4",
     "message_body": "Hello, I need some information",
     "message_id": "UtsRp215RjT36op5FYuap",
      "to_address": "238580349506269",
     "has_attachment": false,
      "from_address": "1108648785921067",
     "application_id": 1700
   },
   "evt-tp": "mo_message_received",
   "timestamp": "2021-01-17T20:43:52.013Z"
},
"event-id": "nS2RUcJtSA6JaxN8RxcvCA"
}

 

Using the information from the event posted to your application, you can construct the recipients address so that you can respond to the user.

Recipient address is a unique id that includes both your Facebook sender address (this is the address associated with the sender id) and the user’s Facebook user ID. Please note that the user’s “fb-user-id” is a unique ID generated by the Facebook messenger service and should not be confused with the standard Facebook ID.

Format: fb:<fb-user-id>@<facebook sender address>

Using the example above,

  • Fb-user-id: 1108648785921067
  • Facebook sender address: 238580349506269

Recipient address: “fb:1108648785921067@238580349506269

 

Sending a Facebook Messenger message (responding to a user)

Within the 24-hour window triggered by receiving a message from a user, Business can send a messenger message (Mobile Originated) to the user using the recipient address above.

Sample MT:

POST 'https://api.syniverse.com/scg-external-api/api/v1/messaging/messages' -H 'Authorization: Bearer {Token} -H 'Content-Type: application/json
'{
   "from": "wBhtqqR2CDgd9N9g5oQ3K4",
   "to": "fb:1108648785921067@238580349506269",
   "body": "Thanks for contacting us, how can we help you?"
}'

 

Sample event (Delivery Receipt)

{
"topic": "SCG-Message",
"attempt": 1,
"event": {
   "fld-val-list": {
     "previous_state": "QUEUED",
     "message_request_id": "NOP2aI65kw0IU7w6lLB8G5",
     "message_id": "NOP2aI65kw0IU7w6lLB8G5",
      "to_address": "fb:1108648785921067@238580349506269",
     "has_attachment": false,
     "reason_description": "SUCCESS",
     "application_id": 1714,
     "reason_code": "200",
     "sender_id_alias": "wBhtqqR2CDgd9N9g5oQ3K4",
     "company-id": 15xx,
     "sender_id_id": "wBhtqqR2CDgd9N9g5oQ3K4",
     "external_message_request_id": "",
     "new_state": "SENT",
     "fragments_count": 1,
     "from_address": "238580349506269",
     "mt_price": 0
   },
   "evt-tp": "message_state_change",
   "timestamp": "2021-01-17T21:06:49.473Z"
},
"event-id": "jXBTsXVAQoKYCU7MkOv15g"
}

 

Sending Facebook Messenger Rich media message to a user

The API also allows Businesses to engage user rich media using specific content types. (Audio, video, File, text). The max size of each content can be no more than 5MB.

Syniverse provides 2 methods for you to submit rich media using our APIs.

  • Attachment: Create and store an attachment
  • Media URL: Include a URL with link to the content.

Send a Rich media using attachment services.

Create an attachment programmatically by uploading you content to our service.

  1. Create an attachment resource:
POST 'https://api.syniverse.com/scg-external-api/api/v1/messaging/attachments' -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'Authorization: Bearer {Token}
'{
                 "name": "My Test content",
                 "type": "image/png",
                 "filename": "mycontent.png"
}'

Response:

{
   "id": "AkBjs0EcBKCeaQBAxcebk"
}

Please note take note of your attachment Id {AkBjs0EcBKCeaQBAxcebk}

 

  1. Get Access Token for the attachment:

Using the response ID received from the attachment resource created;

 

POST 'https://api.syniverse.com/scg-external-api/api/v1/messaging/attachments/AkBjs0EcBKCeaQBAxcebk/access_tokens' -H 'Authorization: Bearer {Token}-H 'Content-Type: application/json'
'{
   "expiry_time": "2021-01-20T00:00:00.000Z"
 }'

 

Response:

{
   "id": "is07C418dw1e5xSeli6Cz1"
}

 

  1. Upload your content to the attachment service:

Using the response/token generated in Step 2, upload your content

POST 'https://api.syniverse.com/scg-attachment/api/v1/messaging/attachments/is07C418dw1e5xSeli6Cz1/content' -H 'Content-Type: application/octet-stream' -H 'Authorization: Bearer {Token}--data-binary '@/C:/Users/Kola/OneDrive - Syniverse/Pictures/mycontent.png'

 

Now you are ready to send a Rich media message using the attachment (attachment ID = AkBjs0EcBKCeaQBAxcebk) you just uploaded.

Sample Request:

POST 'https://api.syniverse.com/scg-external-api/api/v1/messaging/messages' -H 'Authorization: Bearer {Token} -H 'Content-Type: application/json

'{
   "from": " wBhtqqR2CDgd9N9g5oQ3K4",
   "to": "fb:1108648785921067@238580349506269",
   "attachments":[" AkBjs0EcBKCeaQBAxcebk "]
   "body": " Thanks for contacting us, here is a copy of the information you requested"
}'

Sample event (Delivery receipt)

{

"topic": "SCG-Message",
"attempt": 1,
"event": {
   "fld-val-list": {
     "attachment_ids": "AkBjs0EcBKCeaQBAxcebk",
     "previous_state": "QUEUED",
     "message_request_id": "rh9h1Nm6ioJMwMrO8oxBz2",
     "message_id": "rh9h1Nm6ioJMwMrO8oxBz2",
     "to_address": "fb:1108648785921067@238580349506269",
     "has_attachment": true,
     "reason_description": "SUCCESS",
     "application_id": 1764,
     "reason_code": "200",
     "sender_id_alias": "wBhtqqR2CDgd9N9g5oQ3K4",
     "company-id": 15xx,
     "sender_id_id": "wBhtqqR2CDgd9N9g5oQ3K4",
     "external_message_request_id": "",
     "new_state": "SENT",
     "fragments_count": 1,
     "from_address": "238580349506269",
     "mt_price": 0
    },

   "evt-tp": "message_state_change",
   "timestamp": "2021-01-17T22:21:48.522Z"
},
"event-id": "dOYWtfwyRQKBA1susMMnDQ"
}

 

Send a Rich media using Media URL

POST 'https://api.syniverse.com/scg-external-api/api/v1/messaging/messages' -H 'Authorization: Bearer {Token} -H 'Content-Type: application/json
'{
   "from": " wBhtqqR2CDgd9N9g5oQ3K4",
   "to": "fb:1108648785921067@238580349506269",
   "media_urls":["https://drive.google.com/uc?id=1CQmMNHGIcPT-tiiNNMTCf2KbSFkVo4-1"]
   "body": "Thanks for contacting us, here is a copy of the information you requested"
}

 

 

Was this article helpful?
0 out of 0 found this helpful

0 Comments

Article is closed for comments.