NAV
shell ruby python javascript go java php

Generate Token

Before you begin API integrations you will have to generate authorization token. Below steps are outlined on how to generate authorization token. You need to create an account at InTouchVAS. Once you have the account ready, generate API Token via the below ndpoint

Authentication headers

Generate API endpoints accepts Basic Auth headers for authentication, you will need your account username and password to generate API Key

generated_auth=base64(username:password)

Authorization: Basic $generated_auth

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://identity-service.intouchvas.io/auth/api-key")

header = {'Content-Type': 'text/json','Authorization':'Basic [generated_auth]'}

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Get.new(uri.request_uri, header)

# Send the request
response = http.request(request)

import requests

newHeaders = {'Content-type': 'application/json', 'Authorization': 'Basic [generated_auth]'}


response = requests.get('https://identity-service.intouchvas.io/auth/api-key',headers=newHeaders)

print("Status code: ", response.status_code)

response_Json = response.json()
print("Printing Post JSON data")
print(response_Json['status'])
print(response_Json['message'])


curl --location --request GET 'https://identity-service.intouchvas.io/auth/api-key' \
--header 'Content-Type: application/json' \
--header 'api-key: Basic [generated_auth]' \


            // Creating a XHR object 
            let xhr = new XMLHttpRequest(); 
            let url = "https://identity-service.intouchvas.io/auth/api-key"; 

            // open a connection 
            xhr.open("GET", url, true); 

            // Set the request header i.e. which type of content you are sending 
            xhr.setRequestHeader("Content-Type","application/json"); 
            xhr.setRequestHeader("Authorization","Basic [generated_auth]"); 

            // Create a state change callback 
            xhr.onreadystatechange = function () { 
                if (xhr.readyState === 4 ) { 

                    // Print received data from server 
                    console.log(this.responseText.status); 
                    console.log(this.responseText.message); 
                } 
            }; 

            // Sending request 
            xhr.send(); 

package main

import (
  "bytes"
  "fmt"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {

  url := "https://identity-service.intouchvas.io/auth/api-key"
  method := "GET"


// make http request
  client := &http.Client {}
  req, err := http.NewRequest(method, url, nil)

  if err != nil {

    fmt.Println(err)
  }

  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Authorization", "Basic [generated_auth]")

  res, err := client.Do(req)
  if err != nil {

    fmt.Println(err)
  } 

  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import com.google.gson.Gson;

public class PostJSONWithHttpURLConnection {

    public static void main (String []args) throws IOException{

        URL url = new URL ("https://identity-service.intouchvas.io/auth/api-key");

        HttpURLConnection con = (HttpURLConnection)url.openConnection();
        con.setRequestMethod("GET");

        con.setRequestProperty("Content-Type", "application/json; utf-8");
        con.setRequestProperty("Accept", "application/json");
        con.setRequestProperty("Authorization", "Basic [generated_auth]");

        con.setDoOutput(true);


        int code = con.getResponseCode();
        System.out.println(code);

        try(BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream(), "utf-8"))){
            StringBuilder response = new StringBuilder();
            String responseLine = null;
            while ((responseLine = br.readLine()) != null) {
                response.append(responseLine.trim());
            }
            System.out.println(response.toString());
        }
    }

}


<?php

    $httpRequest = curl_init("https://identity-service.intouchvas.io/auth/api-key");
    curl_setopt($httpRequest,CURLOPT_TIMEOUT,60);
    curl_setopt($httpRequest,CURLOPT_RETURNTRANSFER,1);
    curl_setopt($httpRequest,CURLOPT_HTTPHEADER,array(
        "Content-Type:application/json",
        "Authorization: Basic [generated_auth]"
        )
    );
    curl_setopt($httpRequest,CURLOPT_RETURNTRANSFER,true);
    //curl_setopt($httpRequest,CURLOPT_HEADER,1);

    $response    = curl_exec($httpRequest);
    $status      = curl_getinfo($httpRequest,CURLINFO_HTTP_CODE);
    curl_close($httpRequest);
    echo $status;
    echo $response;

The above command returns JSON structured like this on success:

{
    "token": "API token",
    "lifetime": 1800
}

On failure the following is returned, referer to status codes for error types

{
    "status": 428,
    "message": "error message"
}

Token Response

The API returns JSON payload with the following

Key Required Data Type Default Description
token yes String none API Token
lifetime yes Integer none Token lifetime in seconds, this token expires after this number of seconds

SMS API Authentication headers

IntouchVAS Portal uses API key to allow access to the API.

api-key: secureapikeys

Bulk SMS APIs

Send Single SMS

Use this API to send single SMS or Same SMS upto 50 numbers at the same time. There are two main types of SMS

SMS Type Description
Transactional This are real time SMS like OTP and transaction confirmations
Promotional This is promotional and marketing SMS

Transactional SMS API Endpoint

POST /message/send/transactional

Query Input Parameters

The API expects a JSON payload with the following

Key Required Data Type Default Description
message yes String none message ro send
msisdn yes String true Recipient phone number. To send same SMS to more than 1 number separate multiple numbers with comma ( , )
sender_id no String INTOUCHVAS your registered sender ID
callback_url no String none Where DLR report will be send back

This endpoint expects JSON in the below format:

{
    "message": "message here",
    "msisdn": "+2547xxxxxxxx",
    "sender_id": "Intouchvas",
    "callback_url": "https://callback.io/123/dlr"
}

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://sms-service.intouchvas.io/message/send/transactional")

header = {'Content-Type': 'text/json','api-key':'secureapikeys'}
user = {
            message: 'message here',
            msisdn: '+2547xxxxxxxx',
            sender_id: 'INTOUCHVAS',
            callback_url: 'https://callback.io/123/dlr'
       }

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = user.to_json

# Send the request
response = http.request(request)

import requests

newHeaders = {'Content-type': 'application/json', 'api-key': 'secureapikeys'}
payload = {'message': 'message here','msisdn':'+2547xxxxxxxx','sender_id':'INTOUCHVAS','callback_url': 'https://callback.io/123/dlr'}

response = requests.post('https://sms-service.intouchvas.io/message/send/transactional',data=payload,headers=newHeaders)

print("Status code: ", response.status_code)

response_Json = response.json()
print("Printing Post JSON data")
print(response_Json['status'])
print(response_Json['message'])


curl --location --request POST 'https://sms-service.intouchvas.io/message/send/transactional' \
--header 'Content-Type: application/json' \
--header 'api-key: secureapikeys' \
--data-raw '{
    "message": "You message",
    "msisdn": "+2547xxxxxxxx",
    "sender_id": "INTOUCHVAS",
    "callback_url": "https://callback.io/123/dlr"
}'


            // Creating a XHR object 
            let xhr = new XMLHttpRequest(); 
            let url = "https://sms-service.intouchvas.io/message/send/transactional"; 

            // open a connection 
            xhr.open("POST", url, true); 

            // Set the request header i.e. which type of content you are sending 
            xhr.setRequestHeader("Content-Type","application/json"); 
            xhr.setRequestHeader("api-key","secureapikeys"); 

            // Create a state change callback 
            xhr.onreadystatechange = function () { 
                if (xhr.readyState === 4 ) { 

                    // Print received data from server 
                    console.log(this.responseText.status); 
                    console.log(this.responseText.message); 
                } 
            }; 

            var message = {
                "message": "message here",
                "msisdn": "+2547xxxxxxxx",
                "sender_id": "INTOUCHVAS",
                "callback_url": "https://callback.io/123/dlr",
            }

            // Converting JSON data to string 
            var data = JSON.stringify(message); 

            // Sending data with the request 
            xhr.send(data); 

package main

import (
  "bytes"
  "fmt"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {

  url := "http://sms-service.intouchvas.io/message/send/transactional"
  method := "POST"

// construct your message using interface
 message := map[string] interface{}{
    "message": "You message",
    "msisdn":"+2547xxxxxxxx",
    "sender_id":"INTOUCHVAS",
    "callback_url": "https://callback.io/123/dlr",
 }

 // convert to json
  payload,err := json.Marshal(message)
  if err != nil {

    fmt.Println(err)
  }

// make http request
  client := &http.Client {}
  req, err := http.NewRequest(method, url, bytes.NewBuffer(payload))

  if err != nil {

    fmt.Println(err)
  }

  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("api-key", "secureapikeys")

  res, err := client.Do(req)
  if err != nil {

    fmt.Println(err)
  } 

  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import com.google.gson.Gson;

public class PostJSONWithHttpURLConnection {

    public static void main (String []args) throws IOException{

        URL url = new URL ("https://sms-service.intouchvas.io/message/send/transactional");

        HttpURLConnection con = (HttpURLConnection)url.openConnection();
        con.setRequestMethod("POST");

        con.setRequestProperty("Content-Type", "application/json; utf-8");
        con.setRequestProperty("Accept", "application/json");
        con.setRequestProperty("api-key", "secureapikeys");

        con.setDoOutput(true);

        //JSON String need to be constructed for the specific resource. 
        Map<String, String> map = new LinkedHashMap<>();
        map.put("message","You message");
        map.put("msisdn","+2547xxxxxxxx");
        map.put("sender_id","INTOUCHVAS");
        map.put("callback_url","https://callback.io/123/dlr");
        Gson gson = new Gson();
        String jsonInputString = gson.toJson(map);

        try(OutputStream os = con.getOutputStream()){

            byte[] input = jsonInputString.getBytes("utf-8");
            os.write(input, 0, input.length);           
        }

        int code = con.getResponseCode();
        System.out.println(code);

        try(BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream(), "utf-8"))){
            StringBuilder response = new StringBuilder();
            String responseLine = null;
            while ((responseLine = br.readLine()) != null) {
                response.append(responseLine.trim());
            }
            System.out.println(response.toString());
        }
    }

}


<?php
    $message = [
        "message" => 'You message',
        "msisdn" => "+2547xxxxxxxx",
        "sender_id" => "INTOUCHVAS" ,
        "callback_url" => "https://callback.io/123/dlr"       
    ];

    $data_string = json_encode($message);
    $secureapikeys = "secureapikeys";

    $httpRequest = curl_init("https://sms-service.intouchvas.io/message/send/transactional");
    curl_setopt($httpRequest,CURLOPT_POST,true);
    curl_setopt($httpRequest,CURLOPT_POSTFIELDS,$data_string);
    curl_setopt($httpRequest,CURLOPT_TIMEOUT,60);
    curl_setopt($httpRequest,CURLOPT_RETURNTRANSFER,1);
    curl_setopt($httpRequest,CURLOPT_HTTPHEADER,array(
        "Content-Type:application/json",
        "api-key: $secureapikeys"
        )
    );
    curl_setopt($httpRequest,CURLOPT_RETURNTRANSFER,true);
    //curl_setopt($httpRequest,CURLOPT_HEADER,1);

    $response    = curl_exec($httpRequest);
    $status      = curl_getinfo($httpRequest,CURLINFO_HTTP_CODE);
    curl_close($httpRequest);
    echo $status;
    echo $response;

The above command returns JSON structured like this on success:

{
    "message": "SMS successfully queued for sending. Total recipients 1",
    "status": 200,
    "transaction_id": 2295
}

On failure the following is returned, referer to status codes for error types

{
    "status": 428,
    "message": "error message"
}

Promotional SMS API Endpoint

POST /message/send/promotional

Query Input Parameters

The API expects a JSON payload with the following

Key Required Data Type Default Description
message yes String none message ro send
msisdn yes String true Recipient phone number. To send same SMS to more than 1 number separate multiple numbers with comma ( , )
sender_id no String INTOUCHVAS your registered sender ID
callback_url no String none Where DLR report will be send back

This endpoint expects JSON in the below format:

{
    "message": "message here",
    "msisdn": "+2547xxxxxxxx",
    "sender_id": "Intouchvas",
    "callback_url": "https://callback.io/123/dlr"
}

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://sms-service.intouchvas.io/message/send/promotional")

header = {'Content-Type': 'text/json','api-key':'secureapikeys'}
user = {
            message: 'message here',
            msisdn: '+2547xxxxxxxx',
            sender_id: 'INTOUCHVAS',
            callback_url: 'https://callback.io/123/dlr'
       }

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = user.to_json

# Send the request
response = http.request(request)

import requests

newHeaders = {'Content-type': 'application/json', 'api-key': 'secureapikeys'}
payload = {'message': 'message here','msisdn':'+2547xxxxxxxx','sender_id':'INTOUCHVAS','callback_url': 'https://callback.io/123/dlr'}

response = requests.post('https://sms-service.intouchvas.io/message/send/promotional',data=payload,headers=newHeaders)

print("Status code: ", response.status_code)

response_Json = response.json()
print("Printing Post JSON data")
print(response_Json['status'])
print(response_Json['message'])


curl --location --request POST 'https://sms-service.intouchvas.io/message/send/promotional' \
--header 'Content-Type: application/json' \
--header 'api-key: secureapikeys' \
--data-raw '{
    "message": "You message",
    "msisdn": "+2547xxxxxxxx",
    "sender_id": "INTOUCHVAS",
    "callback_url": "https://callback.io/123/dlr"
}'


            // Creating a XHR object 
            let xhr = new XMLHttpRequest(); 
            let url = "https://sms-service.intouchvas.io/message/send/promotional"; 

            // open a connection 
            xhr.open("POST", url, true); 

            // Set the request header i.e. which type of content you are sending 
            xhr.setRequestHeader("Content-Type","application/json"); 
            xhr.setRequestHeader("api-key","secureapikeys"); 

            // Create a state change callback 
            xhr.onreadystatechange = function () { 
                if (xhr.readyState === 4 ) { 

                    // Print received data from server 
                    console.log(this.responseText.status); 
                    console.log(this.responseText.message); 
                } 
            }; 

            var message = {
                "message": "message here",
                "msisdn": "+2547xxxxxxxx",
                "sender_id": "INTOUCHVAS",
                "callback_url": "https://callback.io/123/dlr",
            }

            // Converting JSON data to string 
            var data = JSON.stringify(message); 

            // Sending data with the request 
            xhr.send(data); 

package main

import (
  "bytes"
  "fmt"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {

  url := "http://sms-service.intouchvas.io/message/send/promotional"
  method := "POST"

// construct your message using interface
 message := map[string] interface{}{
    "message": "You message",
    "msisdn":"+2547xxxxxxxx",
    "sender_id":"INTOUCHVAS",
    "callback_url": "https://callback.io/123/dlr",
 }

 // convert to json
  payload,err := json.Marshal(message)
  if err != nil {

    fmt.Println(err)
  }

// make http request
  client := &http.Client {}
  req, err := http.NewRequest(method, url, bytes.NewBuffer(payload))

  if err != nil {

    fmt.Println(err)
  }

  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("api-key", "secureapikeys")

  res, err := client.Do(req)
  if err != nil {

    fmt.Println(err)
  } 

  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import com.google.gson.Gson;

public class PostJSONWithHttpURLConnection {

    public static void main (String []args) throws IOException{

        URL url = new URL ("https://sms-service.intouchvas.io/message/send/promotional");

        HttpURLConnection con = (HttpURLConnection)url.openConnection();
        con.setRequestMethod("POST");

        con.setRequestProperty("Content-Type", "application/json; utf-8");
        con.setRequestProperty("Accept", "application/json");
        con.setRequestProperty("api-key", "secureapikeys");

        con.setDoOutput(true);

        //JSON String need to be constructed for the specific resource. 
        Map<String, String> map = new LinkedHashMap<>();
        map.put("message","You message");
        map.put("msisdn","+2547xxxxxxxx");
        map.put("sender_id","INTOUCHVAS");
        map.put("callback_url","https://callback.io/123/dlr");
        Gson gson = new Gson();
        String jsonInputString = gson.toJson(map);

        try(OutputStream os = con.getOutputStream()){

            byte[] input = jsonInputString.getBytes("utf-8");
            os.write(input, 0, input.length);           
        }

        int code = con.getResponseCode();
        System.out.println(code);

        try(BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream(), "utf-8"))){
            StringBuilder response = new StringBuilder();
            String responseLine = null;
            while ((responseLine = br.readLine()) != null) {
                response.append(responseLine.trim());
            }
            System.out.println(response.toString());
        }
    }

}


<?php
    $message = [
        "message" => 'You message',
        "msisdn" => "+2547xxxxxxxx",
        "sender_id" => "INTOUCHVAS" ,
        "callback_url" => "https://callback.io/123/dlr"       
    ];

    $data_string = json_encode($message);
    $secureapikeys = "secureapikeys";

    $httpRequest = curl_init("https://sms-service.intouchvas.io/message/send/promotional");
    curl_setopt($httpRequest,CURLOPT_POST,true);
    curl_setopt($httpRequest,CURLOPT_POSTFIELDS,$data_string);
    curl_setopt($httpRequest,CURLOPT_TIMEOUT,60);
    curl_setopt($httpRequest,CURLOPT_RETURNTRANSFER,1);
    curl_setopt($httpRequest,CURLOPT_HTTPHEADER,array(
        "Content-Type:application/json",
        "api-key: $secureapikeys"
        )
    );
    curl_setopt($httpRequest,CURLOPT_RETURNTRANSFER,true);
    //curl_setopt($httpRequest,CURLOPT_HEADER,1);

    $response    = curl_exec($httpRequest);
    $status      = curl_getinfo($httpRequest,CURLINFO_HTTP_CODE);
    curl_close($httpRequest);
    echo $status;
    echo $response;

The above command returns JSON structured like this on success:

{
    "message": "SMS successfully queued for sending. Total recipients 1",
    "status": 200,
    "transaction_id": 2295
}

On failure the following is returned, referer to status codes for error types

{
    "status": 428,
    "message": "error message"
}

Schedule SMS

This API supports SMS Scheduling, all scheduled SMS are treated as promotional SMS, you cannot schedule a transactional SMS, an SMS that has been scheduled will be queued to be send later

API Endpoint

POST /message/send/promotional

Query Input Parameters

The API expects a JSON payload with the following

Key Required Data Type Default Description
message yes String none message ro send
msisdn yes String true Recipient phone number. To send same SMS to more than 1 number separate multiple numbers with comma ( , )
country_code no String ke if this is not a kenya number, supply the country code
sender_id no String INTOUCHVAS your registered sender ID
callback_url no String none Where DLR report will be send back
schedule no Boolean false Is this SMS to be scheduled?
date no String none Date to send the SMS, date format YYYY-MM-DD
send_time no String none Time to send the SMS

This endpoint expects JSON in the below format:

{
    "message": "message here",
    "msisdn": "+2547xxxxxxxx",
    "sender_id": "INTOUCHVAS",
    "callback_url": "https://callback.io/123/dlr",
    "schedule": true,
    "date": "2030-01-01",
    "send_time": "09:30:01"
}

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://sms-service.intouchvas.io/message/send/promotional")

header = {'Content-Type': 'text/json','api-key':'secureapikeys'}
user = {
            message: 'message here',
            msisdn: '+2547xxxxxxxx',
            sender_id: 'INTOUCHVAS',
            callback_url: 'https://callback.io/123/dlr',
            schedule: true,
            date: '2030-01-01',
            send_time: '09:30:01'
       }

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = user.to_json

# Send the request
response = http.request(request)

import requests

newHeaders = {'Content-type': 'application/json', 'api-key': 'secureapikeys'}
payload = {'message': 'message here','msisdn':'+2547xxxxxxxx','sender_id':'INTOUCHVAS','callback_url': 'https://callback.io/123/dlr','schedule': true,'date':'2030-09-01','send_time':'09:30:01'}

response = requests.post('https://sms-service.intouchvas.io/message/send/promotional',data=payload,headers=newHeaders)

print("Status code: ", response.status_code)

response_Json = response.json()
print("Printing Post JSON data")
print(response_Json['status'])
print(response_Json['message'])


curl --location --request POST 'https://sms-service.intouchvas.io/message/send/promotional' \
--header 'Content-Type: application/json' \
--header 'Authorization: secureapikeys' \
--data-raw '{
    "message": "You message",
    "msisdn": "+2547xxxxxxxx",
    "sender_id": "INTOUCHVAS",
    "callback_url": "https://callback.io/123/dlr",
    "schedule": true,
    "date": "2030-01-01",
    "send_time": "09:30:01"
}'


            // Creating a XHR object 
            let xhr = new XMLHttpRequest(); 
            let url = "https://sms-service.intouchvas.io/message/send/promotional"; 

            // open a connection 
            xhr.open("POST", url, true); 

            // Set the request header i.e. which type of content you are sending 
            xhr.setRequestHeader("Content-Type","application/json"); 
            xhr.setRequestHeader("api-key","secureapikeys"); 

            // Create a state change callback 
            xhr.onreadystatechange = function () { 
                if (xhr.readyState === 4 ) { 

                    // Print received data from server 
                    console.log(this.responseText.status); 
                    console.log(this.responseText.message); 
                } 
            }; 

            var message = {
                "message": "message here",
                "msisdn": "+2547xxxxxxxx",
                "sender_id": "INTOUCHVAS",
                "callback_url": "https://callback.io/123/dlr",
                "schedule": true,
                "date": "2030-01-01",
                "send_time": "09:30:01",
            }

            // Converting JSON data to string 
            var data = JSON.stringify(message); 

            // Sending data with the request 
            xhr.send(data); 

package main

import (
  "bytes"
  "fmt"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {

  url := "http://sms-service.intouchvas.io/message/send/promotional"
  method := "POST"

// construct your message using interface
 message := map[string] interface{}{
    "message": "You message",
    "msisdn":"+2547xxxxxxxx",
    "sender_id":"INTOUCHVAS",
    "callback_url": "https://callback.io/123/dlr",
    "schedule": true,
    "date": "2030-01-01",
    "send_time": "09:30:01",
 }

 // convert to json
  payload,err := json.Marshal(message)
  if err != nil {

    fmt.Println(err)
  }

// make http request
  client := &http.Client {}
  req, err := http.NewRequest(method, url, bytes.NewBuffer(payload))

  if err != nil {

    fmt.Println(err)
  }

  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("api-key", "secureapikeys")

  res, err := client.Do(req)
  if err != nil {

    fmt.Println(err)
  } 

  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import com.google.gson.Gson;

public class PostJSONWithHttpURLConnection {

    public static void main (String []args) throws IOException{

        URL url = new URL ("https://sms-service.intouchvas.io/message/send/promotional");

        HttpURLConnection con = (HttpURLConnection)url.openConnection();
        con.setRequestMethod("POST");

        con.setRequestProperty("Content-Type", "application/json; utf-8");
        con.setRequestProperty("Accept", "application/json");
        con.setRequestProperty("api-key", "secureapikeys");

        con.setDoOutput(true);

        //JSON String need to be constructed for the specific resource. 
        Map<String, String> map = new LinkedHashMap<>();
        map.put("message","You message");
        map.put("msisdn","+2547xxxxxxxx");
        map.put("sender_id","INTOUCHVAS");
        map.put("callback_url","https://callback.io/123/dlr");
        map.put("schedule",true);
        map.put("date","2030-01-01");
        map.put("send_time","09:30:01");

        Gson gson = new Gson();
        String jsonInputString = gson.toJson(map);

        try(OutputStream os = con.getOutputStream()){

            byte[] input = jsonInputString.getBytes("utf-8");
            os.write(input, 0, input.length);           
        }

        int code = con.getResponseCode();
        System.out.println(code);

        try(BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream(), "utf-8"))){
            StringBuilder response = new StringBuilder();
            String responseLine = null;
            while ((responseLine = br.readLine()) != null) {
                response.append(responseLine.trim());
            }
            System.out.println(response.toString());
        }
    }

}


<?php
    $message = [
        "message" => 'You message',
        "msisdn" => "+2547xxxxxxxx",
        "sender_id" => "INTOUCHVAS" ,
        "callback_url" => "https://callback.io/123/dlr"       
    ];

    $data_string = json_encode($message);
    $secureapikeys = "secureapikeys";

    $httpRequest = curl_init("https://sms-service.intouchvas.io/message/send/promotional");
    curl_setopt($httpRequest,CURLOPT_POST,true);
    curl_setopt($httpRequest,CURLOPT_POSTFIELDS,$data_string);
    curl_setopt($httpRequest,CURLOPT_TIMEOUT,60);
    curl_setopt($httpRequest,CURLOPT_RETURNTRANSFER,1);
    curl_setopt($httpRequest,CURLOPT_HTTPHEADER,array(
        "Content-Type:application/json",
        "api-key: $secureapikeys"
        )
    );
    curl_setopt($httpRequest,CURLOPT_RETURNTRANSFER,true);
    //curl_setopt($httpRequest,CURLOPT_HEADER,1);

    $response    = curl_exec($httpRequest);
    $status      = curl_getinfo($httpRequest,CURLINFO_HTTP_CODE);
    curl_close($httpRequest);
    echo $status;
    echo $response;

The above command returns JSON structured like this on success:

{
    "message": "SMS successfully queued for sending. Total recipients 1",
    "status": 200,
    "transaction_id": 2295
}

On failure the following is returned, referer to status codes for error types

{
    "status": 428,
    "message": "error message"
}

File Upload

This API allows you to upload recipients in a file

API Endpoint

FORM POST /message/send/upload-file

Simple SMS Content

Simple SMS allows you to send the same SMS to many users by upload a file of file numbers. This endpoint provides an interface to upload contacts in a file.

file format

You can only upload a CSV file The first row will in the file will be treated as headers.

basic format

The first column is expected to be the phone numbers example below

msisdn
+2547xxxxxxx0
+2547xxxxxxx1
+2547xxxxxxx2
+2547xxxxxxx3
+2547xxxxxxx4

Input Form Fields

The API expects a FORM POST with the following

Key Required Data Type Default Description
message yes String none message ro send
country_code no String ke if this are not a kenya phone numbers, supply the country code
sender_id no String IntouchVAS your registered sender ID
file yes File File to be uploaded
campaign_name no String Name of Campaign, contact group
schedule no Boolean false Is this SMS to be scheduled?
date no String none Date to send the SMS, date format YYYY-MM-DD
send_time no String none Time to send the SMS 
require "uri"
require "net/http"

url = URI("https://sms-service.intouchvas.io/message/send/upload-file")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-key"] = "secureapikeys"
form_data = [
    ['message', 'test SMS to {msisdn}'],
    ['sender_id', 'InTouchVAS'],
    ['campaign_name', 'test'],
    ['callback_url', 'https://intouchvas.io'],
    ['file', File.open('/Users/user1/Downloads/template (10).csv')]
]
request.set_form form_data, 'multipart/form-data'
response = https.request(request)
puts response.read_body



import requests

url = "https://sms-service.intouchvas.io/message/send/upload-file"

payload={'message': 'test SMS to [msisdn]',
'sender_id': 'InTouchVAS',
'campaign_name': 'test',
'callback_url': 'https://intouchvas.io'}
files=[
  ('file',('template (10).csv',open('/Users/user1/Downloads/template (10).csv','rb'),'text/csv'))
]
headers = {
  'api-key': 'secureapikeys'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)

curl --location --request POST 'https://sms-service.intouchvas.io/message/send/upload-file' \
--header 'api-key: secureapikeys=' \
--form 'message="test SMS to [msisdn]"' \
--form 'sender_id="InTouchVAS"' \
--form 'campaign_name="test"' \
--form 'callback_url="https://intouchvas.io"' \
--form 'file=@"/Users/user1/Downloads/template (10).csv"'


            var data = new FormData();
            data.append("message", "test SMS to [msisdn]");
            data.append("sender_id", "InTouchVAS");
            data.append("campaign_name", "test");
            data.append("callback_url", "https://intouchvas.io");
            data.append("file", fileInput.files[0], "template (10).csv");

            var xhr = new XMLHttpRequest();
            xhr.withCredentials = true;

            xhr.addEventListener("readystatechange", function() {
              if(this.readyState === 4) {
                console.log(this.responseText);
              }
            });

            xhr.open("POST", "https://sms-service.intouchvas.io/message/send/upload-file");
            xhr.setRequestHeader("api-key", "secureapikeys");

            xhr.send(data);

package main

import (
  "fmt"
  "bytes"
  "mime/multipart"
  "os"
  "path/filepath"
  "io"
  "net/http"
  "io/ioutil"
  "log"
)

func main() {

      endpoint := "https://sms-service.intouchvas.io/message/send/upload-file"
      method := "POST"

      csvFileToUpload := "/full/path/of/the/file.extension"

      // your form fields
      formFields := map[string]string{
        "message":       "test SMS to [msisdn]",
        "sender_id":      "InTouchVAS",
        "campaign_name": "Bulk SMS",
        "callback_url": "https://callback.io/dlr",
      }   

     // open file for reading   
     file, err := os.Open(csvFileToUpload)
     if err != nil {

        fmt.Println(err)
        return
     }

     defer file.Close()


     body := &bytes.Buffer{}
     writer := multipart.NewWriter(body)
     part, err := writer.CreateFormFile("file", filepath.Base(csvFileToUpload))
     if err != nil {

        fmt.Println(err)
        return
     }

     _, err = io.Copy(part, file)

    for key, val := range formFields {

        _ = writer.WriteField(key, val)
    }

    err = writer.Close()
    if err != nil {
        fmt.Println(err)
        return
    }

    req, err := http.NewRequest(method, endpoint, body)
    if err != nil {
        fmt.Println(err)
        return
    }

    req.Header.Set("Content-Type", writer.FormDataContentType())
    req.Header.Set("api-key", "secureapikeys")

    client := &http.Client {}
    res, err := client.Do(req)
    if err != nil {
        fmt.Println(err)
        return
    }
    defer res.Body.Close()

   body, err = ioutil.ReadAll(res.Body)
   if err != nil {
    fmt.Println(err)
    return
  }

  fmt.Println(string(body))
}

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import com.google.gson.Gson;

public class PostJSONWithHttpURLConnection {

    public static void main (String []args) throws IOException{

        OkHttpClient client = new OkHttpClient().newBuilder()
          .build();
        MediaType mediaType = MediaType.parse("text/plain");
        RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
          .addFormDataPart("message","test SMS to [msisdn]")
          .addFormDataPart("sender_id","InTouchVAS")
          .addFormDataPart("campaign_name","test")
          .addFormDataPart("callback_url","https://intouchvas.io")
          .addFormDataPart("file","template (10).csv",
            RequestBody.create(MediaType.parse("application/octet-stream"),
            new File("/Users/user1/Downloads/template (10).csv")))
          .build();
        Request request = new Request.Builder()
          .url("https://sms-service.intouchvas.io/message/send/upload-file")
          .method("POST", body)
          .addHeader("api-key", "secureapikeys")
          .build();
        Response response = client.newCall(request).execute();
    }

}


<?php
$curl = curl_init();


curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://sms-service.intouchvas.io/message/send/upload-file',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array(
        'message' => 'test SMS to [msisdn]',
        'sender_id' => 'InTouchVAS',
        'campaign_name' => 'test',
        'callback_url' => 'https://intouchvas.io',
        'file'=> new CURLFILE('/Users/user1/Downloads/template (10).csv')
    ),
  CURLOPT_HTTPHEADER => array(
    'api-key: secureapikeys'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

The above command returns JSON structured like this on success:

{
    "message": "SMS successfully queued for sending. Total recipients 10000",
    "status": 200,
    "transaction_id": 2295
}

On failure the following is returned, refere to status codes for error types

{
    "status": 428,
    "message": "error message"
}

File Upload - SMS Customization

This API allows you to upload recipients in a file and further customize SMS per recipient

API Endpoint

FORM POST /message/send/upload-file

This API allows you to send custom sms to a batch of contacts in a file e.g when sending school fees balance where you want to customize sms for every parent to pick the required fee balance.

1. step 1

When creating a file in this category, the 1st column remains to be phone number, the subsequent columns will be the replacement parameters. example you want to send sms to parents you want sms to go out with student name, fee balance and adminission number. Your file will have the below format. The 1st column will be treated as headers

msisdn name admission balance
2547xxxxxxx0 John Doe adm/01 1000
2547xxxxxxx1 Alice Bobby adm/02 1000
2547xxxxxxx2 Ruby Rose adm/03 1000
2547xxxxxxx3 George Nim adm/04 1000
2547xxxxxxx4 Lucas Madona adm/05 1000

You can have as many columns and rows the only limit will be file size, your file should be below 100MB

2. step 2

Compose your sms to include column header name wrapped in square brackets [ and ] example to use name in SMS we use [name] back to our example above our sms will look like the following

Dear parent your student [name] has a fee balance of [balance]. Please pay your fees through paybill 89544 account [admission] thank you

The above will be your sms contents, the system will go through the file row by row replacing SMS parameters with values in the file in that column. Each recipient will receive a customized SMS

URL Parameters

This endpoint accepts form data with the below fields

Key Required Data Type Default Description
message yes String none message to send
country_code no String ke if this are not a kenya phone numbers, supply the country code
sender_id no String IntouchVAS your registered sender ID
file yes File File to be uploaded
campaign_name no String Name of Campaign, contact group
schedule no Boolean false Is this SMS to be scheduled?
date no String none Date to send the SMS, date format YYYY-MM-DD
send_time no String none Time to send the SMS 
require "uri"
require "net/http"

url = URI("https://sms-service.intouchvas.io/message/send/upload-file")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-key"] = "secureapikeys"
form_data = [
    ['message', 'test SMS to {msisdn}'],
    ['sender_id', 'InTouchVAS'],
    ['campaign_name', 'test'],
    ['callback_url', 'https://intouchvas.io'],
    ['file', File.open('/Users/user1/Downloads/template (10).csv')]
]
request.set_form form_data, 'multipart/form-data'
response = https.request(request)
puts response.read_body



import requests

url = "https://sms-service.intouchvas.io/message/send/upload-file"

payload={'message': 'test SMS to [msisdn]',
'sender_id': 'InTouchVAS',
'campaign_name': 'test',
'callback_url': 'https://intouchvas.io'}
files=[
  ('file',('template (10).csv',open('/Users/user1/Downloads/template (10).csv','rb'),'text/csv'))
]
headers = {
  'api-key': 'secureapikeys'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)

curl --location --request POST 'https://sms-service.intouchvas.io/message/send/upload-file' \
--header 'api-key: secureapikeys=' \
--form 'message="test SMS to [msisdn]"' \
--form 'sender_id="InTouchVAS"' \
--form 'campaign_name="test"' \
--form 'callback_url="https://intouchvas.io"' \
--form 'file=@"/Users/user1/Downloads/template (10).csv"'


            var data = new FormData();
            data.append("message", "test SMS to [msisdn]");
            data.append("sender_id", "InTouchVAS");
            data.append("campaign_name", "test");
            data.append("callback_url", "https://intouchvas.io");
            data.append("file", fileInput.files[0], "template (10).csv");

            var xhr = new XMLHttpRequest();
            xhr.withCredentials = true;

            xhr.addEventListener("readystatechange", function() {
              if(this.readyState === 4) {
                console.log(this.responseText);
              }
            });

            xhr.open("POST", "https://sms-service.intouchvas.io/message/send/upload-file");
            xhr.setRequestHeader("api-key", "secureapikeys");

            xhr.send(data);

package main

import (
  "fmt"
  "bytes"
  "mime/multipart"
  "os"
  "path/filepath"
  "io"
  "net/http"
  "io/ioutil"
  "log"
)

func main() {

      endpoint := "https://sms-service.intouchvas.io/message/send/upload-file"
      method := "POST"

      csvFileToUpload := "/full/path/of/the/file.extension"

      // your form fields
      formFields := map[string]string{
        "message":       "test SMS to [msisdn]",
        "sender_id":      "InTouchVAS",
        "campaign_name": "Bulk SMS",
        "callback_url": "https://callback.io/dlr",
      }   

     // open file for reading   
     file, err := os.Open(csvFileToUpload)
     if err != nil {

        fmt.Println(err)
        return
     }

     defer file.Close()


     body := &bytes.Buffer{}
     writer := multipart.NewWriter(body)
     part, err := writer.CreateFormFile("file", filepath.Base(csvFileToUpload))
     if err != nil {

        fmt.Println(err)
        return
     }

     _, err = io.Copy(part, file)

    for key, val := range formFields {

        _ = writer.WriteField(key, val)
    }

    err = writer.Close()
    if err != nil {
        fmt.Println(err)
        return
    }

    req, err := http.NewRequest(method, endpoint, body)
    if err != nil {
        fmt.Println(err)
        return
    }

    req.Header.Set("Content-Type", writer.FormDataContentType())
    req.Header.Set("api-key", "secureapikeys")

    client := &http.Client {}
    res, err := client.Do(req)
    if err != nil {
        fmt.Println(err)
        return
    }
    defer res.Body.Close()

   body, err = ioutil.ReadAll(res.Body)
   if err != nil {
    fmt.Println(err)
    return
  }

  fmt.Println(string(body))
}

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import com.google.gson.Gson;

public class PostJSONWithHttpURLConnection {

    public static void main (String []args) throws IOException{

        OkHttpClient client = new OkHttpClient().newBuilder()
          .build();
        MediaType mediaType = MediaType.parse("text/plain");
        RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
          .addFormDataPart("message","test SMS to [msisdn]")
          .addFormDataPart("sender_id","InTouchVAS")
          .addFormDataPart("campaign_name","test")
          .addFormDataPart("callback_url","https://intouchvas.io")
          .addFormDataPart("file","template (10).csv",
            RequestBody.create(MediaType.parse("application/octet-stream"),
            new File("/Users/user1/Downloads/template (10).csv")))
          .build();
        Request request = new Request.Builder()
          .url("https://sms-service.intouchvas.io/message/send/upload-file")
          .method("POST", body)
          .addHeader("api-key", "secureapikeys")
          .build();
        Response response = client.newCall(request).execute();
    }

}


<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://sms-service.intouchvas.io/message/send/upload-file',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array(
        'message' => 'test SMS to [msisdn]',
        'sender_id' => 'InTouchVAS',
        'campaign_name' => 'test',
        'callback_url' => 'https://intouchvas.io',
        'file'=> new CURLFILE('/Users/user1/Downloads/template (10).csv')
    ),
  CURLOPT_HTTPHEADER => array(
    'api-key: secureapikeys'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

The above command returns JSON structured like this on success:

{
    "message": "SMS successfully queued for sending. Total recipients 10000",
    "status": 200,
    "transaction_id": 2295
}

On failure the following is returned, refere to status codes for error types

{
    "status": 428,
    "message": "error message"
}

SMS Delivery Report

When you send a Bulk SMS and add delivery callback_url, IntouchVAS will send you SMS status when its done processing, SMS is considered done processing when it either fails or is successfully delivered to the recipient.

DLR fields

Name Data Type Description
msisdn string Phone number
status Integer see DLR Status section
status_description String Description of the status field
country String Recipient Country
network String Recipient Telcom Network
transaction_id String Message Transaction ID

Sample DLR JSON 

{
    "msisdn": "254710XXXXXX",
    "status": 3,
    "country": "ke",
    "network": "Safaricom",
    "status_description": "Delivered To Teminal",
    "transaction_id": 2295
}
```Dawsons-MacBook-Pro:slate phil$     You don't have write permissions for the /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/gems/2.6.0 directory.

Errors

The IntouchVAS SMS API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The data requested is hidden for administrators only.
404 Not Found -- The specified data could not be found.
405 Method Not Allowed -- You tried to access a data with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
418 Invalid Parameters supplied.
421 Invalid Parameters supplied.
422 Invalid Parameters supplied.
428 Invalid API Key or session expired.
429 Too Many Requests
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

SMS Delivery Status

The InTouchVAS SMS API will the following DLR status:

Status Meaning
0 Failed, SMS was not send to Telco. This occurs due to billing issues
1 Failed, SMS was not send to Telco. This
2 Pending. SMS was send to Telco but Telco did not send back delivery status
3 Delivered. SMS Delivered to Phone
shell ruby python javascript go java php