Taqnyat Communications APIs

API Reference

With our REST, easy, and smart “SMS” APIs we allow you to integrate SMS at your app and get started in seconds, With Taqnyat, building a solution with SMS capabilities never been easier, a few lines of code will enable the SMS to create a magnificent app fit with your business needs.

In the below guide, we'll walk you through and explain how Taqnyat SMS API work:

APIs Features:

Connecting to taqnyat.sa API is simple & easy, you can do it using HTML forms, which will send the data as POST, or send data to API URL directly using Query String, which will send the data as "GET". If you want to send a large amount of data, we recommend that you use the first method, which is POST; because the second method GET does not support sending a large amount of data. Besides, you can send data in JSON, a full description of the JSON Data method will be in this document.

taqnyat.sa also returns the data in the most common format, which is JSON.

When you connect to taqnyat.sa API through HTTP/HTTPS protocols, the SMS data must be in a certain format as follows: Sender Name must be encoded using URL-Encoding and message text must be in UTF-8 encodings:

Before you go

We recommended the one who is going to use this documentation or APIs to have programming skills.
The testing cost is nothing because we offer a free startup balance of 1 SAR for any trial account.
Cost calculation for messaging depends on how many messages you will send and how many destinations it will be receiving the messages.
If you want to try to send SMS API, we advise you to send scheduled SMS, so you can check if they reached “Scheduled SMS Archive” in your taqnyat.sa account, then you may delete the SMS to spare the cost and get your balance back.
When you send SMS through API, mobile numbers that will receive the SMS must be in international format without 00 or symbol (+)
You must have an active sender name before you go, you may contact support@taqnyat.sa or account manager to get more details about the requirements and how to activate your Sender Name.

Base URL

All URLs resources in the SMS documentation have the base URL
https://api.taqnyat.sa/

Authentication

To use our API, you will need a unique Bearer token generated from your account at our platform by following the below steps Setup Bearer token

For REST API Bearer token must be submitted withen the header Authorization.

If you failed to authenticate the request, response header with error 401 expected to return.
You need to make sure passing the correct credential.

Setup Bearer token

With Taqnyat you can set up your bearer token in seconds using the below steps:

Login to your account at Taqnyat.
Select Application from Developer section.
Press the add button on the top right corner.
Choose a suitable name for your application.
Select the services you want this app to include , in our case SMS.
Hit the confirm button to submit your application.
Copy the Bearer Tokens.

Let us Get started:

To use taqnyat.sa API, you should have a taqnyat.sa account, here is an explanation of how you can register, checking your current balance, request a recharge for your balance through a “request recharge form” in taqnyat.sa website.

Registration process: You can register on taqnyat.sa website through the following link: Contact and go to Sales tab ,fill the form and hit send.
Check your balance: You can check your current balance from the website after you logged at the dashboard.
Balance Topup: After your login to your https://www.taqnyat.sa account, you can request recharging your balance, through the request top-up form, you can access it through the balance top-up tab located in the left top corner. Fill all the required data in the form and we will top up your account within two hours at most after we validate the deposit.
Using bearer Tokens: bearer Tokens will have a unique value generated in the taqnyat.sa user account , because it provides a more secure connection with the API.
Setup API settings: taqnyat.sa provides security settings that allows you to control SMS sending through API. You can enable or disable sending SMS through API from your account, grant permission to specific IP’s to be allowed to send SMS message through API using your account, and grant permission to specific countries to be allowed to send SMS message through API using your account.

System

System resources are used to retrieve info about the system.

System status

...

This method used to retrieve status for one or multiple services in the system.
Authorization is not required .

GET /system/status

Here are some examples of HTTP API:

https://api.taqnyat.sa/system/status

if the request submitted successfully header status of 200 will be return as follows:

{
    statusCode: 200,
    status: {
        service: "none",
        description: "All Services are Operational"
    }
}

if the request return header 405 , you are using RESTFull API and have used unauthorized method for example
if the System resource allow only get , and you used post error 405 expected to return.

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}

Account

Account resources are used to retrieve info about you account.

Account Balance

This resource is used to retrieve Status, balance, and other info about your account.
Authorization is required.

GET /account/balance

Here are some examples of HTTP API:

https://api.taqnyat.sa/account/balance?
    bearerTokens=xxxxxxxxxxxxxxxxxxxxxxxxxx

if the request submitted successfully header status of 200 will be return as follows:

{
    "statusCode": 200,
    "accountStatus": "active",
    "accountExpiryDate": "23-08-2021",
    "balance": "2044.000",
    "currency": "SAR"
}

if the request return header 401 , you are using wrong bearer Tokens
make sure to follow the steps in above to setup your bearer Token Setup Bearer token

{
    "statusCode": 401,
    "message": "invalid credentials information"
}

if the request return header 405 , you are using RESTFull API and have used unauthorized method for example
if the System resource allow only get , and you used post error 405 expected to return.

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}

Messages

Messages resources are used to deal with messages.

Send a Message

This resource used to send message(s) from your account.

Authorization is required .

POST /v1/messages

Parameter	Description	Required
recipients	Array of international format without 00 or symbol (+)	Yes
body	The Content of the message	Yes
sender	Pre Define sender name at your account	Yes
scheduledDatetime	Schedule the message to send later IE: 2020-09-30T14:26	No

Here is some example of HTTP API:

https://api.taqnyat.sa/v1/messages?
    bearerTokens=xxxxxxxxxxxxxxxxxxxxxxxxxx&
    sender=test&
    recipients=966500000000,966500000000&
    body=bodyTest

if the request submitted successfully header status of 201 will be return as follows:

{
    "statusCode": 201,
    "messageId": 5452899970,
    "cost": 0.026,
    "currency": "SAR",
    "totalCount": 1,
    "msgLength": 1,
    "accepted": "[966500000000,]",
    "rejected": "[]"
}

if the request return header 401 , you are using wrong bearer Tokens
make sure to follow the steps in above to setup your bearer Token Setup Bearer token

{
    "statusCode": 401,
    "message": "invalid credentials information"
}

if the request return header 405 , you are using RESTFull API and have used unauthorized method for example
if the System resource allow only get , and you used post error 405 expected to return.

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}

if the request return header 400 , its mean the request has not submitted successfully and the error code in the response will explain the issue
you can scroll down to the error list to understand what type of error you have.

Send a Schedule Message

POST /v1/messages

Parameter	Description	Required
recipients	Array of international format without 00 or symbol (+)	Yes
body	The Content of the message	Yes
sender	Pre Define sender name at your account	Yes
scheduledDatetime	Schedule the message to send later IE: 2020-09-30T14:26	Yes
deleteId	this id will be used to selete the schedule message	No

Here is some example of HTTP API:

https://api.taqnyat.sa/v1/messages?
    bearerTokens=xxxxxxxxxxxxxxxxxxxxxxxxxx&
    sender=test&
    recipients=966500000000,966500000000&
    body=bodyTest&
    scheduledDatetime=2020-09-30T14:26

if the request submitted successfully header status of 201 will be return as follows:

{
    "statusCode": 201,
    "messageId": 5452899970,
    "cost": 0.026,
    "currency": "SAR",
    "totalCount": 1,
    "msgLength": 1,
    "accepted": "[966500000000,]",
    "rejected": "[]"
}

if the request return header 401 , you are using wrong bearer Tokens
make sure to follow the steps in above to setup your bearer Token Setup Bearer token

{
    "statusCode": 401,
    "message": "invalid credentials information"
}

if the request return header 405 , you are using RESTFull API and have used unauthorized method for example
if the System resource allow only get , and you used post error 405 expected to return.

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}

Delete Scheduled Message

This resource used to delete a message from messages scheduled queue.
Authorization is required .

DELETE /v1/messages/delete

You can make sure the message has been deleted successfuly by access to our portal https://api.taqnyat.sa/ from Manage SMS section and select Scheduled SMS , and make sure the message you've schedualed not exsist.

Parameter	Description	Required
deleteId	Message id you want to delete	Yes

Here are some examples of HTTP API:

https://api.taqnyat.sa/v1/messages/delete?
    bearerTokens=xxxxxxxxxxxxxxxxxxxxxxxxxx&
    deleteId=100

if the request submitted successfully header status of 201 will be return as follows:

{
    "statusCode":201,
    "message":"Deleted successfully"
}

if the request return header 401 , you are using wrong bearer Tokens
make sure to follow the steps in above to setup your bearer Token Setup Bearer token

{
    "statusCode": 401,
    "message": "invalid credentials information"
}

if the request return header 422 , you have submitted wrong deleteId
make sure to pass the correct deleteId with your request.

{
    "statusCode":422,
    "message":"Invalid deleteKey"
}

if the request return header 405 , you are using RESTFull API and have used unauthorized method for example
if the System resource allow only get , and you used post error 405 expected to return.

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}

Sender names

This resource used to manage sender names from your account.

Authorization is required .

GET /v1/messages/senders

To define new sender

Request the New sender Form , from your account manager.
Fill the sender information on the sender form using your company letter head.
Provide your company valid certification.
send both form and certification to your account manager.
you will be notified once your sender is approved by the operators .

Here are some examples of HTTP API:

https://api.taqnyat.sa/v1/messages/senders?
    bearerTokens=xxxxxxxxxxxxxxxxxxxxxxxxxx

if the request submitted successfully header status of 201 will be return as follows:

{
    "statusCode": 201,
    "senders": [
        {
            "senderName": "sender name 1",
            "status": "active",
            "destination": "KSA"
        },
        {
            "senderName": "sender name 2",
            "status": "active",
            "destination": "international"
        }
    ]
}

if the request return header 401 , you are using wrong bearer Tokens
make sure to follow the steps in above to setup your bearer Token Setup Bearer token

{
    "statusCode": 401,
    "message": "invalid credentials information"
}

if the request return header 405 , you are using RESTFull API and have used unauthorized method for example
if the System resource allow only get , and you used post error 405 expected to return.

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}

Message Error codes

Below on the table list for code in the response , if the header returned 400 .
lookup the code of the response with code on the table for better understanding the error cause.

Error	Description
Your balance is 0	Your balance has been consumed and you need to top up your account to restore the ability to send messages again.
Your balance is not enough	Your account has a low balance and does not cover all messages you are about to send.
SMS-API not responding , please try again	Error connecting to the server, due to scheduled maintenance, better try again later on.
Sender Name is not accepted	Sender name used is not correct, make sure to include the sender name as it is shown at your account (case sensitive)
Sender Name not active	Sender name used is not among your active sender name, you may check the active senders using Check Sender
Mobile(s) number(s) is not specified or incorrect	All destination mobile numbers must be submitted with international format without 00 or symbol (+)
Sender Name is not specified	Sender name is required for sending messages, make sure the parameter "sender" is provided with your request
Message text is not specified	Message content is required for sending messages, make sure the parameter "body" is provided with your request
Sending SMS stopped from support	Your account has a problem, you need to contact support@taqnyat.sa
no data for this msg	The request has return no data, you may contact support@taqnayt.sa to get more details about the request results.
The number of recipients is greater than 1000	The max allowed recipients per request are 1000 destination

Callback

DELETE CallBack

Callback URL or "webhook" used to feed your system with messages status once it's updated, you can enable this feature by providing a URL using the below setps.

Callback required to send us a safe phrase to confirm callback receiving , other wise our server will keep sending the same callback considering the previous attempts failed , this loop will continue up to three attempts and we will discontinue calling back after that.

To configure your callback URL or "webhook" simply flow those steps:

Login to your account at portal.taqnyat.sa.
Select Developer tools from Developer section.
Fill your Webhook URL at Webhook URL.
Enter your pass Phrase , that will be used for confirming callback receiving.
Hit save to confirm modifications.

System Status

curl --location 
     --request GET 'https://api.taqnyat.sa/system/status'

// Install Taqnyat Package from Packagist using composer 
// composer require taqnyat/php
// Update the path below to your autoload.php,

<?php
require_once '/path/to/vendor/autoload.php';

$bearer = '**************************0adc2b';
$taqnyt = new TaqnyatSms($bearer);

$Status = $taqnyt->sendStatus();
print $Status;

# Install Taqnyat Package from https://pypi.org/ 
# pip install taqnyat
# import Client from TaqnyatSms

import Client from TaqnyatSms

bearer = '**************************0adc2b'
taqnyt = client(bearer)
status = taqnyt.sendStatus();

print status;


//You may install Taqnyat .net package using Package Manager
//Install-Package Taqnyat 

//Also you may install .net package using .NET CLI
//dotnet add package Taqnyat 

//Finaly using Paket CLI
//paket add Taqnyat 


using System;
using System.Net.Http;
using Taqnyat;

public class Program
{
	public static void Main()
	{
		
		Taqnyat.Taqnyat taqnyt = new Taqnyat.Taqnyat();
        
		var status = taqnyt.GetStatus();

		Console.WriteLine(status);

	}
}

// When All services are fully Operational without any problem. 

{
    statusCode: 200,
    status: {
        service: "none",
        description: "All Services are Operational"
    }
}

// If we have a problem in on or more in our services. 

{
    statusCode: 400,
    status: {
        service: "SMS",
        description: "Service is down for maintenance"
    }
}

Account Balance

curl --location --request GET 'https://api.taqnyat.sa/account/balance' \
--header 'Authorization: Bearer **********************ed3a0adc2b'

// Install Taqnyat Package from Packagist using composer 
// composer require taqnyat/php
// Update the path below to your autoload.php,

<?php
require_once '/path/to/vendor/autoload.php';

$bearer = '**************************0adc2b';
$taqnyt = new TaqnyatSms($bearer);

$balance = $taqnyt->balance();
print $balance;

# Install Taqnyat Package from https://pypi.org/ 
# pip install taqnyat
# import Client from TaqnyatSms

import Client from TaqnyatSms

bearer = '**************************0adc2b'
ttaqnyt = client(bearer)
balance = taqnyt.balance();

print balance;

//You may install Taqnyat .net package using Package Manager
//Install-Package Taqnyat 

//Also you may install .net package using .NET CLI
//dotnet add package Taqnyat 

//Finaly using Paket CLI
//paket add Taqnyat 

using System;
using System.Net.Http;
using Taqnyat;

public class Program
{
	public static void Main()
	{
		Taqnyat.Taqnyat taqnyt = new Taqnyat.Taqnyat();
		string bearer = "**********************ed3a0adc2b";
        var balance = taqnyt.GetBalance(bearer);
        Console.WriteLine(balance);
	}
}

{
    "statusCode": 200,
    "accountStatus": "active",
    "accountExpiryDate": "23-08-2021",
    "balance": "2044.000",
    "currency": "SAR"
}

// You are using wrong bearer Tokens , 
// make sure to follow the steps in above to setup your bearer Token
{
    "statusCode": 401,
    "message": "invalid credentials information"
}

// You are using Restfull API with wrong method.
// make sure to use the allowed method "GET"

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}

Message Send

curl --location --request POST 'https://api.taqnyat.sa/v1/messages' \
--header 'Authorization: Bearer **********************ed3a0adc2b  ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "recipients": [
        966500000000
    ],
    "body":"Message Content",
    "sender":"Sender Name"
}
'

// Install Taqnyat Package from Packagist using composer 
// composer require taqnyat/php
// Update the path below to your autoload.php,

<?php

require_once '/path/to/vendor/autoload.php';
$bearer = '**************************0adc2b';
$taqnyt = new TaqnyatSms($bearer);

$body = 'message Content';
$recipients = ['966********'];
$sender = 'Sender Name';

$message =$taqnyt->sendMsg($body, $recipients, $sender);
print $message;

# Install Taqnyat Package from https://pypi.org/ 
# pip install taqnyat
# import Client from TaqnyatSms

import Client from TaqnyatSms

bearer = '**************************0adc2b'

body = 'message Content';
recipients = ['966********'];
sender = 'Sender Name';

taqnyt = client(bearer)
message = taqnyt.sendMsg(body, recipients, sender);

print message;


//You may install Taqnyat .net package using Package Manager
//Install-Package Taqnyat 

//Also you may install .net package using .NET CLI
//dotnet add package Taqnyat 

//Finaly using Paket CLI
//paket add Taqnyat 


using System;
using System.Net.Http;
using Taqnyat;

public class Program
{
	public static void Main()
	{
		Taqnyat.Taqnyat taqnyt = new Taqnyat.Taqnyat();
		string bearer = "**********************ed3a0adc2b";
		string body = "message Content";
		string recipients = "966xxxxxxxxx";
		string sender = "SenderName";


        var message = taqnyt.SendMessage(bearer, recipients, sender, body);

        Console.WriteLine(message);
	}
}

{
    "statusCode": 201,
    "messageId": 5452899970,
    "cost": 0.026,
    "currency": "SAR",
    "totalCount": 1,
    "msgLength": 1,
    "accepted": "[966500000000,]",
    "rejected": "[]"
}

{
    "statusCode": 400,
    "message": "Mobile(s) number(s) is not specified or incorrect"
}

// You are using wrong bearer Tokens , 
// make sure to follow the steps in above to setup your bearer Token
{
    "statusCode": 401,
    "message": "invalid credentials information"
}

// You are using Restfull API with wrong method.
// make sure to use the allowed method "POST"

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}

Send Schedule Message

curl --location --request POST 'https://api.taqnyat.sa/v1/messages' \
--header 'Authorization: Bearer **********************ed3a0adc2b  ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "recipients": [
        966500000000
    ],
    "body":"Message Content",
    "sender":"Sender Name",
    "scheduledDatetime":"2020-09-30T14:26",
    "deleteId":100
}
'

// Install Taqnyat Package from Packagist using composer 
// composer require taqnyat/php
// Update the path below to your autoload.php,

<?php

require_once '/path/to/vendor/autoload.php';
$bearer = '**************************0adc2b';
$taqnyt = new TaqnyatSms($bearer);

$body = 'message Content';
$recipients = ['966********'];
$sender = 'Sender Name';
$scheduled = 'yyyy-mm-ddThh:mm';
$deleteId = 100;


$message =$taqnyt->sendMsg($body, $recipients, $sender, $deleteId, $scheduled);
print $message;

# Install Taqnyat Package from https://pypi.org/ 
# pip install taqnyat
# import Client from TaqnyatSms

import Client from TaqnyatSms

bearer = '**************************0adc2b'
body = 'message Content';
recipients = ['966********'];
sender = 'Sender Name';
scheduled='2020-09-30T14:26'
deleteId=100

taqnyt = client(bearer)
message = taqnyt.sendMsg(body, recipients, sender, deleteId, scheduled);

print message;


//You may install Taqnyat .net package using Package Manager
//Install-Package Taqnyat 

//Also you may install .net package using .NET CLI
//dotnet add package Taqnyat 

//Finaly using Paket CLI
//paket add Taqnyat 


using System;
using System.Net.Http;
using Taqnyat;

public class Program
{
	public static void Main()
	{
		Taqnyat.Taqnyat taqnyt = new Taqnyat.Taqnyat();
		string bearer = "**********************ed3a0adc2b";
		string body = "message Content";
		string recipients = "966xxxxxxxxx";
		string sender = "SenderName";
		string scheduled="2020-09-30T14:26";
		string deleteId="2020-09-30T14:26";

        var message = taqnyt.SendMessage(bearer, recipients, sender, body,deleteId, scheduled);

        Console.WriteLine(message);
	}
}

{
    "statusCode": 201,
    "messageId": 5453165288,
    "balance": 0.026,
    "currency": "SAR",
    "totalCount": 1,
    "msgLength": 1,
    "accepted": "[966000000000,]",
    "rejected": "[]"
}

{
    "statusCode": 400,
    "message": "Mobile(s) number(s) is not specified or incorrect"
}

// You are using wrong bearer Tokens , 
// make sure to follow the steps in above to setup your bearer Token
{
    "statusCode": 401,
    "message": "invalid credentials information"
}

// You are using Restfull API with wrong method.
// make sure to use the allowed method "POST"

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}

Delete Schedule Message

curl --location --request DELETE 'https://api.taqnyat.sa/v1/messages' \
--header 'Authorization: Bearer **********************ed3a0adc2b  ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "deleteId":100
}
'

{
    "statusCode":201,
    "message":"Deleted successfully"
}

// You are using wrong bearer Tokens , 
// make sure to follow the steps in above to setup your bearer Token
{
    "statusCode": 401,
    "message": "invalid credentials information"
}

// You are using Restfull API with wrong method.
// make sure to use the allowed method "DELETE"

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}

{
    "statusCode": 422,
    "message": "Invalid deleteKey"
}

Message Senders

curl --location --request GET 'https://api.taqnyat.sa/v1/messages/senders' \
--header 'Authorization: Bearer **********************ed3a0adc2b  '

// Install Taqnyat Package from Packagist using composer 
// composer require taqnyat/php
// Update the path below to your autoload.php,

<?php

require_once '/path/to/vendor/autoload.php';
$bearer = '**************************0adc2b';
$taqnyt = new TaqnyatSms($bearer);

$senders = $taqnyt->senders();
print $senders;

# Install Taqnyat Package from https://pypi.org/ 
# pip install taqnyat
# import Client from TaqnyatSms

import Client from TaqnyatSms

bearer = '**************************0adc2b'
taqnyt = client(bearer)
senders = taqnyt.senders();

print senders;


//You may install Taqnyat .net package using Package Manager
//Install-Package Taqnyat 

//Also you may install .net package using .NET CLI
//dotnet add package Taqnyat 

//Finaly using Paket CLI
//paket add Taqnyat 


using System;
using System.Net.Http;
using Taqnyat;

public class Program
{
	public static void Main()
	{
		Taqnyat.Taqnyat taqnyt = new Taqnyat.Taqnyat();
		string bearer = "**********************ed3a0adc2b";

        var senders = taqnyt.GetSenders(bearer);

        Console.WriteLine(senders);
	}
}

{
    "statusCode": 201,
    "senders": [
        {
            "senderName": "sender name 1",
            "status": "active",
            "destination": "KSA"
        },
        {
            "senderName": "sender name 2",
            "status": "active",
            "destination": "international"
        }
    ]
}

// You are using wrong bearer Tokens , 
// make sure to follow the steps in above to setup your bearer Token
{
    "statusCode": 401,
    "message": "invalid credentials information"
}

// You are using Restfull API with wrong method.
// make sure to use the allowed method "GET"

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}

API Reference #

APIs Features: #

Before you go #

Base URL #

Authentication #

Setup Bearer token #

Let us Get started: #

System #

System status #

Account #

Account Balance #

Messages #

Send a Message #

Send a Schedule Message #

Delete Scheduled Message #

Sender names #

Message Error codes #

Callback #

System Status

Account Balance

Message Send

Send Schedule Message

Delete Schedule Message

Message Senders

Callback

API Reference

APIs Features:

Before you go

Base URL

Authentication

Setup Bearer token

Let us Get started:

System

System status

Account

Account Balance

Messages

Send a Message

Send a Schedule Message

Delete Scheduled Message

Sender names

Message Error codes

Callback