Sozuri Developer Documentation

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 Shortcode sender defined in your project. This must be registered and
number	Yes	String	A recipient phone number. Define the messages destination in the international mobile number format .E164 e.g "25472xx64287". 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	premium. Define the channel you wish to send your message with.
message	Yes	String	Content of the message to be sent (Mandatory for SMS and Whatsapp of contentType text
type	No	String	Subscription. This must match the type of Shortcode you are using. Can either be subscription or ondemand.
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
keyword	Yes	String	The keyword to be used for a premium service.

The body of the response will be a JSON object containing the following fields:

Parameter Name	Type	Description
messageData	String	The eventual result of the sms request. It contains the count of sms: >
recipients	String	A list of recipients that you included in the request. Each recipient is a Map with the following fields
messageId	String	This is the unique talkzuri message ID returned in the response after the message is successfully accepted
to	String	This is the recipient’s phone number
status	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)
messagePart	String	This is the nuber of Full text messages. A Full message is made up of 160 characters.
type	String	premium

Sample POST Subscription Premium send SMS Request


POST /api/v1/premium HTTP/1.1
Host: sozuri.net
Authorization: Bearer LOx5JPdqf0lvf.......R9X9XDJ4PFxRqVrt9dx83cWiwfTQMF
Content-Type: application/json
Accept: application/json
{
    "project":"my project",
    "from":"23546",
    "to":"2547251642xx",
    "campaign":"Promo Nai",
    "channel":"premium",
    "message":"Test SMS.",
    "type": "subscription",
    "linkId": "54785454"
    "keyword": "Omoka"

}


POST /api/v1/premium   HTTP/1.1
Host: sozuri.net
Authorization: Bearer LOx5JPdqf0lvf45EZAQMJ.......SUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF
Content-Type: application/json
Accept: application/xml
<request>
    <project>my project</project>
    <from>25465</from>
    <to>2547251642xx</to>
    <campaign>Promo nai</campaign>
    <channel>premium</channel>
    <message>Test SMS.</message>
    <type>subscription</type>
    <linkId>234542</linkId>
    <keyword>Omoka</keyword>

</request>

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://sozuri.net/api/v1/premium",
    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\":\"253145\",\"to\":\"2547251642xx\",
\"campaign\":\"Promo nai\",\"channel\":\"premium\",\"message\":\"Test SMS.\",\"type\":\"subscription\",\"linkId\":\"234542\",\"keyword\":\"Omoka\" }",
    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":"235464",
    "to":"2547251642xx",
    "campaign":"Promo Nai",
    "channel":"premium",
    "message":"Test SMS.",
    "type": "subscription",
    "linkId": "54785454",
    "keyword": "Omoka"
});

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/premium",);
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/premium")

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\":\"254654\",\"to\":\"2547251642xx\",
\"campaign\":\"Promo nai\",\"channel\":\"premium\",\"message\":\"Test SMS.\",\"type\":\"subscription\",\"linkId\":\"234542\",\"keyword\":\"Omoka\"}"

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


conn = http.client.HTTPSConnection("sozuri.net")

payload = "{\"project\":\"my project\",\"from\":\"231254\",\"to\":\"2547251642xx\",
\"campaign\":\"Promo nai\",\"channel\":\"sms\",\"message\":\"Test SMS.\",\"type\":\"subscription\",\"linkId\":\"234542\",\"keyword\":\"Omoka\"}"

headers = {
    'authorization': "Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF",
    'content-type': "application/json",
    'accept': "application/json"
    }

conn.request("POST", "/api/v1/premium", payload, headers)

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

print(data.decode("utf-8"))


HttpResponse<String> response = Unirest.post("https://sozuri.net/api/v1/premium")
    .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\":\"premium\",\"message\":\"Test SMS.\",\"type\":\"subscription\",\"linkId\":\"234542\",\"keyword\":\"Omoka\"}")
    .asString();


var client = new RestClient("https://sozuri.net/api/v1/premium");
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\":\"21254\",\"to\":\"2547251642xx\",
\"campaign\":\"Promo nai\",\"channel\":\"sms\",\"message\":\"Test SMS.\",\"type\":\"subscription\",\"linkId\":\"234542\",\"keyword\":\"Omoka\"}", 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":"23451",
    "to":"2547251642xx",
    "campaign":"Promo Nai",
    "channel":"sms",
    "message":"Test SMS.",
    "type": "Subscription"
}' https://sozuri.net/api/v1/premium


HTTP/1.1 200 OK
Content-Type: application/json
{
    "Result": [
        {
            "messageId": "TZ5DBC6504A7243",
            "credits": 1,
            "number": "+2547251642xx",
            "status": "Success",
            "statusCode": "Hello World."
        },

    ]

            }

Synchronous JSON Response



{
    "messageData": {
        "messages": 2
    },
    "recipients": [
        {
            "messageId": "MSGBLK6012A7E8B90A21611835368",
            "to": "2547251642xx",
            "status": "accepted",
            "statusCode": "11",
            "keyword": "Omoka",
            "messagePart": 1,
            "type": "Subscription"
        },
    ]
}

Sample Create Subscriber Request (for the DELETE counterpart request, just change the value of parameer "type" from "subscribe" to "unsubscribe"


POST /api/v1/premium HTTP/1.1
Host: sozuri.net
Authorization: Bearer LOx5JPdqf0lvf.......R9X9XDJ4PFxRqVrt9dx83cWiwfTQMF
Content-Type: application/json
Accept: application/json
{
    "project":"my project",
    "shortcode": "25654"
    "keyword": "Omoka"
    "number":"2547251642xx",
    "network": "safaricom"
    "type": "subscribe",

}


POST /api/v1/premium   HTTP/1.1
Host: sozuri.net
Authorization: Bearer LOx5JPdqf0lvf45EZAQMJ.......SUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF
Content-Type: application/json
Accept: application/xml
<request>
    <project>my project</project>
    <shortcode>25465</shortcode>
    <keyword>Omoka</keyword>
    <number>2547251642xx</number>
    <network>Promo nai</network>
    <type>subscribe</type>
</request>

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://sozuri.net/api/v1/premium",
    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\",\"shortcode\":\"253145\",\"number\":\"2547251642xx\",
\"network\":\"safaricom\",\"type\":\"subscribe\", }",
    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",
    "shortcode":"235464",
    "keyword": "Omoka"
    "number":"2547251642xx",
    "network":"safaricom",
    "type":"subscribe",
});

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/premium",);
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/premium")

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\",\"shortcode\":\"254654\",\"keyword\":\"Omoka\",\"number\":\"2547251642xx\",
\"network\":\"safaricom\",\"type\":\"subscribe\",}"

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


conn = http.client.HTTPSConnection("sozuri.net")

payload = "{\"project\":\"my project\",\"shortcode\":\"231254\",\"keyword\":\"Omoka\",\"number\":\"2547251642xx\",
\"network\":\"safaricom\",\"type\":\"subscribe\"}"

headers = {
    'authorization': "Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF",
    'content-type': "application/json",
    'accept': "application/json"
    }

conn.request("POST", "/api/v1/premium", payload, headers)

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

print(data.decode("utf-8"))


HttpResponse<String> response = Unirest.post("https://sozuri.net/api/v1/premium")
    .header("authorization", "Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF")
    .header("content-type", "application/json")
    .header("accept", "application/json")
    .body("{\"project\":\"my project\",\"shortcode\":\"254565\",\"keyword\":\"Omoka\",\"number\":\"2547251642xx\",
\"network\":\"safaricom\",\"type\":\"subscribe\"}")
    .asString();


var client = new RestClient("https://sozuri.net/api/v1/premium");
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\",\"shortcode\":\"21254\",\"keyword\":\"Omoka\",\"number\":\"2547251642xx\",
\"network\":\"safaricom\",\"type\":\"subscribe\"}", 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",
    "shortcode":"23451",
    "keyword":"Omoka",
    "number":"2547251642xx",
    "network":"safaricom",
    "type":"subscribe",
}' https://sozuri.net/api/v1/premium


HTTP/1.1 200 OK
Content-Type: application/json
{
    "Result": [
        {
            "messageId": "TZ5DBC6504A7243",
            "credits": 1,
            "number": "+2547251642xx",
            "status": "Success",
            "statusCode": "Hello World."
        },

    ]

            }

Synchronous JSON Response



{
    "project":"my project",
    "shortcode": "25654"
    "keyword": "Omoka"
    "number":"2547251642xx",
    "network": "safaricom"
    "type": "subscribe",
    "status": "failure"
}

Activate

Sent whenever a subscriber subscribes to your service by sending an sms starting with your keyword string.

Sozuri will asynchronously send a callback to your application with the details of the subscriber and the keyword they used

Receive new subscriber CREATED/opt-in notification

{
    "project":"yourproject_name",
    "shortcode":"25145",
    "keyword":"JOIN",
    "number": "2547251xxxxx"
    "network": "safaricom",
    "type": "activation",
    "status": "success",
    "timestamp": "1603713484"
}

De-activate

Receive new subscriber DELETED/opt-out notification. When a subscriber opt-outsof your premium service.

{
    "project":"yourproject_name",
    "shortcode":"25145",
    "keyword":"JOIN",
    "number": "2547251xxxxx"
    "network": "safaricom",
    "type": "deactivation",
    "status": "success",
    "timestamp": "1603713484"
}

Receive the asynchronous consent response from a subscriber after a making an ACTIVATE request. This is received after invoking the activate subscription API and the status can be either success or failure

{
    "project":"yourproject_name",
    "shortcode":"25145",
    "keyword":"JOIN",
    "number": "2547251xxxxx"
    "network": "safaricom",
    "type": "consent",
    "status": "failure",
    "timestamp": "1603713484"
}

Delivery Status

Sent whenever a message you had sent changes status. We send a notification to your callback for that premium service

Receive an asynchronous DELIVERY STATUS NOTIFICATION callback when your sent Premium message changes status

{
    "project":"yourproject_name",
    "shortcode":"25145",
    "keyword":"JOIN",
    "number": "2547251xxxxx"
    "network": "safaricom",
    "type": "premiumDelivery"",
    "status": "success",
    "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.

Premium Subscription SMS

Send Premium Subscription SMS Request

Premium Subscription SMS Response parameters

Response FROM Sozuri OmniChannel API (synchronous)

Send Premium Subscription SMS message

NB: Premium Subscription Service will receive four types of important asynchronous Notifications: activate (when a customer opts-in), deactivate(when a subscriber opt-outs), consent(subscriber response to your 'subscribe' request), premiumDelivery(delivery status of premium SMS)

Receive Incoming Message (MO) to your Shortcode keywords from a subscriber

Activate

De-activate

Delivery Status

Setting a username & password on callback (Optional Authentication)

Premium Subscription SMS

Send Premium Subscription SMS Request

Premium Subscription SMS Response parameters

Response FROM Sozuri OmniChannel API (synchronous)

Send Premium Subscription SMS message

Create or delete a new Subscriber for your Premium service

NB: Premium Subscription Service will receive four types of important asynchronous Notifications: activate (when a customer opts-in), deactivate(when a subscriber opt-outs), consent(subscriber response to your 'subscribe' request), premiumDelivery(delivery status of premium SMS)

Receive Incoming Message (MO) to your Shortcode keywords from a subscriber

Activate

De-activate

Consent

Delivery Status

Setting a username & password on callback (Optional Authentication)