BULK SMS
Request TO the Sozuri OmniChannel BULK SMS API
Parameter Name | Mandatory | Type | Description |
---|---|---|---|
project | Yes | String | The name of the project that owns the apiKey making this request. |
from | Yes | String | This is the Sender ID defined in your project. It will default to Sozuri |
to | Yes | String | A comma separated string of recipients’ phone numbers. Define the messages destination in the international mobile number format .E164 e.g "25472xx64287,25472289xx45". NB: talkzuri API will attempt to format your numbers accordingly eg.0722-503-129 is formatted to 254722503129 |
campaign | No | String | Name of the campaign you are sending the message for. |
channel | No | String | Define the channel you wish to send your message with. Defaults to SMS |
message | Yes | String | Content of the message to be sent (Mandatory for SMS and Whatsapp of contentType text |
type | Yes | String | transactional or promotional. This must match the type of sender ID you are using. Note, regulations stipulate that a Sender ID can either be EXPLICITLY promotional or transactional. |
apiKey | - | String | The Project API Key. NB: Instead of having the apiKey in the body, it can alternatively be added as the Value of an Authorization header Bearer token instead. See its use in the Request header HERE |
Sozuri OmniChannel BULK SMS Response parameters
Response FROM Sozuri OmniChannel API (synchronous)
Parameter Name | Type | Description |
---|---|---|
messageData (sms&whatsapp) | String | The eventual result of the sms request. It contains the count of sms: > |
recipients (sms&whatsapp) | String | A list of recipients that you included in the request. Each recipient is a Map with the following fields |
messageId (sms&whatsapp) | String | This is the unique talkzuri message ID returned in the response after the message is successfully accepted |
to (sms&whatsapp) | String | This is the recipient’s phone number |
status (sms&whatsapp) | String | Description of the status code eg. accepted, unknown_number. This is not indicative of the delivery status of the message. |
statusCode | String | Unique code for the status (see Status Code table for details) |
bulkId | String | The unique code identifying what batch of bulk sms request a message belongs to. |
messagePart | String | This is the nuber of Full text messages. A Full message is made up of 160 characters. |
type | String | This is the type of message. SMS is either promotional or transactional for SMS or conversational or notification for whatsaa |
SMS
Send plain SMS text message
Text SMS message
This allows you to send one or more messages at a go. Sozuri will use the SMS channel by default. Sozuri API responds with a unique identifier for each message. The Sozuri Omnichannel platform then asynchronously targets your project's callback URL with status updates.
1. SMS text message limitations:-
a. There is no limit to the number of messages you can send.
b. For SMS the maximum length of a single text message depends on whether your message is sent using the standard GSM character set, or using Unicode. for special characters.
c. For Whatsapp the maximum length of a single text message is 4096 characters
The base URL for all API call strings is: https://sozuri.net/api/v1/messaging.
One-way messaging: Request headers
POST /api/v1/messaging Content-Type: application/json Authorization: Bearer Your_Project_API_KEY
One-way messaging: Sample GET Request
https://sozuri.net/api/v1/messaging?apiKey=Your_Project_API_KEY&project=Your_Project_name&channel=sms&from=MySenderID&to=254722xxx675&message=SozuriTestSMS
Sample POST Request
POST /api/v1/messaging HTTP/1.1
Host: sozuri.net
Authorization: Bearer LOx5JPdqf0lvf.......R9X9XDJ4PFxRqVrt9dx83cWiwfTQMF
Content-Type: application/json
Accept: application/json
{
"project":"my project",
"from":"Sozuri",
"to":"2547251642xx,2547326971xx",
"campaign":"Promo Nai",
"channel":"sms",
"message":"Test SMS.",
"type": "promotional"
}
POST /api/v1/messaging HTTP/1.1
Host: sozuri.net
Authorization: Bearer LOx5JPdqf0lvf45EZAQMJ.......SUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF
Content-Type: application/json
Accept: application/xml
<request>
<project>my project</project>
<from>Sozuri</from>
<to>2547251642xx,2547326971xx</to>
<campaign>Promo nai</campaign>
<channel>sms</channel>
<message>Test SMS.</message>
<type>promotional</type>
</request>
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://sozuri.net/api/v1/messaging",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{ \"project\":\"my project\",\"from\":\"Sozuri\",\"to\":\"2547251642xx,2547326971xx\",
\"campaign\":\"Promo nai\",\"channel\":\"sms\",\"message\":\"Test SMS.\",\"type\":\"promotional\" }",
CURLOPT_HTTPHEADER => array(
"accept: application/json",
"authorization: Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
var data = JSON.stringify({
"project":"my project",
"from":"Sozuri",
"to":"2547251642xx,2547326971xx",
"campaign":"Promo Nai",
"channel":"sms",
"message":"Test SMS.",
"type": "promotional"
});
var xhr = new XMLHttpRequest();
xhr.withCredentials = false;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://sozuri.net/api/v1/messaging",);
xhr.setRequestHeader("authorization", "Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("accept", "application/json");
xhr.send(data);
require 'uri'
require 'net/http'
url = URI("https://sozuri.net/api/v1/messaging")
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"] = 'Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF'
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request.body = "{\"project\":\"my project\",\"from\":\"Sozuri\",\"to\":\"2547251642xx,2547326971xx\",
\"campaign\":\"Promo nai\",\"channel\":\"sms\",\"message\":\"Test SMS.\",\"type\":\"promotional\"}"
response = http.request(request)
puts response.read_body
conn = http.client.HTTPSConnection("sozuri.net")
payload = "{\"project\":\"my project\",\"from\":\"Sozuri\",\"to\":\"2547251642xx,2547326971xx\",
\"campaign\":\"Promo nai\",\"channel\":\"sms\",\"message\":\"Test SMS.\",\"type\":\"promotional\"}"
headers = {
'authorization': "Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF",
'content-type': "application/json",
'accept': "application/json"
}
conn.request("POST", "/api/v1/messaging", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://sozuri.net/api/v1/messaging")
.header("authorization", "Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF")
.header("content-type", "application/json")
.header("accept", "application/json")
.body("{\"project\":\"my project\",\"from\":\"Sozuri\",\"to\":\"2547251642xx,2547326971xx\",
\"campaign\":\"Promo nai\",\"channel\":\"sms\",\"message\":\"Test SMS.\",\"type\":\"promotional\"}")
.asString();
var client = new RestClient("https://sozuri.net/api/v1/messaging");
var request = new RestRequest(Method.POST);
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddHeader("authorization", "Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF");
request.AddParameter("application/json", "{ \"project\":\"my project\",\"from\":\"Sozuri\",\"to\":\"2547251642xx,2547326971xx\",
\"campaign\":\"Promo nai\",\"channel\":\"sms\",\"message\":\"Test SMS.\",\"type\":\"promotional\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF' \
-d '{
"project":"my project",
"from":"Sozuri",
"to":"2547251642xx,2547326971xx",
"campaign":"Promo Nai",
"channel":"sms",
"message":"Test SMS.",
"type": "promotional"
}' https://sozuri.net/api/v1/messaging
HTTP/1.1 200 OK
Content-Type: application/json
{
"Result": [
{
"tzId": "TZ5DBC6504A7243",
"credits": 1,
"number": "+2547251642xx",
"status": "Success",
"statusCode": "Hello World lucy."
},
{
"wzId": "TZ5DBC6504A7289",
"sms_credits": 1,
"to": "+2547326971xx",
"status": "Success",
"message": "Hello World John."
}
]
}
JSON Response
{ "messageData": { "messages": 2 }, "recipients": [ { "messageId": "MSGBLK6012A7E8B90A21611835368", "to": "2547251642xx", "status": "accepted", "statusCode": "11", "bulkId": "bulk6012a7e8b904e1611835368", "messagePart": 1, "type": "promotional" }, { "messageId": "MSGBLK6012A7E8B90A41611835368", "to": "2547326971xx", "status": "accepted", "statusCode": "11", "bulkId": "bulk6012a7e8b904e1611835368", "messagePart": 1, "type": "promotional" } ] }
Receive message Delivery callback Notification
Receive message callback
Sozuri will asynchronously send a callback to your application with the details of any messages that were received via either your SMS channel (incoming messages sent from the end user’s mobile phone to your business account).
Note that the sequence in which message callbacks are received is not guaranteed to be the original sequence in which these messages were initiated by users. The callback will return the incoming messages with a timestamp generated upon receiving them in the Sozuri system. The exact implementation of this timestamp could vary from channel to channel.
Below is a standard callback sample to your webhook when the message has been received by Sozuri:
To set up your webhook, Open your Sozuri project and go to Manage API > Callback URLs
Receive Message Callback to your webhook
{ "project":"yourproject_name", "messageId": "MSGBLK5F96B6A0CC2EB1603712672", "channel":"sms", "status": "success", "network": "safaricom", "type": "bulkDelivery", "timestamp": "1603713484" }
Setting a username & password on callback (Optional Authentication)
It is possible to predefine an Auth Key for your message callbacks. This value will then be included as parameters in the body to allow your system to authenticate that the request is indeed from Sozuri.