Premium Subscription SMS

Send Premium Subscription SMS Request

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.

Premium Subscription SMS Response parameters

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 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

Send Premium Subscription SMS message

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

To Create or delete a new Subscriber for your Premium service

Change type to "subscribe" or "unsubscribe" for creating or deleting a subscriber respectively.

You will then await the asynchronous CONSENT callback sent to your project webhook to know the status of the subscribe or unsubscribe request.

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"
}

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

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)

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"
}

Consent

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.