Introduction

This documentation will provide instructions on how to quickly integrate SMS services into various solutions using the HTTP API.

Our API is based on REST standards. In order to interact with our API, any client HTTP in any programming language can be used.

The documentation is intuitive and written with the developers in mind.

Prerequisites

In order to use our API, you will need identification information. These are not only used for the API but also for other services such as your customer area.

Base URL

Although you can use the HTTP protocol, we strongly recommend that you submit all your requests to the SMS API API via HTTPS so that the traffic is encrypted and confidentiality is ensured.
URL de base :

Phone number format

We use number formatting E.164 which is internationally standardized. Telephone numbers are generally preceded by a + (plus) sign, followed by the country code, network code and subscriber number.

Indicatif Phone number
225 09000001

Nous n'envoyons des méssages qu'à des numéro de téléphone valide (numéros), écrit en format international par ex. 22509000001, 22377000010

Check the balance statement

POST : https://vavasms.com/api/v1/check/balance

Settings

Name Type Description
username string the email of your account
password string the password of your account

Sample query
                                    
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://vavasms.com/api/v1/check/balance",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "username=your_email&password=your_password",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
                                    
                                
                                    
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "username=your_email&password=your_password");
Request request = new Request.Builder()
  .url("https://vavasms.com/api/v1/check/balance")
  .method("POST", body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .build();
Response response = client.newCall(request).execute();
                                    
                                
                                    
var settings = {
  "url": "https://vavasms.com/api/v1/check/balance",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  "data": {
    "username": "your_email",
    "password": "your_password"
  }
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
                                    
                                
                                    
var request = require("request");

var options = { method: 'POST',
  url: 'https://vavasms.com/api/v1/check/balance',
  headers:
   {'cache-control': 'no-cache',
     'Host': 'vavasms.com',
     'Content-Type': 'application/x-www-form-urlencoded'},
  form: { username: 'your_email', password: 'your_password' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});
                                    
                                
                                    
import http.client
import mimetypes
conn = http.client.HTTPSConnection("vavasms.com")
payload = 'username=your_email&password=your_password'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}
conn.request("POST", "/api/v1/check/balance", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
                                    
                                
                                    
var client = new RestClient("https://vavasms.com/api/v1/check/balance");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("username", "your_email");
request.AddParameter("password", "your_password");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Success story example
                            
{
    "code": 0,
    "message": "OPERATION_SUCCES",
    "data": {
        "amount": 25540,
        "currency": "XOF"
    }
}

Example of failure case
                            
{
    "code": 901,
    "message": "INVALID_CREDENTIALS",
    "description": "Identifiant de connexion incorrect",
    "data": []
}

NB: The balance is in XOF (XOF)

Outgoing messages

By default, your username is your SENDER_ID , but you can request more SENDER_ID in your account.

Send a message

POST : https://vavasms.com/api/v1/text/single

Settings

Name Type Description
username string the email of your account
password string the password of your account
sender_id string The length of the alphanumeric sender_id must be between 3 and 11 characters (example: <code> CompanyName </ code>).
phone string The number (s) of destination of the message. Separated by commas if you want to send to multiple phone number
Example of sending to one contact : 22509000001
Example of sending to multiple contacts: 22509000001,22509000002
message string Text of the message that will be sent.

Sample query
                                    
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://vavasms.com/api/v1/text/single",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "username=your_email&password=your_password&sender_id=your_sender_id&phone=your_receiver_phone_number&message=your_message_here",
  CURLOPT_HTTPHEADER => array(
    "Accept: */*",
    "Content-Type: application/x-www-form-urlencoded",
    "Host: vavasms.com"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
                                    
                                

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "username=your_email&password=your_password&sender_id=your_sender_id&phone=your_receiver_phone_number&message=your_message_here");
Request request = new Request.Builder()
  .url("https://vavasms.com/api/v1/text/single")
  .post(body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .addHeader("Accept", "*/*")
  .addHeader("Host", "vavasms.com")
  .build();
Response response = client.newCall(request).execute();
                                    

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://vavasms.com/api/v1/text/single",
  "method": "POST",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded",
    "Accept": "*/*",
    "Host": "vavasms.com"
  },
  "data": {
    "username": "your_email",
    "password": "your_password",
    "sender_id": "your_sender_id",
    "phone": "your_receiver_phone_number",
    "message": "your_message_here"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});
                                    

var request = require("request");

var options = { method: 'POST',
  url: 'https://vavasms.com/api/v1/text/single',
  headers:
   { 'Host': 'vavasms.com',
     'Accept': '*/*',
     'Content-Type': 'application/x-www-form-urlencoded' },
  form:
   { username: 'your_email',
     password: 'your_password',
     sender_id: 'your_sender_id',
     phone: 'your_receiver_phone_number',
     message: 'your_message_here' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

                                    

import http.client

conn = http.client.HTTPConnection("vavasms.com")

payload = "username=your_email&password=your_password&sender_id=your_sender_id&phone=your_receiver_phone_number&message=your_message_here"

headers = {
    'Content-Type': "application/x-www-form-urlencoded",
    'Accept': "*/*",
    'Host': "vavasms.com"
}

conn.request("POST", "api,v1,text,single", payload, headers)

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

print(data.decode("utf-8"))

Success story example
        
{
    "code": 0,
    "message": "OPERATION_SUCCES",
    "data": {
        "lot_id": "LOT-20190623-1217676",
        "description": "Message envoyé avec succès",
        "message_id": [
            "SM-20190623-1217879"
        ]
    }
}

Example of failure case
{
    "code": "901",
    "status": "INVALID_CREDENTIALS",
    "description": "Identifiant de connexion incorrect",
}
{
    "code": "902",
    "status": "INVALID_SENDER_ID",
    "description": "Le sender_id n’existe pas",
}
{
    "code": "903",
    "status": "INVALID_PHONE_NUMBER",
    "description": "Le format du numéro de téléphone est invalide",
}

Check the status of a sent message

POST : https://vavasms.com/api/v1/check/status

Settings

Name Type Description
username string the email of your account
password string the password of your account
message_id string The mesage identifier Ex : RMA029VA222991919
lot_id string | optional The batch identifier Ex : RMA029VA222991919

Sample query

Success story example
        
{
    "code": 0,
    "message": "OPERATION_SUCCES",
    "data": [
        {
            "lot_id": "LOT-20190617-1445425",
            "message_id": "SM-20190617-1445914",
            "status": "sent",
            "description": "Envoyé"
        }
    ]
}

Example of failure case
{
    "code": "901",
    "status": "INVALID_CREDENTIALS",
    "description": "Identifiant de connexion incorrect",
}
{
    "code": "709",
    "message": "EXECUTION_ERROR",
    "description": "Aucun envoi existe pour ce ID",
    "data": []
}

Receiving a Message

Notification URL

The notification link is the one called by the platform to notify you of the receipt of an SMS and its content. This URL must be available to host HTTP requests of type POST.
You must configure your notification url in your back office

Settings

Name Type Description
message_id string the message identifier
form string The sender of the SMS
content string the content of the message
sms_date string the date of receipt of the SMS

URL de Notification

POST : https://{your_notification_url.com}

OTP Code: Send and Verify

Envoyer un code OTP

POST : https://vavasms.com/api/v1/otp/send

Settings

Name Type Description
username string the email of your account
password string the password of your account
sender_id string La longueur du sender_id alphanumérique doit être comprise
entre 3 et 11 caractères (exemple : CompanyName).
otp_length integer La longueur de l'OTP à generer. doit être comprise entre 4 et 9
par defaut : 4.
otp_expiry integer La durée de l'OTP à verifier en minute.
par défaut : 60
phone string Le numéro de destination du message qui reçoit le code OTP.
Exemple d'envoi à un contact : 22509000001
message string Texte du message qui sera envoyé. le message doit comporter la balise ##OTP##
Par defaut, le message est : Votre code OTP est : ##OTP##

Sample query
                                    
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://vavasms.com/api/v1/otp/send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "username=your_email&password=your_password&sender_id=your_sender_id&phone=your_receiver_phone_number",
  CURLOPT_HTTPHEADER => array(
    "Accept: */*",
    "Content-Type: application/x-www-form-urlencoded",
    "Host: vavasms.com"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
                                    
                                

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "username=your_email&password=your_password&sender_id=your_sender_id&phone=your_receiver_phone_number");
Request request = new Request.Builder()
  .url("https://vavasms.com/api/v1/otp/send")
  .post(body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .addHeader("Accept", "*/*")
  .addHeader("Host", "vavasms.com")
  .build();
Response response = client.newCall(request).execute();
                                    

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://vavasms.com/api/v1/otp/send",
  "method": "POST",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded",
    "Accept": "*/*",
    "Host": "vavasms.com"
  },
  "data": {
    "username": "your_email",
    "password": "your_password",
    "sender_id": "your_sender_id",
    "phone": "your_receiver_phone_number"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});
                                    

var request = require("request");

var options = { method: 'POST',
  url: 'https://vavasms.com/api/v1/otp/send',
  headers:
   { 'Host': 'vavasms.com',
     'Accept': '*/*',
     'Content-Type': 'application/x-www-form-urlencoded' },
  form:
   { username: 'your_email',
     password: 'your_password',
     sender_id: 'your_sender_id',
     phone: 'your_receiver_phone_number' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

                                    

var request = require("request");

var options = { method: 'POST',
  url: 'https://vavasms.com/api/v1/otp/send',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  form:
   { username: 'your_email',
     password: 'your_password',
     sender_id: 'your_sender_id',
     phone: 'your_receiver_phone_number' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Success story example
        
{
    "code": 0,
    "message": "OPERATION_SUCCES",
    "data": {
        "message_id": "OTP-20190621-2234509",
        "description": "OTP envoyé avec succès"
    }
}

Example of failure case
{
    "code": "901",
    "status": "INVALID_CREDENTIALS",
    "description": "Identifiant de connexion incorrect",
}
{
    "code": "902",
    "status": "INVALID_SENDER_ID",
    "description": "Le sender_id n’existe pas",
}
{
    "code": "903",
    "status": "INVALID_PHONE_NUMBER",
    "description": "Le format du numéro de téléphone est invalide",
}


Verifier et valider un code OTP

POST : https://vavasms.com/api/v1/otp/verify

Settings

Name Type Description
username string the email of your account
password string the password of your account
otp integer Le code OTP à verifier.
phone string Le numéro de téléphone qui a reçu le code OTP.
Exemple d'envoi à un contact : 22509000001

Sample query
                                    
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://vavasms.com/api/v1/otp/verify",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "username=your_email&password=your_password&sender_id=your_sender_id&phone=your_receiver_phone_number&otp=otp_received",
  CURLOPT_HTTPHEADER => array(
    "Accept: */*",
    "Content-Type: application/x-www-form-urlencoded",
    "Host: vavasms.com"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
                                    
                                

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "username=your_email&password=your_password&sender_id=your_sender_id&phone=your_receiver_phone_number&otp=otp_received");
Request request = new Request.Builder()
  .url("https://vavasms.com/api/v1/otp/verify")
  .post(body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .addHeader("Accept", "*/*")
  .addHeader("Host", "vavasms.com")
  .build();
Response response = client.newCall(request).execute();
                                    

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://vavasms.com/api/v1/otp/verify",
  "method": "POST",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded",
    "Accept": "*/*",
    "Host": "vavasms.com"
  },
  "data": {
    "username": "your_email",
    "password": "your_password",
    "sender_id": "your_sender_id",
    "phone": "your_receiver_phone_number",
    "otp": "otp_received",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});
                                    

var request = require("request");

var options = { method: 'POST',
  url: 'https://vavasms.com/api/v1/otp/verify',
  headers:
   { 'Host': 'vavasms.com',
     'Accept': '*/*',
     'Content-Type': 'application/x-www-form-urlencoded' },
  form:
   { username: 'your_email',
     password: 'your_password',
     sender_id: 'your_sender_id',
     otp: 'otp_received',
     phone: 'your_receiver_phone_number' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

                                    

var request = require("request");

var options = { method: 'POST',
  url: 'https://vavasms.com/api/v1/otp/verify',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  form:
   { username: 'your_email',
     password: 'your_password',
     sender_id: 'your_sender_id',
     otp: 'otp_received',
     phone: 'your_receiver_phone_number' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Success story example
        
{
    "code": 0,
    "message": "OPERATION_SUCCES",
    "data": {
        "message_id": "OTP-20190621-2250698",
        "status": "success"
    }
}

Example of failure case

{
    "code": "901",
    "status": "INVALID_CREDENTIALS",
    "description": "Identifiant de connexion incorrect",
}
{
    "code": "902",
    "status": "INVALID_SENDER_ID",
    "description": "Le sender_id n’existe pas",
}
        
{
    "code": 913,
    "message": "INVALID_OTP",
    "description": "vavasms.INVALID_OTP",
    "data": []
}