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

Send a Mail

POST /mailSend.php/

Parameter	Description	Required
campaignName	The Name of Your Campain	Yes
subject	The Subject for your Email	Yes
from	The Sender Email	Yes
to	Array of Resivers Email	Yes
msg	The Message that you want to send it	Yes

Here is some example of HTTP API:


https://api.taqnyat.sa/mailSend.php?
    bearerTokens=xxxxxxxxxxxxxxxxxxxxxxxxxx&
    campaignName=your campain name&
    subject= youe email subject&
    from=mail@example.com&
    to=mail1@example.com,mail2@example.com&
    msg=your message text

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


{
    "status": 1,
    "ResponseStatus":"success",
    "Data": {
        "msgId":202,
        "result":1,
        "MessageAr":"تم الإرسال",
        "MessageEn":"sent successfully",
        "price":"0",
    }
    "Error":null,
}

if the request return ErrorCode 2


        {
            "status": 1,
            "ResponseStatus":"fail",
            "Data":null,
            "Error": {
                "ErrorCode":2,
                "MessageAr":" الرصيد = 0",
                "MessageEn":" Your balance is 0"",
            }
            
        }

if the request return ErrorCode 3


        {
            "status": 1,
            "ResponseStatus":"fail",
            "Data":null,
            "Error": {
                "ErrorCode":2,
                "MessageAr":" الرصيد غير كافي",
                "MessageEn":" Your balance is not enough"",
            }
            
        }

if the request return ErrorCode 14


        {
            "status": 1,
            "ResponseStatus":"fail",
            "Data":null,
            "Error": {
                "ErrorCode":14,
                "MessageAr":" خطا في المرسل",
                "MessageEn":" error From"",
            }
            
        }

if the request return ErrorCode 15


        {
            "status": 1,
            "ResponseStatus":"fail",
            "Data":null,
            "Error": {
                "ErrorCode":15,
                "MessageAr":" البريد الالكتروني المرسل لها غير صحيحه أو فارغه",
                "MessageEn":" Email is not specified or incorrect"",
            }
            
        }

if the request return ErrorCode 16


        {
            "status": 1,
            "ResponseStatus":"fail",
            "Data":null,
            "Error": {
                "ErrorCode":16,
                "MessageAr":" يوجد خطا في عنوان الرساله",
                "MessageEn":" error subject"",
            }
            
        }

if the request return ErrorCode 17


        {
            "status": 1,
            "ResponseStatus":"fail",
            "Data":null,
            "Error": {
                "ErrorCode":17,
                "MessageAr":" يوجد خطا في الرساله",
                "MessageEn":" error msg"",
            }
            
        }

if the request return ErrorCode 101


        {
            "status": 1,
            "ResponseStatus":"fail",
            "Data":null,
            "Error": {
                "ErrorCode":101,
                "MessageAr":" الارسال باستخدام بوابات الارسال معطل",
                "MessageEn":"Invalid Bearer Tokens",
            }
            
        }

if the request return ErrorCode 102


            {
                "status": 1,
                "ResponseStatus":"fail",
                "Data":null,
                "Error": {
                    "ErrorCode":102,
                    "MessageAr":" هذا الاي بي 10.0.0.1 غير مصرح له باستخدم بوابات الارسال",
                    "MessageEn":" this ip 10.0.0.1 Not authorized to using the API"",
                }
                
            }

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


            {
                "status": 1,
                "ResponseStatus":"fail",
                "Data":null,
                "Error": {
                    "ErrorCode":104,
                    "MessageAr":" مفتاح الارسال غير صحيح",
                    "MessageEn":"Invalid Bearer Tokens",
                }
                
            }

Mail 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.

number	Error	Description
2	Your balance is 0	Your balance has been consumed and you need to top up your account to restore the ability to send mail again.
3	Your balance is not enough	Your account has a low balance and does not cover all mail you are about to send.
14	error From	Sender email used is not correct, make sure to include the sender email with correct format
15	Email is not specified or incorrect	Resivers Emails used is not correct, make sure to include the Resivers Emails as Array of emails with correct format
16	error subject	subject used is not correct, make sure to include the subject as text
17	error msg	message used is not correct, make sure to include the message as text
101	sending by API is disabled	the functionality or capability to send data or requests through an API has been deactivated or turned off
102	this ip 10.0.0.1 Not authorized to using the API	the IP address from which you are attempting to access an API service is not granted permission or authorization to do so.
104	Invalid Bearer Tokens	the API key you are using to authenticate or authorize your access to the API service is either missing, incorrect, expired, or revoked.

Status

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

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

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

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

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

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

Send a Mail

curl -X POST \
https://api.taqnyat.sa/mailSend.php/ \
-H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
-H 'Content-Type: application/json' \
-d '{
"campaignName":"your campain name",
"subject":"youe email subject",
"from":"mail@example.com",
"to": [
"mail1@example.com",
"mail2@example.com"
],
"msg":"your message text"
}


{
    "status": 1,
    "ResponseStatus": "success",
    "Data": 
    {
        "msgId": "V-8",
        "result": 1,
        "MessageAr": "تم الإرسال",
        "MessageEn": "sent successfully",
        "duration": 3,
        "dtmfTimeout": "0",
        "connectionFee": 3,
        "price": "0.216",
        "rejectedNumber": "[]",
    },
    "Error": null                                
}




//Error on invalid or empty sender email
{
"status": 1,
"ResponseStatus": "fail",
"Data": null,
"Error": 
{
    "ErrorCode": 14,
    "MessageAr": "خطا في المرسل",
    "MessageEn": "error From",
}                                       
}

//Error on invalid or empty receivers emails
{
"status": 1,
"ResponseStatus": "fail",
"Data": null,
"Error": 
{
    "ErrorCode": 15,
    "MessageAr": "البريد الالكتروني المرسل لها غير صحيحه أو فارغه",
    "MessageEn": "Email is not specified or incorrect",
}                                       
}

//Error on Empty subject 
{
"status": 1,
"ResponseStatus": "fail",
"Data": null,
"Error": 
{
    "ErrorCode": 16,
    "MessageAr": "يوجد خطا في عنوان الرساله",
    "MessageEn": "error subject",
}                                       
}

//Error on Empty msg 
{
"status": 1,
"ResponseStatus": "fail",
"Data": null,
"Error": 
{
    "ErrorCode": 17,
    "MessageAr": "يوجد خطا في الرساله ",
    "MessageEn": "error msg",
}                                       
}

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

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

Schedule

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

Scheduled

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

Sender

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

{
    "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 #

Send a Mail #

Mail Error codes #

Status

Send a Mail

Message

Schedule

Scheduled

Sender

Callback

API Reference

APIs Features:

Before you go

Base URL

Authentication

Setup Bearer token

Let us Get started:

System

System status

Send a Mail

Mail Error codes