OMNI channel: Push example

In the following examples, we’ll show you how to configure the PUSH-SMS failover scenario, send your first messages and retrieve message reports. There are three easy steps to follow:

1. Create 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 the channel and from, respectively identifying the communication channels and senders for each communication channel.

For PUSH sender (“channel”: “PUSH” flow) you should use the Application Code created during the setup of the PUSH application, as described in the Create PUSH application.

Below is an example showing how to create a scenario with PUSH and SMS steps and the order of those steps in the scenario flow. In the following example the PUSH applicationCode is 233623e3c860b49ec69a464834343481-8bj4el4a-256d-23fd-56ad-b5bc3d568b53.

• JSON

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

{
  "name":"My PUSH-SMS scenario",
  "flow": [
    {
      "from": "233623e3c860b49ec69a464834343481-8bj4el4a-256d-23fd-56ad-b5bc3d568b53",
      "channel": "PUSH"
    },
    {
      "from": "InfoSMS",
      "channel": "SMS"
    }    
  ],
  "default": true
}	
  

Response:

• JSON

{
  "key": "AD9E01A5DC7BEE2C2B828D208182A611",
  "name":"My PUSH-SMS scenario",
  "flow": [
    {
      "from": "233623e3c860b49ec69a464834343481-8bj4el4a-256d-23fd-56ad-b5bc3d568b53",
      "channel": "PUSH"
    },
    {
      "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 message.

2. Send OMNI 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 PUSH and SMS communication channels. First, the PUSH message will be sent to the defined phoneNumber. If for some reason the message is rejected in the PUSH application, the message will be sent using the SMS communication channel.

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 channel, as shown below.

• JSON

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

{ 
  "scenarioKey":"AD9E01A5DC7BEE2C2B828D208182A611",  
  "destinations":[ 
  	{ 
    	"to":{
        "phoneNumber": "41793026727"
      }
    }
  ],
  "push": {
  	"text": "This PUSH message will pop up on your mobile device."
  },
  "sms": {
  	"text": "This is the SMS failover message"
  }
}	
  

Response:

• JSON

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

{   
    "messages":[   
       {   
            "to":{
              "phoneNumber": "41793026731"
            },
            "status": {
                "groupId": 1,
                "groupName": "PENDING",
                "id": 7,
                "name": "PENDING_ENROUTE",
                "description": "Message sent to next instance"
            },
            "messageId": "7046974d-68cd-4648-a4ec-53a73a6b4ae2"
        }
    ]
}	
  

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.

OMNI PUSH message with a custom payload

OMNI also supports PUSH custom payload objects. Custom payload is additional custom data included in the request and delivered with the PUSH message.

Custom payload request example:

• JSON

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

{
  "scenarioKey":"AD9E01A5DC7BEE2C2B828D208182A611",
  "destinations":[
    {
      "to":{
        "phoneNumber": "41793026727"
      }
    }
  ],
  "push": {
    "text": "This PUSH message will pop up on your mobile device.",
    "customPayload": {
      "contentUrl": "https://someurl.com/content",
      "deepLink": "myApp://some/link"
    }
  },
  "sms": {
    "text": "This is the SMS failover message"
  }
}	
  

Notification options

You may choose different options on how to alert the user when PUSH message is received.

Name	Required	Default	Type	Description
vibrationEnabled	no	true	boolean	Notification vibration (Android only).
soundEnabled	no	true	boolean	Sound when notification arrives on a device.
soundName	no	-	String	Name of the custom sound played when notification arrives on a device. File should be located in the app with max 30 seconds length. File extension is required for iOS and optional for Android. For custom sound to be played soundEnabled shouldn’t be false (Example: notification_sound.wav). Check Android and iOS usage details.
badge	no	true	integer	Badge counter (iOS only).
contentUrl	no	-	string	URL of the image displayed in the notification. Rich push notifications are available on devices with iOS 10 and Android 4.1.+. Supported on iOS since MM SDK version 2.5.8. Supported on Android since MM SDK version 1.6.4.
category	no	-	string	Category id for actionable notification. Supported on Android since MM SDK version 1.6.16. Supported on iOS since MM SDK version 2.6.9. Predefined category ids: mm_accept_decline - Accept & Decline button actions.
inAppStyle	no	-	string	Possible values: MODAL, BANNER. Set to MODAL to use in app dialog for actionable message, or BANNER to show a standard banner view. MODAL is supported on iOS from 3.6.0, on Android from 1.13.0 and on Cordova from 0.7.0. BANNER is supported from iOS 5.0.0, Android 2.0.0 and Cordova 1.0.0
isSilent	no	-	boolean	Set to true to send silent push message. Such messages aren’t displayed on device lock screen and in the notification center. Silent messages can be used to deliver custom data to your mobile application or to trigger an in-app notification.
title	no	Application name set within mobile project	string	Notification title displayed within notification. Requires iOS 10+ or Android 4.1+ (may depend on Android custom firmware)

Example with notification options:

• JSON

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

{
  "scenarioKey": "AD9E01A5DC7BEE2C2B828D208182A611",
  "destinations": [
    {
      "to": {
        "phoneNumber": "41793026727"
      }
    }
  ],
  "push": {
    "text": "This PUSH message will pop up on your mobile device.",
    "customPayload": {
      "contentUrl": "https://someurl.com/content",
      "deepLink": "myApp://some/link"
    },
    "notificationOptions": {
      "vibrationEnabled": true,
      "soundEnabled": true,
      "soundName": "sound.wav",
      "badge": 1,
      "contentUrl": "http://www.mydomain.com/images/image1.jpg",
      "category": "mm_accept_decline",
      "inAppStyle": "MODAL",
      "title": "This is some title"
    },
    "targetOnlyPrimaryDevices": true,
    "includeNotificationsDisabledDevices": true
  },
  "sms": {
    "text": "This is the SMS failover message"
  }
}	
  

3. Get Delivery Reports

Once you’ve successfully sent your message using the advanced API method you can 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.

• JSON

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.

• JSON

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

{  
   "results":[  
      {  
         "messageId":"07e03aae-fabc-44ad-b1ce-222e14094d70",
         "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": "PUSH"
      },
      {  
         "messageId":"1f21d8d7-f306-4f53-9f6e-eddfce9849ea",
         "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"
      }
   ]
}