OMNI channel: Push example

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

Parameters

Property name Type Description
from string PUSH Application Code you are using to send messages. Application Code is the application identifier which links your mobile application to the application profile created in Infobip Platform. It is required to insert the Application Code in Mobile Messaging SDK configuration once you implement it in your mobile application.
to object Recipient destination address.
text* string Text of the message that will be sent.
sendAt datetime Used for scheduled Push notifications. Message will be sent at scheduled time.
customPayload object Additional data that can be delivered with the Push message. customPayload must be formatted as JSON object.
notificationOptions object JSON object that contains notification options.
validityPeriod int The message validity period. Unless specified differently in validityPeriodTimeUnit, it is expressed in hours. When the period expires, it will not be allowed for the message to be sent or message will be canceled if it's pending in Cloud (APNS or GCM). Default value 48h. Minimum value is 30 sec. Maximum value is 72h.
notifyUrl string The URL on your callback server on which the Delivery report will be sent. Additional Information about Delivery reports on Notify URL.
notifyContentType string(application/json) Preferred Delivery report content type. Supported content types: application/json, application/xml.
callbackData string Additional client's data that will be sent on the notifyUrl. The maximum value is 200 characters.
targetOnlyPrimaryDevices boolean Set to true to only send messages to push devices which are marked as primary devices. By default, messages will be sent to all targeted devices, including both primary and non-primary.

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:

PUSH - SMS OMNI process

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

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.

Prerequisites

To be able to send PUSH messages using the Infobip platform please configure your PUSH application and your mobile application using Infobip PUSH SDK as described in the PUSH documentation.

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.

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:

{
  "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.

Info

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

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.

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:

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:

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.
showInApp no - Boolean Set to true to enable in app dialog for actionable message. Supported on iOS from 3.6.0. Supported on Android from 1.13.0.

Example with notification options:

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"
    },
    "targetOnlyPrimaryDevices": 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.

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":"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"
      }
   ]
}