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 parameters

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 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 and sent to you in a notification(see below) message 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 ondemand

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 will send a notification to your callback for that premium service with the respective linkId that you will use for sending back a reply to the subscriber.

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

Delivery status notification for your Ondemand messages

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