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:
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:
https://api.taqnyat.sa/
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.
With Taqnyat you can set up your bearer token in seconds using the below steps:
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 resources are used to retrieve info about the system.
This method used to retrieve status for one or multiple services
in the system.
Authorization is not required .
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 resources are used to retrieve info about you account.
This resource is used to retrieve Status, balance, and other info
about your account.
Authorization is required.
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 resources are used to deal with messages.
Authorization is required .
| 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.
This resource is used to send messages using a template.
Send a JSON request with Content-Type: application/json; charset=UTF-8. Include your API token in the Authorization header as a Bearer token.
Authorization is required .
| Parameter | Description | Required |
|---|---|---|
| recipients |
Array of international phone numbers without 00 or (+), for example ["966500000000"].
|
Yes |
| templateName | Name of the template to use. | Yes |
| sender | Sender name predefined in your account. | Yes |
| campaignName | Name of the campaign. | No |
| variables | Object containing template variable names and their values, for example {"code":"1234"}. |
Conditional |
Example JSON request:
curl --location 'https://api.taqnyat.sa/v1/messages' \
--header 'Content-Type: application/json; charset=UTF-8' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
"sender": "Taqnyat",
"recipients": [
"966500000000"
],
"campaignName": "Campaign-Name",
"templateName": "Template-Name",
"variables": {
"code": "1234"
}
}'
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": "[966********,]",
"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 template error list to
understand what type of error you have.
| 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"
}
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.
This resource used to delete a message from messages scheduled
queue.
Authorization is required .
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"
}
This resource used to manage sender names from your account.
Authorization is required .
To define new sender
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"
}
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 Code | 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 messages again. |
| 3 | Your balance is not enough | Your account has a low balance and does not cover all messages you are about to send. |
| 6 | SMS-API not responding , please try again | Error connecting to the server, due to scheduled maintenance, better try again later on. |
| 13 | 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) |
| 14 | Sender Name not active | Sender name used is not among your active sender name, you may check the active senders using Check Sender |
| 15 | Mobile(s) number(s) is not specified or incorrect | All destination mobile numbers must be submitted with international format without 00 or symbol (+) |
| 16 | Sender Name is not specified | Sender name is required for sending messages, make sure the parameter "sender" is provided with your request |
| 17 | Message text is not specified | Message content is required for sending messages, make sure the parameter "body" is provided with your request |
| 18 | Sending SMS stopped from support | Your account has a problem, you need to contact support@taqnyat.sa |
| 21 | 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. |
| 22 | The number of recipients is greater than 1000 | The max allowed recipients per request are 1000 destination |
| 24 | Sender Name is expired | Your Sender Name is expierd, you need to contact support@taqnayt.sa |
| 101 | sending by API is disabled | You need to go to Developers on the left side of the screen, then click on Security Settings, and make sure that "Disable send SMS using API" is enabled. |
| 102 | this ip Not authorized to using the API | You need to go to Developers on the left side of the screen, then click on Security Settings, and make sure that the IP is authorized to send. |
| 103 | this country Not authorized to using the API | to send to this country, you need to contact support@taqnayt.sa |
| 104 | you can't use proxy to send | Your account has a problem, you need to contact support@taqnayt.sa |
| 130 | Error while checking the template |
خطأ أثناء التحقق من القالب فشل استعلام قاعدة البيانات أثناء البحث عن القالب. |
| 131 | Template name does not exist or is not active |
اسم القالب غير موجود أو غير فعال اسم القالب غير موجود للمستخدم والمرسل. |
| 132 | Invalid template variable configuration |
تعريف المتغيرات في القالب غير صحيح عدد أو أسماء المتغيرات في إعدادات القالب لا تطابق تعريف القالب. |
| 132 | Undefined type for variable: {variableName} |
نوع المتغير {variableName} غير معرف نوع المتغير المحفوظ في القالب غير معرف. |
| 133 | Invalid variables format |
صيغة المتغيرات غير صحيحة صيغة بيانات المتغيرات ليست مصفوفة أو JSON صحيحًا. |
| 134 | Variables count does not match template. Expected: {count} |
عدد المتغيرات لا يطابق القالب. المطلوب: {count} عدد المتغيرات المرسلة لا يساوي العدد المطلوب. |
| 135 | Missing variable: {variableName} |
المتغير {variableName} غير موجود أحد أسماء المتغيرات المطلوبة غير موجود في الطلب. |
| 136 | Invalid value for variable: {variableName} |
قيمة المتغير {variableName} غير صحيحة قيمة المتغير ليست نصًا أو رقمًا. |
| 136 | Invalid characters or spaces in variable: {variableName} |
المتغير {variableName} يحتوي على أحرف أو مسافات غير صحيحة قيمة فارغة، أو تحتوي على مسافات أو أحرف غير مسموحة، أو UTF-8 غير صالح. |
| 137 | Variable {variableName} exceeds maximum length: {maxLength} |
المتغير {variableName} يتجاوز الحد المسموح: {maxLength} طول المتغير يتجاوز الحد المسموح، أو الحد غير صالح. |
| 138 | Invalid type for variable {variableName}. Expected: {type} |
قيمة المتغير {variableName} غير مطابقة للنوع المطلوب: {type} قيمة المتغير لا تطابق نوعه المسجل. |
| 139 | Company name is missing for awareness template |
اسم الشركة غير معرف للقالب التوعوي لا يوجد اسم شركة للقالب التوعوي. |
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.
To configure your callback URL or "webhook" simply flow those steps: