Omni-Channel Messaging
Documentation /

Social Messaging -Facebook & WeChat User Guide

One unique value of the Syniverse CPaaS omni-channel solution is the ability for customers to engage their end-user across social media networks. Our service offers an engagement channel that allows customers to interact with their end users via Facebook Messenger and WeChat. For more details on how to programmatically integrate your application with our Social Messaging API, please refer to the Omni-Channel API Resource documentation.

Prerequisites

Social Messaging Messaging API requires the following items to be configured before the APIs can be used:

  •  An valid Account
  • Service Offering with a Syniverse application ( Credentials)

Related Services

Social Messaging messaging can be a standalone messaging channel or can be mashed up with the SMS service for fallback functionality. For relevant messaging and account events relating to the service, the Event Manager provides a callback service to receive event information about your contacts, messages status changes, or sender-id's

Using Facebook Messenger

To make use of this channel, customers have to setup a Facebook Sender ID using the following:

  • A valid Facebook account
  • Facebook page
  • An approved Application

You can create page at: https://www.facebook.com/pages/create/ and get some help (https://www.facebook.com/help/104002523024878 ).

You can create application here: https://developers.facebook.com/docs/apps/register

In general you can see an overview of Facebook Messenger at (https://developers.facebook.com/docs/messenger-pla... ).

Facebook Sender ID Setup Flow

  1. Create a Facebook page and an application
  2. Go to the application and from there click "+ Add Product".
  3. From the list on the right choose "Get started" on the line where it says "Messenger"

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {token}" -d '{ "name":"Facebook_Example_ABC", "class_id":"COMMERCIAL", "type_id":"FACEBOOK", "credentials":"{\"app_secret\":\"47fd493e6...\",\"page_access_token\":\"EAAZApvtqjZAMIB...\"}" }' "https://api.syniverse.com/scg-external-api/api/v1/messaging/sender_ids" ```

See example query below:

curl -X GET -H "Authorization: Bearer {token}" "https://api.syniverse.com/scg-external-api/api/v1/messaging/sender_ids/{SENDERID}"

Type a message in the Messenger field and send it.

curl -X GET -H "Authorization: Bearer {token}" "https://api.syniverse.com/scg-external-api/api/v1/messaging/messages/?sort=-created_date&limit=1"
    
curl -X POST -H "Authorization: Bearer {token}" -d '{"from":"{sender_id}","to":["fb:{fbuserID}@{SenderID.address}"],"body":"Hello!"}' https://api.syniverse.com/scg-external-api/api/v1/messaging/message_requests
  • To work as intended the gateway will need the following data for the Sender Address:
    • credentials/app_secret - This is the Application the Sender Address have created with the intention to use with Messenger API. It is required as to check the communication with Facebook. Take it from Dashboard > App Secret.
    • credentials/page_access_token - This is generated from Token Generation in your Application under Products / Messenger. It is required to send messages to the users. This can be retrieved from Messenger > "Token Generation" and then under Page, "Select a Page" choose your page and click on the generated token to get your Page Access Token
  • Using the app_secret and the page_access_token, create your SenderId. See example request below:
  • The response will return the newly created SenderID.
  • Now use the returned ID to retrieve the SenderID.
  • From the response you should get the value that is in the `address` field. You will use this value in a later step.
  • Next, setup a Webhook. On the Facebook application page, go to Messenger and click on Setup Webhooks.
  • The next step is to test the message. Facebook requires that an end-user initiates the conversation to a customer’s Facebook page.
  • Go to your Facebook Page and click Message
  • .
  • You can now check that you received a message using the Social Messaging API
  • You should see the message that you have sent earlier from Facebook.
  • Please take note of the `from_address` in the message as this is recipient address you will use when sending a message to the Facebook user. The Facebook recipient address format is: ["fb:{fbuserID}@{SenderID.address}"] where:
    1. fbuserID - Facebook unique ID for the end-user. This is specific to each Facebook page.
    2. SenderID address - This is the address field for the Sender ID associated with this Facebook page.
  • You can now send a message to the Facebook recipient.
  • Once you’ve completed integration with our Social Messaging API and tested your application with your page, ensure that your complete approval of your application and page with Facebook.

Working with Attachments in Facebook

Sending Attachments

You can send a Facebook message with attachments in the following ways:

  1. Binary attachment: Customer need to first create and upload the binary file using the Attachment Service and then send a message referring to that attachment.

Creating the Attachment:

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {token}" -d '{"filename":"some-file-name","name":"test","type":"image/png"}' "https://api.syniverse.com/scg-external-api/api/v1/messaging/attachments"

`{"id":"0GVzslvBOx2TOpd5CD1H15"}`.
    
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {token}" -d '{"resource":"ATTACHMENT","resource_id":"0GVzslvBOx2TOpd5CD1H15"}' "https://api.syniverse.com/scg-external-api/api/v1/access_tokens"
    
`{"id":"AaXyKN9Ptc6xiVfBMXWgb3"}`
    
curl -X POST -H 'Content-Type:application/octet-stream' -H "Authorization: Bearer {token}" -d @/home/user/myfilename.png "https://api.syniverse.com/scg-attachment/api/v1/messaging/attachments/AaXyKN9Ptc6xiVfBMXWgb3/content" ```
    
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {token}" -d '{"from":"{sender_id}","to":["fb:{fbuserID}@{SenderID.address}"],"body":"","attachments":["0GVzslvBOx2TOpd5CD1H15"]}' "https://api.syniverse.com/scg-external-api/api/v1/messaging/message_requests" ```
  1. You will receive in response a resource id like this:
  2. Now get the access token to the new resource:
  3. You will receive in response an access token like this:
  4. Upload data to the new resource:
  5. Send the message with an attachment:

Using a URL attachment with Facebook Messenger

Social messaging supports sending a message with a valid Content type and URL as a body.

The supported content types are:

  • "application/fb.message.image"
  • "application/fb.message.audio"
  • "application/fb.message.video"
  • "application/fb.message.file"

Example:

```bash curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {token}" -d '{"from":"{sender_id}","to":["fb:{fbuserID}@{SenderID.address}"],"body":"http://host.com/yin-yang.png","content_type":"application/fb.message.image"}' "https://api.syniverse.com/scg-external-api/api/v1/messaging/message_requests" ```

Template attachment

Customer can also send messages using one of the special Facebook message templates. https://developers.facebook.com/docs/messenger-platform/send-api-reference/generic-template)

Customer needs to indicate this in the message request by providing the content type:

  • "application/fb.message.template"

The provided body should be the Facebook message `payload` that includes the `template_type` and the `elements` array and is urlescaped stringified JSON.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {token}" -d '{"from":"{sender_id}","to":["fb:{fbuserID}@{SenderID.address}"],"body":"%7B%22template_type%22%3A%22generic%22%2C%22elements%22%3A%5B%7B%22title%22%3A%22Welcome%20to%20Peter'"'"'s%20Hats%22%2C%22image_url%22%3A%22http%3A%2F%2Fpetersapparel.parseapp.com%2Fimg%2Fitem100-thumb.png%22%2C%22subtitle%22%3A%22We've%20got%20the%20right%20hat%20for%20everyone.%22%2C%22buttons%22%3A%5B%7B%22type%22%3A%22web_url%22%2C%22url%22%3A%22https%3A%2F%2Fpetersapparel.parseapp.com%2Fview_item%3Fitem_id%3D100%22%2C%22title%22%3A%22View%20Website%22%7D%2C%7B%22type%22%3A%22postback%22%2C%22title%22%3A%22Start%20Chatting%22%2C%22payload%22%3A%22USER_DEFINED_PAYLOAD%22%7D%5D%7D%5D%7D","content_type":"application/fb.message.template"}' "https://api.syniverse.com/scg-external-api/api/v1/messaging/message_requests"

Receiving attachments on Facebook Page

When a user sends an attachment to your Facebook Page, the Social messaging service saves the received attachments from the messages in the Attachment Service.

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {token}" "https://api.syniverse.com/scg-external-api/api/v1/messaging/messages/?sort=-created_date&limit=50&message_delivery_provider=FACEBOOK"
    
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {token}" -d'{"resource":"ATTACHMENT","resource_id":"{AttachmentID}"}' "https://api.syniverse.com/scg-external-api/api/v1/access_tokens"
    
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {token}" "https://api.syniverse.com/scg-attachment/api/v1/messaging/attachments/{AccessToken}/content"
  1. To download the attachment, you will need to find the attachment id by listing your recent messages to retrieve the attachment ID.
  2. Find a message that includes an `attachments` array and grab one of the IDs.
  3. Next you will need to get an access token for that attachment:
  4. With the received access token you can now download the content of the attachment:

Using WeChat Messaging

To make use of this channel, customers have to have a WeChat official account and setup a Sender ID with the details of that account

  • Official WeChat Service account

Visit https://mp.weixin.qq.com for more information on creating a Service Account.

WeChat Sender ID Setup Flow

 bash curl --request POST -H "Authorization: Bearer [token}"  
 -H 'Content-Type: application/json' -d '{"name":"WC_TEST", "class_id":"COMMERCIAL","type_id":"WECHAT", 
"credentials":"{\"app_secret\":\"007584xfb629f64553dbx204906943xc\",\"app_id\": \"xxbfx403xx33d42x1x\",\"token\": \"unique_token\"}","address":"gh_53b23xy777"}' 
 https://api.syniverse.com/scg-external-api/api/v1/messaging/sender_ids
    
curl -X GET -H "Authorization: Bearer {token}" "https://api.syniverse.com/scg-external-api/api/v1/messaging/messages/?sort=-created_date&limit=1"
    
curl -X POST -H "Authorization: Bearer {token}" -d '{"from":"{sender_id}","to":["we:{WeChaUserID}@{SenderID.address}"],"body":"Hello!"}' https://api.syniverse.com/scg-external-api/api/v1/messaging/message_requests
  1. Login to the WeChat Web site for the WeChat official account.
  2. Go to "Basic Configuration."
  3. Now add or modify the server configuration to set the following values:
    1. URL - This should be set to "https://gateway3-scg-api.syniverse.com "
    2. Token - Enter any string as the secret token. This will be used during Sender ID creation.
  4. Submit the change.
  5. Now, retrieve the following values from this page.
    1. AppID - This is the WeChat Unique Id for your application. It will be used when creating the Server
    2. AppSecret - This is a key generated by WeChat.
  6. Go to Setup->No Public Settings.
  7. Retrieve the "Original ID" value.
  8. Using the AppID, AppSecret, token, and Original ID, create your SenderId. The Original ID value is used as the value for the "address" field in the Sender Id request.See example request below:
  9. The response will return the newly created SenderID.
  10. The next step is to test the message. WeChat requires that an end-user initiates the conversation to a customer’s WeChat service ID.
  11. Go to your WeChat App and search for your Service Account name and subscribe.
  12. Type a message in the Messenger field and send it.
  13. You can now check that you received a message using the Social Messaging API
  14. You should see the message that you have sent earlier from WeChat.
  15. Please take note of the `from_address` in the message as this is recipient address you will use when sending a message to the WeChat user. The WeChat recipient address format is: ["we:{WeChatUserID}@{SenderID.address}"] where:
    1. WeChatUserID - WeChat unique ID for the end-user. This is specific to each WeChat service.
    2. SenderID.address - This is the address field for the Sender ID associated with this WeChat service.
  16. You can now send a message to the WeChat recipient.

Copyright © 2023 Syniverse Technologies