Premium Ondemand SMS

Contents

1. Request Parameters

2. Response Parameters

3. Send Premium Ondemand SMS

4. Receive Premium Ondemand Callback Notifications for message with keyword from subscriber

Send Premium Ondemand 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
to Yes String A recipient phone number. 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 premium. Define the channel you wish to send your message with.
message(SMS & Whatsapp) Yes String Content of the message to be sent (Mandatory for SMS and Whatsapp of contentType text
type No String ondemand. This must match the type of Shortcode you are using. Can either be ondemand or subscription.
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
linkId Yes String This ID is generated when a user requests for an Ondemand service. This parameter is mandatory while delivering content for ondemand services.
keyword Yes String The keyword to be used for a premium service.

Premium Ondemand 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 Ondemand SMS message

Sample POST Ondemand Premium 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": "ondemand",
    "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>ondemand</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\":\"ondemand\",\"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": "ondemand",
    "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\":\"ondemand\",\"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\":\"ondemand\",\"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\":\"ondemand\",\"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\":\"ondemand\",\"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": "ondemand"
}' 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": "ondemand"
        },
    ]
}

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

Sent whenever a message with your respective Keyword is sent to any of your registered shortcodes. We send a notification to your callback for that premium service with the respective linkId for sending back a reply to the subscriber.

Sozuri will asynchronously send a callback to your application with the details of any messages that were received via your Shortcode keyword.

Receive Message Callback to your webhook 

{
    "project":"yourproject_name",
    "shortcode":"25145",
    "keyword":"JOIN",
    "number": "2547251xxxxx"
    "network": "safaricom",
    "type": "linkNotification",
    "linkId": "256e487h2",
    "status": "success",
    "timestamp": "1603713484"
}
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.