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(SMS & Whatsapp) 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
contentType (whatsapp) Yes String The type of whatsapp content being sent. Allowed are: text, media, or location
longitude(whatsapp) No Double Longitude of a location (Only if contentType is location
latitude(whatsapp) No Double latitude of a location (Only if contentType is location
latitude(whatsapp) No Double Latitude of a location (Only if contentType is location
label(whatsapp) No Double Label of a location (Only if contentType is location
address(whatsapp) No Double Address of a location (Only if contentType is location
mediaUrl(whatsapp) No URL Url of a image(jpeg,jpg,png) (Only if contentType is media
mediaCaption(whatsapp) No String Caption of a location (Only if contentType is media
See an example SMS Request from the Postman Collection:

See an example Whatsapp Request from the Postman Collection:

Response FROM Sozuri OmniChannel API (synchronous)

The body of the response will be a JSON object containing the following fields:
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 (sms&whatsapp) String This is the type of message. SMS is either promotional or transactional for SMS or conversational or notification for whatsaa
contentType (whatsapp) String The type of whatsapp content being sent. Allowed are: text, media, or location
direction (whatsapp) String Inbound for C2B and Outbound for B2C
longitude (whatsapp) Double Longitude of a location (Only if contentType is location
latitude (whatsapp) Double latitude of a location (Only if contentType is location
latitude (whatsapp) Double Latitude of a location (Only if contentType is location
label (whatsapp) Double Label of a location (Only if contentType is location
address (whatsapp) Double Address of a location (Only if contentType is location
mediaUrl (whatsapp) URL Url of a image(jpeg,jpg,png) (Only if contentType is media
mediaCaption (whatsapp) String Caption of a location (Only if contentType is media
description (whatsapp) String Description of message: 'customer message' for c2b, 'business message' for b2c and 'status update' for async message status
cost (whatsapp) float Fee carged for the message

SMS


Whatsapp

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 callback

Sozuri will asynchronously send a callback to your application with the details of any messages that were received via either your SMS or WhatsApp channels (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 when the message has been read by Sozuri:

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.