OMNI: Send advanced message

This method allows you to send a message to one or more destination addresses over the OMNI channel.

Resource

https://api.infobip.com/omni/1/advanced

Parameters


 

Property name Type Description
phoneNumber* string Destination phone number. Addresses must be in international format (example: 41793026727).
emailAddress string Destination email address.
messageId string The ID that uniquely identifies the message sent.
bulkId string The ID which uniquely identifies the request. Bulk ID will be received only when you send a message to more than one destination address.
scenarioKey string Scenario key that uniquely identifies the scenario which will be used when sending message. If this field is not set, the default scenario will be used.
sms object SMS specific data. The data will be used if the message is sent through SMS channel.
voice object Voice specific data. The data will be used if the message is sent through voice channel.
viber object Viber specific data. The data will be used if the message is sent through Viber channel.
facebook object Facebook Messenger specific data. The data will be used if the message is sent through Facebook channel.
email object Email specific data. The data will be used if the message is sent through email channel.
text string Text of the message that will be sent.
validityPeriod int The message validity period. Unless specified differently in validityPeriodTimeUnit, it is expressed in minutes. When the period expires, the message will be automatically sent using the next OMNI step. Validity period longer than 48h is not supported (in this case, it will be automatically set to 48h). Additionally, period should be longer than 30 seconds.
validityPeriodTimeUnit string (MINUTES) The message validity period time unit, allowing finer time granulation. Supported values are: SECONDS, MINUTES and HOURS.
sendAt datetime Date and time when the message is to be sent. Used for scheduled OMNI messaging (first message in the OMNI flow not sent immediately, but at scheduled time).

Request Example 

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

{ 
  "bulkId":"BULK-ID-123-xyz",
  "scenarioKey":"AD9E01A5DC7BEE2C2B828D208182A611",  
  "destinations":[ 
  	{ 
    	"messageId":"MESSAGE-ID-123-xyz",
      "to":{
        "phoneNumber": "41793026727",
        "emailAddress": "email@example.com"
      }
    },
    { 
    	"to":{
        "phoneNumber": "41793026731"
      }
    }
  ],
  "sms": {
  	"text": "Artık Ulusal Dil Tanımlayıcısı ile Türkçe karakterli smslerinizi rahatlıkla iletebilirsiniz.",
     "language":{
       "languageCode":"TR"
     },
     "transliteration":"TURKISH"
  },
  "viber": {
  	"text": "Or to have fun with Viber text."
  },
  "voice": {
  	"text": "Or make a call and read this text"
  },
  "facebook": {
  	"text": "Receive a message in Facebook Messenger."
  },
  "email":{
    "text":"Finally, send an email.",
    "subject": "Email subject"
   }  
}
					
				
					POST /omni/1/advanced HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/xml

<request>
  <bulkId>BULK-ID-123-xyz</bulkId>
  <scenarioKey>AD9E01A5DC7BEE2C2B828D208182A611</scenarioKey>
  <destinations>
  	<destination>
    	<to>
        <phoneNumber>41793026727</phoneNumber>
        <emailAddress>email@example.com</emailAddress>
      </to>
      <messageId>MESSAGE-ID-123-xyz</messageId>
    </destination>
    <destination>
      <to>
        <phoneNumber>41793026731</phoneNumber>
      </to>
    </destination>
  </destinations>
  <sms>
    <text>SMS text</text>
  </sms>
  <viber>
    <text>Viber text</text>
  </viber>
  <voice>
    <text>Voice text</text>
  </voice>
  <email>
    <text>Email text</text>
    <subject>Subject</subject>
  </email>
</request>
					
				
					curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" \
-d '{ 
  "bulkId":"BULK-ID-123-xyz",
  "scenarioKey":"AD9E01A5DC7BEE2C2B828D208182A611",  
  "destinations":[ 
  	{ 
    	"messageId":"MESSAGE-ID-123-xyz",
      "to":{
        "phoneNumber": "41793026727",
        "emailAddress": "email@example.com"
      }
    },
    { 
    	"to":{
        "phoneNumber": "41793026731"
      }
    }
  ],
  "sms": {
  	"text": "This is custom SMS text."
  },
  "viber": {
  	"text": "Or to have fun with Viber text."
  },
  "voice": {
  	"text": "Or make a call and read this text"
  },
  "email":{
    "text":"Email message text.",
    "subject": "Test subject"
   }
}' https://api.infobip.com/omni/1/advanced
					
				
					<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.infobip.com/omni/1/advanced",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{ \"bulkId\":\"BULK-ID-123-xyz\", \"scenarioKey\":\"AD9E01A5DC7BEE2C2B828D208182A611\", \"destinations\":[ { \"messageId\":\"MESSAGE-ID-123-xyz\", \"to\":{ \"phoneNumber\":\"41793026727\", \"emailAddress\":\"email@example.com\" } }, { \"to\":{ \"phoneNumber\":\"41793026731\" } } ], \"sms\":{ \"text\":\"This is custom SMS text.\" }, \"viber\":{ \"text\":\"Or to have fun with Viber text.\" }, \"voice\":{ \"text\":\"Or make a call and read this text\" }, \"facebook\":{ \"text\":\"Receive a message in Facebook Messenger.\" }, \"email\":{ \"text\":\"Finally, send an email.\", \"subject\":\"Email subject\" } }",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
					
				
					require 'uri'
require 'net/http'

url = URI("https://api.infobip.com/omni/1/advanced")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
request["content-type"] = 'application/json'
request["cache-control"] = 'no-cache'
request["postman-token"] = 'ba1c51d5-26df-2cbf-a4de-58a95ac687cd'
request.body = "{ \n  \"bulkId\":\"BULK-ID-123-xyz\",\n  \"scenarioKey\":\"AD9E01A5DC7BEE2C2B828D208182A611\",  \n  \"destinations\":[ \n  \t{ \n    \t\"messageId\":\"MESSAGE-ID-123-xyz\",\n      \"to\":{\n        \"phoneNumber\": \"41793026727\",\n        \"emailAddress\": \"email@example.com\"\n      }\n    },\n    { \n    \t\"to\":{\n        \"phoneNumber\": \"41793026731\"\n      }\n    }\n  ],\n  \"sms\": {\n  \t\"text\": \"This is custom SMS text.\"\n  },\n  \"viber\": {\n  \t\"text\": \"Or to have fun with Viber text.\"\n  },\n  \"voice\": {\n  \t\"text\": \"Or make a call and read this text\"\n  },\n  \"email\":{\n    \"text\":\"Email message text.\",\n    \"subject\": \"Test subject\"\n   }\n}"

response = http.request(request)
puts response.read_body
					
				
					import http.client

conn = http.client.HTTPSConnection("api.infobip.com")

payload = "{ \n  \"bulkId\":\"BULK-ID-123-xyz\",\n  \"scenarioKey\":\"AD9E01A5DC7BEE2C2B828D208182A611\",  \n  \"destinations\":[ \n  \t{ \n    \t\"messageId\":\"MESSAGE-ID-123-xyz\",\n      \"to\":{\n        \"phoneNumber\": \"41793026727\",\n        \"emailAddress\": \"email@example.com\"\n      }\n    },\n    { \n    \t\"to\":{\n        \"phoneNumber\": \"41793026731\"\n      }\n    }\n  ],\n  \"sms\": {\n  \t\"text\": \"This is custom SMS text.\"\n  },\n  \"viber\": {\n  \t\"text\": \"Or to have fun with Viber text.\"\n  },\n  \"voice\": {\n  \t\"text\": \"Or make a call and read this text\"\n  },\n  \"email\":{\n    \"text\":\"Email message text.\",\n    \"subject\": \"Test subject\"\n   }\n}"

headers = {
    'content-type': "application/json",
    'authorization': "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
    }

conn.request("POST", "/omni/1/advanced", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
					
				
					HttpResponse<String> response = Unirest.post("https://api.infobip.com/omni/1/advanced")
  .header("content-type", "application/json")
  .header("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
  .body("{ \n  \"bulkId\":\"BULK-ID-123-xyz\",\n  \"scenarioKey\":\"AD9E01A5DC7BEE2C2B828D208182A611\",  \n  \"destinations\":[ \n  \t{ \n    \t\"messageId\":\"MESSAGE-ID-123-xyz\",\n      \"to\":{\n        \"phoneNumber\": \"41793026727\",\n        \"emailAddress\": \"email@example.com\"\n      }\n    },\n    { \n    \t\"to\":{\n        \"phoneNumber\": \"41793026731\"\n      }\n    }\n  ],\n  \"sms\": {\n  \t\"text\": \"This is custom SMS text.\"\n  },\n  \"viber\": {\n  \t\"text\": \"Or to have fun with Viber text.\"\n  },\n  \"voice\": {\n  \t\"text\": \"Or make a call and read this text\"\n  },\n  \"email\":{\n    \"text\":\"Email message text.\",\n    \"subject\": \"Test subject\"\n   }\n}")
  .asString();
					
				
					var client = new RestClient("https://api.infobip.com/omni/1/advanced");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{ \n  \"bulkId\":\"BULK-ID-123-xyz\",\n  \"scenarioKey\":\"AD9E01A5DC7BEE2C2B828D208182A611\",  \n  \"destinations\":[ \n  \t{ \n    \t\"messageId\":\"MESSAGE-ID-123-xyz\",\n      \"to\":{\n        \"phoneNumber\": \"41793026727\",\n        \"emailAddress\": \"email@example.com\"\n      }\n    },\n    { \n    \t\"to\":{\n        \"phoneNumber\": \"41793026731\"\n      }\n    }\n  ],\n  \"sms\": {\n  \t\"text\": \"This is custom SMS text.\"\n  },\n  \"viber\": {\n  \t\"text\": \"Or to have fun with Viber text.\"\n  },\n  \"voice\": {\n  \t\"text\": \"Or make a call and read this text\"\n  },\n  \"email\":{\n    \"text\":\"Email message text.\",\n    \"subject\": \"Test subject\"\n   }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
					
				
					var data = JSON.stringify({ 
  "bulkId":"BULK-ID-123-xyz",
  "scenarioKey":"AD9E01A5DC7BEE2C2B828D208182A611",  
  "destinations":[ 
  	{ 
    	"messageId":"MESSAGE-ID-123-xyz",
      "to":{
        "phoneNumber": "41793026727",
        "emailAddress": "email@example.com"
      }
    },
    { 
    	"to":{
        "phoneNumber": "41793026731"
      }
    }
  ],
  "sms": {
  	"text": "This is custom SMS text."
  },
  "viber": {
  	"text": "Or to have fun with Viber text."
  },
  "voice": {
  	"text": "Or make a call and read this text"
  },
  "email":{
    "text":"Email message text.",
    "subject": "Test subject"
   }
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.infobip.com/omni/1/advanced");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==");

xhr.send(data);

Response 

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

{   
    "bulkId":"BULK-ID-123-xyz",
    "messages":[   
        {   
            "to":{
              "phoneNumber": "41793026727",
              "emailAddress": "email@example.com"
            },
            "status": {
                "groupId": 1,
                "groupName": "PENDING",
                "id": 7,
                "name": "PENDING_ENROUTE",
                "description": "Message sent to next instance"
            },
            "messageId": "MESSAGE-ID-123-xyz"
        },
        {   
            "to":{
              "phoneNumber": "41793026731"
            },
            "status": {
                "groupId": 1,
                "groupName": "PENDING",
                "id": 7,
                "name": "PENDING_ENROUTE",
                "description": "Message sent to next instance"
            },
            "messageId": "5a7b59de-c5e9-4f7c-9df9-25d53fd32309"
        }
    ]
}
					
				
					HTTP/1.1 200 OK
Content-Type: application/xml

<omniResponse>
	<bulkId>BULK-ID-123-xyz</bulkId>
	<messages>
  	<message>
			<to>
        <phoneNumber>41793026727</phoneNumber>
        <emailAddress>email@example.com</emailAddress>
      </to>
			<status>
				<groupId>0</groupId>
				<groupName>ACCEPTED</groupName>
				<id>0</id>
				<name>MESSAGE_ACCEPTED</name>
				<description>Message accepted</description>
			</status>
			<messageId>MESSAGE-ID-123-xyz</messageId>
		</message>
		<message>
			<to>
        <phoneNumber>41793026731</phoneNumber>
      </to>
			<status>
				<groupId>0</groupId>
				<groupName>ACCEPTED</groupName>
				<id>0</id>
				<name>MESSAGE_ACCEPTED</name>
				<description>Message accepted</description>
			</status>
			<messageId>9304a5a3ab19-1ca1-be74-76ad87651ed25f35</messageId>
  	</message>
  </messages>
</omniResponse>

Sending a message with a scenario key

We will attempt to send the message sequentially as defined in a given scenario. If sending over the first defined step fails, we will attempt to send it over second and so on.

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.

OmniResponse

Parameter Type Description
bulkId String The ID that uniquely identifies the request. Bulk ID will be received only when a message is sent to more than one destination address.
messages OmniResponseDetails Array of sent message objects, one object per every message.

OmniResponseDetails

Parameter Type Description
to To The message destination address.
status Status Indicates whether the message is sent successfully, not sent, delivered, not delivered, waiting for delivery or any other possible status.
messageId String The ID that uniquely identifies the sent message.

To

Parameter Type Description
phoneNumber String The message destination phone number.
emailAddress String The message destination email address.

Status

Parameter Type Description
groupId int Status group ID.
groupName String Status group name.
id int Status ID.
name String Status name.
description String Human-readable description of the status.
action String Action that should be taken to eliminate the error.

Additional example

Send a scheduled OMNI message with a custom Validity period

You can schedule your OMNI messages with a predefined date and time.

To reach users in the fastest and most effective way, define validity periods for each message step.

Validity period constraints

Note that the validityPeriod together with its validityPeriodTimeUnit should not represent a time interval shorter than 30 seconds or longer than 48 hours.

{
    "scenarioKey": "AD9E01A5DC7BEE2C2B828D208182A611",
    "destinations": [
        {
            "to": {
                "phoneNumber": "41793026727",
                "emailAddress": "email@example.com"
            }
        }
    ],
    "viber": {
        "text": "Viber message is going first.",
        "validityPeriod": 1
    },
    "sms": {
        "text": "After one minute I'm trying to reach the user on SMS",
        "validityPeriod": 90,
        "validityPeriodTimeUnit": "SECONDS"
    },
    "email": {
        "text": "Two and a half minutes (1 minute + 90 seconds) after the initial message I'm trying to reach the user on email for the next two hours.",
        "subject": "Hey - turn on your mobile phone!",
        "validityPeriod": 2,
        "validityPeriodTimeUnit": "HOURS"
    },
    "sendAt": "2016-04-26T10:52:15.000+01:00"
}

Result Format 

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

{   
    "messages":[   
        {   
            "to":{
              "phoneNumber": "41793026727",
              "emailAddress": "email@example.com"
            },
            "status": {
                "groupId": 1,
                "groupName": "PENDING",
                "id": 7,
                "name": "PENDING_ENROUTE",
                "description": "Message sent to next instance"
            },
            "messageId": "f2c7b078-6645-43c5-a840-70d6a246b7d7"
        }
}
Prev: OMNI: Send simple message Next: OMNI reports