OMNI channel: Facebook example

Read about the simple methods which will allow you to send messages and retrieve message reports using the Facebook and SMS communication channels.

Prerequisites

To be able to send Facebook messages using the Infobip platform you need to have the Facebook service configured. Please follow the detailed instructions for service activation and configuration.

In the following examples we’ll show you how to configure the Facebook Messenger - SMS OMNI failover scenario, send your first messages and retrieve message reports.

There are three easy steps to follow:

Facebook Messenger - SMS OMNI process

  1. Create an OMNI Scenario
  2. Send a message using an OMNI scenario
  3. Get Delivery Reports

Available methods:

Create an OMNI scenario

The first step is to create an OMNI scenario. In the OMNI scenario configuration, you need to define the OMNI steps which will be sequentially executed. The key parameters are channel and from, respectively identifying the communication channels and senders for each communication channel.

For Facebook sender (“channel”: “FACEBOOK” flow) you should use the Facebook application key obtained during the Facebook channel activation process.

POST /omni/1/scenarios HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
  "name":"My first Facebook-SMS scenario",
  "flow": [
    {
      "from": "FacebookApplicationKey",
      "channel": "FACEBOOK"
    },
    {
      "from": "InfoSMS",
      "channel": "SMS"
    }    
  ],
  "default": true
}	
  

Response:

{
  "key": "12CD1116DC7B451B2B7286412482CCC1",
  "name":"My first Facebook-SMS scenario",
  "flow": [
    {
      "from": "FacebookApplicationKey",
      "channel": "FACEBOOK"
    },
    {
      "from": "InfoSMS",
      "channel": "SMS"
    }    
  ],
  "default": true
}	
  

If successful, the response header HTTP status code will be 200 OK and the scenario will be created, as shown in the example bellow. If you try to create the scenario without authorization, you will receive a 401 Unauthorized error.

The key parameter needs to be stored as it will be used when sending the OMNI message.

Info

More information about creating an OMNI scenario can be found at the following page: Scenario:// Create.

Send an OMNI text message

Once you’ve created an OMNI scenario (identified by the key parameter) as described in the previous chapter, you are ready to send your OMNI messages through defined Facebook and SMS communication channels. Firstly, the Facebook message will be sent to the defined phoneNumber. If for some reason the message is rejected on the Facebook platform, the message will be sent using the SMS communication channel.

Facebook messenger phone number

In order to send messages to Facebook Messenger users using the phone number, certain guidelines provided by Facebook must be followed. Please check the detailed Facebook guidelines

For sending OMNI messages, you can use the advanced API method. Detailed descriptions about the advanced API method can be found here: OMNI:// Send the advanced message.

The parameters that should be set are the scenario key, phoneNumber and specific text for each communication channels, as shown below.

POST /omni/1/advanced HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{ 
	"scenarioKey":"CC9F01A5DC7BEE2C2B829D203482A654",  
  "destinations":[ 
  	{ 
    	"to":{
        "phoneNumber": "41793026727"
      }
    }
  ],
  "facebook": {
  	"text": "This Facebook message will be delivered both to the Facebook user page and Facebook messenger."
  },
  "sms": {
  	"text": "This is the SMS failover message"
  }
}	
  

Response:

{   
    "messages":[   
       {   
            "to":{
              "phoneNumber": "41793026731"
            },
            "status": {
                "groupId": 1,
                "groupName": "PENDING",
                "id": 7,
                "name": "PENDING_ENROUTE",
                "description": "Message sent to next instance"
            },
            "messageId": "2601aea7-3646-4d98-b1b6-163bcaf7dd86"
        }
    ]
}	
  

If successful, the response header HTTP status code will be 200 OK and the message will be sent. If you try to send the message without authorization, you will receive a 401 Unauthorized error.

Send OMNI message by using Facebook user key

The phone number is not the only way to identify the recipient of the message. In some cases, your user may be using one phone number for receiving SMS messages and another one for registering on Facebook. If this is the case, specifying one recipient phone number is not enough.

This is where the facebookUserKey comes in handy. If the Facebook User Key is specified, it will be used as the primary destination address for the Facebook message. The phoneNumber will be used only as the SMS destination.

Facebook User Key

Each registered application user has a unique ‘key’ which can be used as the Facebook messenger destination address. Learn how to access your user keys in the User documentation.

Request example:

POST /omni/1/advanced HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{ 
	"scenarioKey":"CC9F01A5DC7BEE2C2B829D203482A654",  
  "destinations":[ 
  	{ 
    	"to":{
        "phoneNumber": "41793026727",
        "facebookUserKey": "9c29bd43-054b-4cfe-a1d4-0b37812b4ed3"
      }
    }
  ],
  "facebook": {
  	"text": "This Facebook message will be delivered both to the Facebook user page and Facebook messenger."
  },
  "sms": {
  	"text": "This is the SMS failover message"
  }
}	
  

Response:

{   
    "messages":[   
       {   
            "to":{
              "phoneNumber": "41793026731",
              "facebookUserKey": "9c29bd43-054b-4cfe-a1d4-0b37812b4ed3"
            },
            "status": {
                "groupId": 1,
                "groupName": "PENDING",
                "id": 7,
                "name": "PENDING_ENROUTE",
                "description": "Message sent to next instance"
            },
            "messageId": "2601aea7-3646-4d98-b1b6-163bcaf7dd86"
        }
    ]
}	
  

Send a rich OMNI message

Besides the text message, a media file can also be sent over API. Before sending the message, you will need to upload your media to a publicly accessible server and supply the url of the file.

According to the supplied file type, Facebook will attempt to render a media preview inside of the client chat application.

Supported media types are: IMAGE, AUDIO, VIDEO and FILE.

If type is defined, url of the file must also be included in the request.

Image request example:

POST /omni/1/advanced HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{ 
	"scenarioKey":"CC9F01A5DC7BEE2C2B829D203482A654",  
  "destinations":[ 
  	{ 
    	"to":{
        "phoneNumber": "41793026727"
      }
    }
  ],
  "facebook": {
    "type": "IMAGE",
    "url": "https://somedomain.com/images/image.jpg"
  },
  "sms": {
  	"text": "This is the SMS failover message"
  }
}	
  

Response:

{   
    "messages":[   
       {   
            "to":{
              "phoneNumber": "41793026731"
            },
            "status": {
                "groupId": 1,
                "groupName": "PENDING",
                "id": 7,
                "name": "PENDING_ENROUTE",
                "description": "Message sent to next instance"
            },
            "messageId": "2601aea7-3646-4d98-b1b6-163bcaf7dd86"
        }
    ]
}	
  

Get Delivery Reports

Once you’ve successfully sent your message using the advanced API method, you’ll be able to check the status of sent messages using the OMNI reports method.

The simplest way is to use the method without any query parameters. In that case, the response will contain all messages sent to a specific account.

GET /omni/1/reports HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json	
  

The response will contain all messages, rejected and delivered, as shown in the example below.

HTTP/1.1 200 OK
Content-Type: application/json

{  
   "results":[  
      {  
         "messageId":"1215f543ab19-345f-adbd-12ad31451ed25f35",
         "to":"41793026731",
         "messageCount": 1,
         "sentAt":"2016-02-23T17:41:11.833+0100",
         "doneAt":"2016-02-23T17:41:11.843+0100",
         "mccMnc":"22801",
         "price":{  
            "pricePerMessage":0.0104,
            "currency":"EUR"
         },
         "status":{  
            "groupId":2,
            "groupName":"UNDELIVERABLE",
            "id":9,
            "name":"UNDELIVERABLE_NOT_DELIVERED",
            "description":"Message sent not delivered"
         },
         "error":{  
            "groupId":1,
            "groupName":"HANDSET_ERRORS",
            "id":6,
            "name":"EC_ABSENT_SUBSCRIBER_SM",
            "description":"Absent Subscriber",
            "permanent":false
         },
        "channel": "FACEBOOK"
      },
      {  
         "messageId":"2315d543441c-335f-1d3d-142d31451ed25f35",
         "to":"41793026731",
         "sentAt":"2016-06-23T17:40:31.773+0100",
         "doneAt":"2016-06-23T17:40:31.787+0100",
         "messageCount":1,
         "mccMnc":"22801",
         "price":{  
            "pricePerMessage":0.01,
            "currency":"EUR"
         },
         "status":{  
            "groupId":3,
            "groupName":"DELIVERED",
            "id":5,
            "name":"DELIVERED_TO_HANDSET",
            "description":"Message delivered to handset"
         },
         "error":{  
            "groupId":0,
            "groupName":"OK",
            "id":0,
            "name":"NO_ERROR",
            "description":"No Error",
            "permanent":false
         },
        "channel": "SMS"
      }
   ]
}