Guide for Bulk SMS integration

Last updated: Feb 11th, 2018

Introduction

This document provides a reference for all features available to you via the HTTP interface for sending SMS.

The HTTP-API allows you to integrate your application (client) to Movetech Bulk SMS using the HTTP protocol to send SMS. HTTPS is also supported for secure transactions using SSL encryption.

The Client issues either a HTTP GET or POST request to the Movetech Bulk SMS HTTP interface supplying a list of required parameters. Movetech Bulk SMS issues back a HTTP response which indicates the validity of the transaction.

The HTTP-API is used for one-way messaging only. Therefore, you need to provide a valid Shortcode number as the Sender ID of the message to enable the recipient to respond.

REGISTER AND ACCOUNT TO GET Movetech API

Getting API code

Register

In our Bulk SMS we have exposed API endpoints for accessing Bulk SMS and other services; we have Bulk SMS API endpoints for Sending Bulk SMS, Checking Balance, and Scheduling Bulk SMS. You need your Movetech Bulk SMS username and APIKey for any request to our API. If you don't have an APIKey, you can generate one from Movetech Bulk SMS  portal here.

Developer Sign-up

To use our APIs or invoke an API endpoint, you will need to register for an account. You will receive an SMS with sender ID Movetech for activation and also an account activation link will be sent in an email to the email address you used in registering for an account; the activation link expires within 24 hours of it being sent, and you will need to register for another account. The account activation link enables you to activate your developer account and set a password for your account.

Register an Account
Movetech Bulk SMS
Verify Your Accounts:

You must first verify the account by checking your email and SMS code generated and sent to your phone. If you encounter problems call our instant customer care on 254 742 06 33 55

Check API Code

Kindly on the left Menu. click on HTTP API.

Movetech Bulk SMS

Required Parameters

Parameter
  • username.
  • api_key.
  • sender.
  • to.
  • message.
  • msgtype.
  • dlr.

Required Parameters

Description
  1. Your account Username.
  2. Your API Key.
  3. Your Sender ID.
  4. Your Recipients separated by commas.
  5. Your Text Message.
  6. Type of the message (use 5 for plain sms).
  7. Type of Delivery Report(use 0 for no delivery Report).

Quick HTTP API URL

Access Quick HTTP API URL List To test it on your preferred browser or using postman application, you can use the following HTTP API URLs to test our rest API.

/* ======= Full URL to our API ======= */
Send Simple SMS     https://www.sms.movesms.co.ke/API?userId=YOURUSERNAME&password=YOURPASSWORD&senderId=YOURSENDERNAME&sendMethod=simpleMsg&msgType=TEXT&msg=YOUR+MESSAGE&mobile=254700123456,254700123457&duplicateCheck=true&format=json

Send Group SMS     https://www.sms.movesms.co.ke/API?userId=YOURUSERNAME&password=YOURPASSWORD&senderId=YOURSENDERNAME&sendMethod=groupMsg&msgType=TEXT&msg=YOUR+MESSAGE&group=test,test1,test2&duplicateCheck=true&format=json

Send using Bulk Upload     https://www.sms.movesms.co.ke/API?userId=YOURUSERNAME&password=YOURPASSWORD&senderId=YOURSENDERNAME&sendMethod=excelMsg&msgType=TEXT&msg=YOUR+MESSAGE&file=/file/path&duplicateCheck=true&format=json

SMS API Code EXAMPLES

We can help you in guiding you where possible. Otherwise, the codes below will greatly help you.

Useful Tip:

The following sample code has been contributed by our community of developers to help you get started with Movetech Bulk SMS faster. The code they’ve given back to everyone represents a lot of time & work that you can benefit from as you implement Bulk SMS with your application!

If you have usage examples or code libraries in other languages, please let us know.

Please note that these samples were coded by Movetech , so you can reuse or redevelop them. Of course, we help where we can, but our internal knowledge is Java and Php. Most of our Developers who made the code are happy to help, and some of them can easily be reached on Twitter.

Java Code Example
<!DOCTYPE html> 

import java.io.BufferedReader;

import java.io.InputStreamReader;
import java.net.URL;
import org.springframework.security.authentication.BadCredentialsException;
@SuppressWarnings("restriction")
public class SecurityFunction {

	  public static String sendSms(String link, String usern, String key, String senderId,   String phonenumber,String msg){
			try{	
				try{
					 URL smslink = new URL(link+"?action=compose&"+"username="+usern+"&api_key="+key+"&sender="+senderId+"&to="+phonenumber+"&message="+java.net.URLEncoder.encode(msg, "UTF-8")+"");
						BufferedReader in = new BufferedReader(ja
								new InputStreamReader(
										smslink.openStream()));
								String inputLine;
					while ((inputLine = in.readLine()) != null)
					    System.out.println(inputLine);
					
					System.out.println("Sms send successfully!");
					
					//System.out.println("Api: " +smslink);

					in.close();
				 }catch (Exception e) {
					 e.printStackTrace();
						Xlog.LogError(e);
					 throw new BadCredentialsException("Sms Connection not Found");
				}
			}catch (Exception e) {
				e.printStackTrace();
				Xlog.LogError(e);
			}
			return null;
			
		}
		  

}

    
</html>
Send SMS in cURL

The following bulk SMS API sample can be used to send out text messages in Single, Bulk, Group and Excel Upload. Through Excel Upload we allow 2 types of text messages to be sent, one is normal with mobile numbers and second one is Custom. In custom, you can upload custom parameters which will be explained in detail in this documentation.

If you have usage examples or code libraries in other languages, please let us know.

This sample API is for PHP both in POST or GET method.

Send SMS in cURL
/* ======= Base Styling ======= */
curl -X POST \
  https://www.sms.movesms.co.ke/API/ \
  -H 'apikey: somerandomuniquekey' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'userId=user&password=userpass&senderId=SMSGAT&sendMethod=simpleMsg&msgType=text&mobile=254700123456&msg=This%20is%20my%20first%20message%20with%20SMSGateway.Center&duplicateCheck=true&format=json&scheduleTime=2017-06-13%2020%3A22%3A00'

Send SMS in C#
/*

Imports System
Imports System.Text
Imports System.Net
Imports System.Net.Security
Imports System.Collections.Specialized
Imports System.Security.Cryptography.X509Certificates
Module SendSMS
 

    Public Function AcceptAllCertifications(
    sender As Object,
    certificate As X509Certificate,
    chain As X509Chain,
    sslPolicyErrors As SslPolicyErrors
) As Boolean
 

        Return True
 

    End Function
 

    Public Sub sendMsg()
 

        Try
 

            ServicePointManager.Expect100Continue = True
            ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls Or SecurityProtocolType.Tls11 Or SecurityProtocolType.Tls12 Or SecurityProtocolType.Ssl3
 

            ServicePointManager.ServerCertificateValidationCallback =
      New RemoteCertificateValidationCallback(AddressOf AcceptAllCertifications)
 

            Dim url As String = "https://sms.movesms.co.ke/api/balance?"
            Using wb = New WebClient()
                Dim data = New NameValueCollection()
                data("username") = "username"
                data("api_key") = "TcdpaC2BhfdjdjoCijrpiQszjhMr0ISuGzosssdg1rk4w1dr5"
                data("sender") = "SMARTLINK"
                data("to") = "+254730000"
                data("message") = "HELLO Mr THIS WAS SENT FROM software ITS WORKING"
                data("msgtype") = "5"
                data("dlr") = "0"
 

                Dim response = wb.UploadValues(url, "POST", data)
                Dim responseString As String = Encoding.UTF8.GetString(response)
            End Using
        Catch ex As Exception
 

        End Try
 

    End Sub
    Public Function checkBalance() As String
 

        Dim responseString As String = String.Empty
 

        Try
            ServicePointManager.Expect100Continue = True
            ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls Or SecurityProtocolType.Tls11 Or SecurityProtocolType.Tls12 Or SecurityProtocolType.Ssl3
 

            ServicePointManager.ServerCertificateValidationCallback =
      New RemoteCertificateValidationCallback(AddressOf AcceptAllCertifications)
 

            Dim url As String = "https://sms.movesms.co.ke/api/balance?"
            Using wb = New WebClient()
                Dim data = New NameValueCollection()
                data("api_key") = "TcdpaC2BhfdjdjoCijrpiQszjhMr0ISuGzosssdg1rk4w1dr5"
 

                Dim response = wb.UploadValues(url, "POST", data)
                responseString = Encoding.UTF8.GetString(response) 'SMS Balance: 1"
            End Using
 

        Catch ex As Exception
            responseString = ex.Message
        End Try
 

        Return responseString
 

    End Function
End Module
.NET Code Example
#main {
  
  string url = "https://sms.movesms.co.ke/API/";
string username = "yourusername";
string apiKey = "yourapikey";
string senderid = "yoursenderid"

Url url = new Url (url);

string data = "username =" + username + "& apiKey =" + apiKey + "& senderid ="senderid + "& smsData =      SHIPPER < / TPOA>   254722000000    ";

byte [] Buffer = System.Text.Encoding.UTF8.GetBytes (data);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create (uri);
request.Method = WebRequestMethods.Http.Post;
request.ContentLength = Buffer.Length;
request.ContentType = "application / x-www-form-urlencoded";

using (Stream writer = request.GetRequestStream ())
{
    writer.Write (Buffer, 0, Buffer.Length);
    writer.Flush ();
    writer.Close ();
}

HttpWebResponse response = (HttpWebResponse) request.GetResponse ();
StreamReader reader = new StreamReader (response.GetResponseStream ());
string tmp = reader.ReadToEnd ();
response.Close ();
Response.Write (tmp);
  
}
Send SMS in Ruby
<script> 
 require 'uri'
require 'net/http'

url = URI("https://www.sms.movesms.co.ke/API/")

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["content-type"] = 'application/x-www-form-urlencoded'
request["cache-control"] = 'no-cache'
request.body = "userId=YourUsername&password=YourPassword&senderId=SMSGAT&sendMethod=simpleMsg&msgType=text&mobile=919999999999%2C%20919999999998&msg=This%20is%20my%20first%20message%20with%20SMSGateway.Center&duplicateCheck=true&format=json"

response = http.request(request)
puts response.read_body
Send bulk SMS in Python Code Example
>>> x = int(input("
import http.client

conn = http.client.HTTPSConnection("www.sms.movesms.co.ke")

payload = "userId=user&password=userpass&senderId=SMSGAT&sendMethod=simpleMsg&msgType=text&mobile=254700123456&msg=This%20is%20my%20first%20message%20with%20MoveSMS&duplicateCheck=true&format=json&scheduleTime=2017-06-13%2020%3A22%3A00"

headers = {
    'apikey': "somerandomuniquekey",
    'content-type': "application/x-www-form-urlencoded",
    'cache-control': "no-cache"
    }

conn.request("POST", "/API", payload, headers)

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

print(data.decode("utf-8"))
Send SMS in PHP
<?php 


 CURLOPT_URL => "https://www.sms.movesms.co.ke/API/
             
  $postData = array(
                    'action' => 'compose',
                    'username' => $username,
                    'api_key' => $Key,
                    'sender' => $senderId,
                    'to' => $tophonenumber,
                    'message' => $finalmessage,
                    'msgtype' => $msgtype,
                    'dlr' => $dlr,
                );


                $ch = curl_init();
                curl_setopt_array($ch, array(
                    CURLOPT_URL => $url,
                    CURLOPT_RETURNTRANSFER => true,
                    CURLOPT_POST => true,
                    CURLOPT_POSTFIELDS => $postData

                ));

                curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
                curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);

                $output = curl_exec($ch);

                if (curl_errno($ch)) {
                    // echo 'error:' . curl_error($ch);
                    $output = curl_error($ch);
                }

                curl_close($ch);



?>
Send SMS in NodeJS
<?php 


var qs = require("querystring");
var http = require("https");

var options = {
  "method": "POST",
  "hostname": "www.sms.movesms.co.ke/",
  "port": null,
  "path": "/API",
  "headers": {
    "content-type": "application/x-www-form-urlencoded",
    "cache-control": "no-cache"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(qs.stringify({ userId: 'YourUsername',
  password: 'YourPassword',
  senderId: 'SMSGAT',
  sendMethod: 'simpleMsg',
  msgType: 'text',
  mobile: '254700123456, 254710123456',
  msg: 'This is my first message with SMSGateway.Center',
  duplicateCheck: 'true',
  format: 'json' }));
req.end();



?>
Perl Code Example
Handlebars.registerHelper('list', function(items, options) { 
  var out = "<ul>"; 
  
  for(var i=0, l=items.length; i<l; i++) { 
    out = out + "<li>" + options.fn(items[i]) + "</li>"; 
  } 
  
  return out + "</ul>"; 
  
 
  
});


use strict;
use LWP::Simple;
use LWP::UserAgent;
use URI::Escape;
use Getopt::Long;
use HTTP::Request::Common;
my %args;
GetOptions(
'help' => $args{help},
'smseagleip=s' => $args{smseagleip},
'user=s' => $args{user},
'password=s' => $args{password},
'dstnum=s' => $args{dstnum},
'msg=s' => $args{msg}
);
if(defined($args{help}) || !defined($args{smseagleip}) || !defined($args{user}) || !defined($args{password}) || !defined($args{dstnum}) || !defined($args{msg}) ) {
print "Usage: script_name.pl --smseagleip --user --password --dstnum --msg n";
exit(0);
}
my $text = uri_escape($args{msg});
my $baseurl = "http://".$args{smseagleip}.'/index.php/http_api/';
my $req = GET $baseurl."send_sms?login=$args{user}&pass=$args{password}&to=$args{dstnum}&message=$text";
my $ua = LWP::UserAgent->new();
my $rsp = $ua->request($req);
if($rsp->content == "OK") {
print "Message sent succesfully to $args{dstnum}n";
} else {
print "Sent failure: " . $rsp->content . "n";
}
Git Code Example
$ git add Documentation.txt

Bulk SMS API Tips

HTTP POST v/s HTTP GET

Though you can communicate with our REST API using both POST and GET methods, we recommend you to use POST method for better performance. Sample codes are given for both.

urlEncoding

If your messages seems to be garbled, make sure you are urlencoding the messaging while using GET method to deliver. URLENCODING IS NOT REQUIRED FOR POST METHOD, Hence we recommend using POST method.

Firewall Issues

Sometimes, it is possible that our firewall block non browser connections, if you face such issues, please contact us to whitelist your IP..

Incorrect Request URLs

Make sure you are using the correct HTTP headers or Request Parameters as required. Our app validation will show you the error to debug.

Errors

When certain parameters of the API URL are not entered correctly, you will receive a response from the URL stating the type of error. These error descriptions will help you to pin-point the erroneous parameter in the URL and rectify it. The common error codes received while using the API to send an SMS.

Errors
Error Types
# Error Code Message Solution
1 1701 Success You Have Successed
2 1702 Invalid URL Error Correct the API URL
3 1703 Invalid value in username or password field Check correct username or password
4 1704 Invalid value in " type " field Check correct type of message
5 1705 Invalid Message Check correct of message
6 1706 Invalid Destination Check correct Phone Values and format
7 1707 Invalid Source (Sender) No correct Sender ID approved
8 1708 1708:Invalid value for " dlr " field Check correct routing or country code
9 1709 User validation failed Validate User Correctly
10 1710 Internal Error Internal Error
11 1025 Insufficient Credit Add credit and refress your APP
12 1715 Response timeout Check Response time of your APP

Buttons

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi nec imperdiet turpis. Curabitur aliquet pulvinar ultrices. Etiam at posuere leo. Proin ultrices ex et dapibus feugiat link example aenean purus leo, faucibus at elit vel, aliquet scelerisque dui. Etiam quis elit euismod, imperdiet augue sit amet, imperdiet odio. Aenean sem erat, hendrerit eu gravida id, dignissim ut ante. Nam consequat porttitor libero euismod congue.

Video

Responsive Video 16:9
Responsive Video 4:3

Icons

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi nec imperdiet turpis. Curabitur aliquet pulvinar ultrices. Etiam at posuere leo. Proin ultrices ex et dapibus feugiat link example aenean purus leo, faucibus at elit vel, aliquet scelerisque dui. Etiam quis elit euismod, imperdiet augue sit amet, imperdiet odio. Aenean sem erat, hendrerit eu gravida id, dignissim ut ante. Nam consequat porttitor libero euismod congue.

Elegant Icon Font
elegant icons
FontAwesome Icon Font
fontawesome