OMNI channel: VK example

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

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

The messages will first be sent over VK communication channel. If the messages are rejected on VK (for example, the user doesn’t have VK installed or the user was not online in VK for longer than 6 days), the messages will be sent using the SMS communication channel. For each communication channel, a specific validity period can be set.

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.

Prerequisites

To be able to send VK messages using the Infobip platform you need to configure the VK service. Please contact us for service activation and configuration.

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

{
  "name":"My VK-SMS scenario",
  "flow": [
    {
      "from":"InfoVK",
      "channel": "VKONTAKTE"
    },
    {
      "from": "InfoSMS",
      "channel": "SMS"
    }    
  ],
  "default": true
}	
  

Response format

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.

{
  "key": "CC9F01A5DC7BEE2C2B829D203482A654",
  "name":"My VK-SMS scenario",
  "flow": [
    {
      "from": "InfoVK",
      "channel": "VKONTAKTE"
    },
    {
      "from": "InfoSMS",
      "channel": "SMS"
    }    
  ],
  "default": true
}	
  

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

Info

You can find more information about creating an OMNI scenario at: 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 VK and SMS communication channels. First, the VK message will be sent to the defined phoneNumber. If, for some reason, the message is rejected on the VK or the end user doesn’t have the VK application installed, 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 an advanced message.

The parameters that should be set are the scenario key, phoneNumber, templateName and templateData (JSON object where the keys are names of parameters in the template) text for the SMS failover as shown below.

TEMPLATE REGISTRATION

During the registration process you will need to provide the template according to which the messages will be sent. You can register as many templates as you want.

For the example below, the following template with the name InfoVK_template was registered; “Hi #parameter1# this is a test message with #parameter2#”.

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

{ 
	"scenarioKey":"CC9F01A5DC7BEE2C2B829D203482A654",  
  "destinations":[ 
  	{ 
    	"to":{
        "phoneNumber": "41793026727"
      }
    }
  ],
  "vKontakte": {
  	"templateName": "InfoVK_template",
        "templateData": {"parameter1":"param1Value", "parameter2":"param2Value"}
  },
  "sms": {
  	"text": "This is the SMS failover message"
  }
}	
  

Response format

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.

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": "50c24400-124f-4678-9f4b-309e994a4deb"
        }
    ]
}	
  

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

If you have any additional questions please contact us.