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

Voice

Voices resources are used to deal with voice.

Send a Voice

This resource used to send voice(s) from your account. Authorization is required .

POST /voiceSend.php/

Parameter	Description	Required
audioUrl	full path for your voice	Yes
callerId	sender name as international format without 00 or symbol (+)	Yes
recipients	Array of international format without 00 or symbol (+)	Yes

Here is some example of HTTP API:


            https://api.taqnyat.sa/voiceSend.php
            bearerTokens=xxxxxxxxxxxxxxxxxxxxxxxxxx&
            audioUrl=https://your_domain.com/your_mp3_file.mp3&
            callerId=966500000000&
            recipients=966500000000,966500000000&

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


        {
            "status": 1,
            "ResponseStatus": success,
            "messageId": 5452899970,
            "Data": {
                "msgId": "V-8",
                "result": "1",
                "MessageAr": "تم الارسال",
                "MessageEn": "sent successfully",
                "duration": 3,
                "dtmfTimeout": "0",
                "connectionFee": 3,
                "price": "0.216",
                "rejectedNumber": "[]",
                "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": 3,
                    "MessageAr": "الرصيد غير كافي",
                    "MessageEn": "Your balance is not enough",
                }
            }

if the request return ErrorCode 14


            {
                "status": 1,
                "ResponseStatus": fail,
                "Data": null,
                "Error": {
                    "ErrorCode": 14,
                    "MessageAr": "هوية المتصل غير صحيحة",
                    "MessageEn": "Invalid CallerId",
                }
            }

if the request return ErrorCode 15


            {
                "status": 1,
                "ResponseStatus": fail,
                "Data": null,
                "Error": {
                    "ErrorCode": 15,
                    "MessageAr": "الأرقام المرسل لها غير صحيحة أو فارغة",
                    "MessageEn": "Mobile(s) number(s) is not specified or incorrect",
                }
            }

if the request return ErrorCode 17


            {
                "status": 1,
                "ResponseStatus": fail,
                "Data": null,
                "Error": {
                    "ErrorCode": 17,
                    "MessageAr": "يوجد خطأ في الارسال او الملف الصوتي",
                    "MessageEn": "error msg or error audio file",
                }
            }

if the request return ErrorCode 101


            {
                "status": 1,
                "ResponseStatus": fail,
                "Data": null,
                "Error": {
                    "ErrorCode": 101,
                    "MessageAr": "الارسال باستخدام بوابات الارسال معطل",
                    "MessageEn": "sending by API is disabled",
                }
            }

if the request return ErrorCode 102


            {
                "status": 1,
                "ResponseStatus": fail,
                "Data": null,
                "Error": {
                    "ErrorCode": 102,
                    "MessageAr": "هذا الاي بي 10.0.0.1 غير مصرح له ",
                    "MessageEn": "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",
                    }
                }

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.

Voice 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 Voice again.
3	Your balance is not enough	Your account has a low balance and does not cover all Voices you are about to send.
14	Invalid CallerId	Sender phone used is not correct, make sure to include the sender phone as international format without 00 or symbol (+)
15	Mobile(s) number(s) is not specified or incorrect	Resivers phones used is not correct, make sure to include the Resivers phones as Array of international format without 00 or symbol (+)
17	error msg or error audio file	your audio file is not correct, make sure to include the correct path and the correct file type
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 Voice

curl -X POST \
https://api.taqnyat.sa/voiceSend.php/ \
-H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
-H 'Content-Type: application/json' \
-d '{
    "audioUrl":"https://your_domain.com/your_mp3_file.mp3",
    "callerId":"96600000000",
        "recipients": [
            "966666666666",
            "966666666666"
        ]
    }'

{
    "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 number 
{
    "status": 1,
    "ResponseStatus": "fail",
    "Data": null,
    "Error": 
    {
        "ErrorCode": 14,
        "MessageAr": "هوية المتصل غير صحيحة",
        "MessageEn": "Invalid CallerId",
    }                                       
}
 
//Error on invalid or empty numbers
{
    "status": 1,
    "ResponseStatus": "fail",
    "Data": null,
    "Error": 
    {
        "ErrorCode": 15,
        "MessageAr": "الأرقام المرسل لها غير صحيحه أو فارغه",
        "MessageEn": "Mobile(s) number(s) is not specified or incorrect",
    }                                       
}

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

Opt Out

curl -X DELETE \
https://api.taqnyat.sa/wa/v1/provision/optin \
-H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
-H 'Content-Type: application/json' \
-d '{
        "numbers": [
            "966666666666",
            "966666666666"
        ]
    }'

{
    "type": "Opt-Out",
    "statuses": [
        {
            "status": "success",
            "state": "disable"
        }
    ]
}

//Error on Empty number 
{
    "message": "Validation Failed",
    "reason": "Field [numbers]: must not be empty"
}
 
//Error on invalid number 
{
    "message": "Validation Failed",
    "reason":  "965577.523233 is not a valid msisdn"
}

Template Text

curl -X POST \
  https://api.taqnyat.sa/wa/v1/messages \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d 
  '{
        "to": [
            "966666666666",
            "966666666666"
            ],
        "message": {
            "type": "template",
            "template_name": "template_name",
            "language": "en",
            "header_params":[],
            "body_params": [],
            "ttl": "P1D"
        }
    }'

{
    "type": "whatsapp",
    "statuses": [
        {
            "message_id": "01F9V6SQD0AD630Z3WZZXF0695",
            "recipient": "+966590465693",
            "status": "success",
            "state": "queued"
        }
    ]
}

//Empty Numbers or Text Message is empty or message type is incorrect
{
    "message": "Validation Failed",
    "reason": "Field [to]: There is no list of numbers in the request"
}

//increct MSID format
{
    "message": "Validation Failed",
    "reason": "Field [message]: Parameter '{parameterPath}' must be provided."
}
 
//Invalid type for the message
{
    "message": "Validation Failed",
    "reason": "Line 15, Missing type id when trying to resolve subtype of : missing type id property 'type' (for POJO property 'message')"
}


{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

Template Image

curl -X POST \
  https://api.taqnyat.sa/wa/v1/messages \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d 
  '{
        "to": [],
        "message": {
            "type": "template",
            "template_name": "template_name",
            "language": "en",
            "header_params":[],
            "body_params": [],
            "ttl": "P1D"
        },
        "media": {
            "type": "image",
            "url": "image-url.jpg",
            "provider": "image-provider-name"
        },
    }'

{
    "type": "whatsapp",
    "statuses": [
        {
            "message_id": "01F9V6SQD0AD630Z3WZZXF0695",
            "recipient": "+966590465693",
            "status": "success",
            "state": "queued"
        }
    ]
}

//Empty Numbers or Text Message is empty or message type is incorrect
{
    "message": "Validation Failed",
    "reason": "Field [to]: There is no list of numbers in the request"
}

//increct MSID format
{
    "message": "Validation Failed",
    "reason": "Field [message]: Parameter '{parameterPath}' must be provided."
}
 
//Invalid type for the message
{
    "message": "Validation Failed",
    "reason": "Line 15, Missing type id when trying to resolve subtype of : missing type id property 'type' (for POJO property 'message')"
}


{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

Template Audio

curl -X POST \
  https://api.taqnyat.sa/wa/v1/messages \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d 
  '{
        "to": [],
        "message": {
            "type": "template",
            "template_name": "template_name",
            "language": "en",
            "header_params":[],
            "body_params": [],
            "ttl": "P1D"
        },
        "media": {
            "type": "audio",
            "url": "audio-url.mp3"
        }
    }'

{
    "type": "whatsapp",
    "statuses": [
        {
            "message_id": "01F9V6SQD0AD630Z3WZZXF0695",
            "recipient": "+966590465693",
            "status": "success",
            "state": "queued"
        }
    ]
}

//Empty Numbers or Text Message is empty or message type is incorrect
{
    "message": "Validation Failed",
    "reason": "Field [to]: There is no list of numbers in the request"
}

//increct MSID format
{
    "message": "Validation Failed",
    "reason": "Field [message]: Parameter '{parameterPath}' must be provided."
}
 
//Invalid type for the message
{
    "message": "Validation Failed",
    "reason": "Line 15, Missing type id when trying to resolve subtype of : missing type id property 'type' (for POJO property 'message')"
}


{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

Template Video

curl -X POST \
  https://api.taqnyat.sa/wa/v1/messages \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d 
  '{
        "to": [],
        "message": {
            "type": "template",
            "template_name": "template_name",
            "language": "en",
            "header_params":[],
            "body_params": [],
            "ttl": "P1D"
        },
        "media": {
            "type": "video",
            "url": "video-url",
            "provider": "Name-of-provider"
        },
    }'

{
    "type": "whatsapp",
    "statuses": [
        {
            "message_id": "01F9V6SQD0AD630Z3WZZXF0695",
            "recipient": "+966590465693",
            "status": "success",
            "state": "queued"
        }
    ]
}

//Empty Numbers or Text Message is empty or message type is incorrect
{
    "message": "Validation Failed",
    "reason": "Field [to]: There is no list of numbers in the request"
}

//increct MSID format
{
    "message": "Validation Failed",
    "reason": "Field [message]: Parameter '{parameterPath}' must be provided."
}
 
//Invalid type for the message
{
    "message": "Validation Failed",
    "reason": "Line 15, Missing type id when trying to resolve subtype of : missing type id property 'type' (for POJO property 'message')"
}


{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

Template Video

curl -X POST \
  https://api.taqnyat.sa/wa/v1/messages \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d 
  '{
        "to": [],
        "message": {
            "type": "template",
            "template_name": "template_name",
            "language": "en",
            "header_params":[],
            "body_params": [],
            "ttl": "P1D"
        },
        "media": {
            "type": "video",
            "url": "video-url",
            "provider": "Name-of-provider"
        },
    }'

{
    "type": "whatsapp",
    "statuses": [
        {
            "message_id": "01F9V6SQD0AD630Z3WZZXF0695",
            "recipient": "+966590465693",
            "status": "success",
            "state": "queued"
        }
    ]
}

//Empty Numbers or Text Message is empty or message type is incorrect
{
    "message": "Validation Failed",
    "reason": "Field [to]: There is no list of numbers in the request"
}

//increct MSID format
{
    "message": "Validation Failed",
    "reason": "Field [message]: Parameter '{parameterPath}' must be provided."
}
 
//Invalid type for the message
{
    "message": "Validation Failed",
    "reason": "Line 15, Missing type id when trying to resolve subtype of : missing type id property 'type' (for POJO property 'message')"
}


{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

Template Document

curl -X POST \
  https://api.taqnyat.sa/wa/v1/messages \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d 
  '{
        "to": [],
        "message": {
            "type": "template",
            "template_name": "template_name",
            "language": "en",
            "header_params":[],
            "body_params": [],
            "ttl": "P1D"
        },
        "media": {
            "type": "document",
            "url": "document-url.pdf",
            "provider": "Name-of-provider"
        },
    }'

{
    "type": "whatsapp",
    "statuses": [
        {
            "message_id": "01F9V6SQD0AD630Z3WZZXF0695",
            "recipient": "+966590465693",
            "status": "success",
            "state": "queued"
        }
    ]
}

//Empty Numbers or Text Message is empty or message type is incorrect
{
    "message": "Validation Failed",
    "reason": "Field [to]: There is no list of numbers in the request"
}

//increct MSID format
{
    "message": "Validation Failed",
    "reason": "Field [message]: Parameter '{parameterPath}' must be provided."
}
 
//Invalid type for the message
{
    "message": "Validation Failed",
    "reason": "Line 15, Missing type id when trying to resolve subtype of : missing type id property 'type' (for POJO property 'message')"
}


{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

Template Contact

curl -X POST \
  https://api.taqnyat.sa/wa/v1/messages \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d 
  '{
    "to": [],
    "message": {
        "type": "template",
        "template_name": "template_name",
        "language": "en",
        "header_params": [],
        "body_params": [],
        "ttl": "P1D"
    },
    "media": {
        "type": "contacts",
        "contacts": [
            {
                "addresses": [
                    {
                        "city": "Jeddah ",
                        "country": "Saudi Arabia",
                        "country_code": "sa",
                        "state": "Jeddah",
                        "street": "",
                        "type": "HOME",
                        "zip": ""
                    }
                ],
                "birthday": "1980-01-15",
                "emails": [
                    {
                        "email": "test@tsanyat.sa",
                        "type": "WORK"
                    }
                ],
                "name": {
                    "first_name": "John",
                    "formatted_name": "John Smith",
                    "last_name": "Smith"
                },
                "org": {
                    "company": "WhatsApp",
                    "department": "Design",
                    "title": "Manager"
                },
                "phones": [
                    {
                        "phone": "966 50 000 0000",
                        "type": "WORK",
                        "wa_id": "966 50 000 0000"
                    }
                ],
                "urls": [
                    {
                        "url": "https://www.taqnyat.sa",
                        "type": "WORK"
                    }
                ]
            }
        ],
        "ttl": "P1D"
    }
}'

{
    "type": "whatsapp",
    "statuses": [
        {
            "message_id": "01F9V6SQD0AD630Z3WZZXF0695",
            "recipient": "+966590465693",
            "status": "success",
            "state": "queued"
        }
    ]
}

//Empty Numbers or Text Message is empty or message type is incorrect
{
    "message": "Validation Failed",
    "reason": "Field [to]: There is no list of numbers in the request"
}

//increct MSID format
{
    "message": "Validation Failed",
    "reason": "Field [message]: Parameter '{parameterPath}' must be provided."
}
 
//Invalid type for the message
{
    "message": "Validation Failed",
    "reason": "Line 15, Missing type id when trying to resolve subtype of : missing type id property 'type' (for POJO property 'message')"
}


{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

Template Location

curl -X POST \
  https://api.taqnyat.sa/wa/v1/messages \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d 
  '{
        "to": [],
        "message": {
            "type": "template",
            "template_name": "template_name",
            "language": "en",
            "header_params":[],
            "body_params": [],
            "ttl": "P1D"
        },
        "media": {
            "type": "location",
            "lat": 00.0000,
            "lng": 00.0000,
            "name": "location name",
            "address": "adress"
        },
    }'

{
    "type": "whatsapp",
    "statuses": [
        {
            "message_id": "01F9V6SQD0AD630Z3WZZXF0695",
            "recipient": "+966590465693",
            "status": "success",
            "state": "queued"
        }
    ]
}

//Empty Numbers or Text Message is empty or message type is incorrect
{
    "message": "Validation Failed",
    "reason": "Field [to]: There is no list of numbers in the request"
}

//increct MSID format
{
    "message": "Validation Failed",
    "reason": "Field [message]: Parameter '{parameterPath}' must be provided."
}
 
//Invalid type for the message
{
    "message": "Validation Failed",
    "reason": "Line 15, Missing type id when trying to resolve subtype of : missing type id property 'type' (for POJO property 'message')"
}


{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

Conversation Text

curl -X POST \
  https://api.taqnyat.sa/wa/v1/messages \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d 
  '{
  "to": [
    "46732001122"
  ],
  "message": {
    "type": "text",
    "preview_url": false,
    "text": "Greetings from Taqnyat"
  }
}'

{
    "type": "whatsapp",
    "statuses": [
        {
            "message_id": "01F9V6SQD0AD630Z3WZZXF0695",
            "recipient": "+966590465693",
            "status": "success",
            "state": "queued"
        }
    ]
}

//Empty Numbers or Text Message is empty or message type is incorrect
{
    "message": "Validation Failed",
    "reason": "Field [to]: There is no list of numbers in the request"
}

//increct MSID format
{
    "message": "Validation Failed",
    "reason": "Field [message]: Parameter '{parameterPath}' must be provided."
}
 
//Invalid type for the message
{
    "message": "Validation Failed",
    "reason": "Line 15, Missing type id when trying to resolve subtype of : missing type id property 'type' (for POJO property 'message')"
}


{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

Conversation Image

curl -X POST \
  https://api.taqnyat.sa/wa/v1/messages \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d 
  '{
  "to": [
    "46732001122"
  ],
  "message": {
    "type": "image",
    "url": "https://example.com/image.jpg",
    "caption": "Example Image"
  }
}'

{
    "type": "whatsapp",
    "statuses": [
        {
            "message_id": "01F9V6SQD0AD630Z3WZZXF0695",
            "recipient": "+966590465693",
            "status": "success",
            "state": "queued"
        }
    ]
}

//Empty Numbers or Text Message is empty or message type is incorrect
{
    "message": "Validation Failed",
    "reason": "Field [to]: There is no list of numbers in the request"
}

//increct MSID format
{
    "message": "Validation Failed",
    "reason": "Field [message]: Parameter '{parameterPath}' must be provided."
}
 
//Invalid type for the message
{
    "message": "Validation Failed",
    "reason": "Line 15, Missing type id when trying to resolve subtype of : missing type id property 'type' (for POJO property 'message')"
}


{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

Conversation Audio

curl -X POST \
  https://api.taqnyat.sa/wa/v1/messages \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d 
  '{
  "to": [
    "46732001122"
  ],
  "message": {
    "type": "audio",
    "url": "https://example.com/song.mp3"
  }
}'

{
    "type": "whatsapp",
    "statuses": [
        {
            "message_id": "01F9V6SQD0AD630Z3WZZXF0695",
            "recipient": "+966590465693",
            "status": "success",
            "state": "queued"
        }
    ]
}

//Empty Numbers or Text Message is empty or message type is incorrect
{
    "message": "Validation Failed",
    "reason": "Field [to]: There is no list of numbers in the request"
}

//increct MSID format
{
    "message": "Validation Failed",
    "reason": "Field [message]: Parameter '{parameterPath}' must be provided."
}
 
//Invalid type for the message
{
    "message": "Validation Failed",
    "reason": "Line 15, Missing type id when trying to resolve subtype of : missing type id property 'type' (for POJO property 'message')"
}


{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

Conversation Video

curl -X POST \
  https://api.taqnyat.sa/wa/v1/messages \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d 
  '{
  "to":[
    "46732001122"
  ],
  "message":{
    "type": "video",
    "url": "https://example.com/video.mp4",
    "caption": "Example Video",
    "provider": "your-bearer-provider"
  }
}'

{
    "type": "whatsapp",
    "statuses": [
        {
            "message_id": "01F9V6SQD0AD630Z3WZZXF0695",
            "recipient": "+966590465693",
            "status": "success",
            "state": "queued"
        }
    ]
}

//Empty Numbers or Text Message is empty or message type is incorrect
{
    "message": "Validation Failed",
    "reason": "Field [to]: There is no list of numbers in the request"
}

//increct MSID format
{
    "message": "Validation Failed",
    "reason": "Field [message]: Parameter '{parameterPath}' must be provided."
}
 
//Invalid type for the message
{
    "message": "Validation Failed",
    "reason": "Line 15, Missing type id when trying to resolve subtype of : missing type id property 'type' (for POJO property 'message')"
}


{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

Conversation Video

curl -X POST \
  https://api.taqnyat.sa/wa/v1/messages \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d 
  '{
  "to":[
    "46732001122"
  ],
  "message":{
    "type": "video",
    "url": "https://example.com/video.mp4",
    "caption": "Example Video",
    "provider": "your-bearer-provider"
  }
}'

{
    "type": "whatsapp",
    "statuses": [
        {
            "message_id": "01F9V6SQD0AD630Z3WZZXF0695",
            "recipient": "+966590465693",
            "status": "success",
            "state": "queued"
        }
    ]
}

//Empty Numbers or Text Message is empty or message type is incorrect
{
    "message": "Validation Failed",
    "reason": "Field [to]: There is no list of numbers in the request"
}

//increct MSID format
{
    "message": "Validation Failed",
    "reason": "Field [message]: Parameter '{parameterPath}' must be provided."
}
 
//Invalid type for the message
{
    "message": "Validation Failed",
    "reason": "Line 15, Missing type id when trying to resolve subtype of : missing type id property 'type' (for POJO property 'message')"
}


{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

Conversation Document

curl -X POST \
  https://api.taqnyat.sa/wa/v1/messages \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d 
  '{
  "to": [
    "46732001122"
  ],
  "message": {
    "type": "document",
    "url": "https://example.com",
    "caption": "Example study",
    "filename": "document.pdf"
  }
}'

{
    "type": "whatsapp",
    "statuses": [
        {
            "message_id": "01F9V6SQD0AD630Z3WZZXF0695",
            "recipient": "+966590465693",
            "status": "success",
            "state": "queued"
        }
    ]
}

//Empty Numbers or Text Message is empty or message type is incorrect
{
    "message": "Validation Failed",
    "reason": "Field [to]: There is no list of numbers in the request"
}

//increct MSID format
{
    "message": "Validation Failed",
    "reason": "Field [message]: Parameter '{parameterPath}' must be provided."
}
 
//Invalid type for the message
{
    "message": "Validation Failed",
    "reason": "Line 15, Missing type id when trying to resolve subtype of : missing type id property 'type' (for POJO property 'message')"
}


{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

Conversation Contact

curl -X POST \
  https://api.taqnyat.sa/wa/v1/messages \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d 
  '{
  "to": [
    "46732001122"
  ],
  "message": {
    "type": "contacts",
    "contacts": [
      {
        "addresses": [
          {
            "city": "Jeddah ",
            "country": "Saudi Arabia",
            "country_code": "sa",
            
            "street": "1 Hacker Way",
            "type": "HOME",
            "zip": "23448"
          }
        ],
        "birthday": "2012-08-18",
        "emails": [
          {
            "email": "test@taqnyat.sa",
            "type": "WORK"
          }
        ],
        "name": {
          "first_name": "John",
          "formatted_name": "John Smith",
          "last_name": "Smith"
        },
        "org": {
          "company": "WhatsApp",
          "department": "Design",
          "title": "Manager"
        },
        "phones": [
          {
            "phone": "+966 50000000",
            "type": "WORK",
            "wa_id": "966920015404"
          }
        ],
        "urls": [
          {
            "url": "https://www.taqnyat.sa",
            "type": "WORK"
          }
        ]
      }
    ]
  }
}'

{
    "type": "whatsapp",
    "statuses": [
        {
            "message_id": "01F9V6SQD0AD630Z3WZZXF0695",
            "recipient": "+966590465693",
            "status": "success",
            "state": "queued"
        }
    ]
}

//Empty Numbers or Text Message is empty or message type is incorrect
{
    "message": "Validation Failed",
    "reason": "Field [to]: There is no list of numbers in the request"
}

//increct MSID format
{
    "message": "Validation Failed",
    "reason": "Field [message]: Parameter '{parameterPath}' must be provided."
}
 
//Invalid type for the message
{
    "message": "Validation Failed",
    "reason": "Line 15, Missing type id when trying to resolve subtype of : missing type id property 'type' (for POJO property 'message')"
}


{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

Conversation Location

curl -X POST \
  https://api.taqnyat.sa/wa/v1/messages \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d 
  '{
  "to": [
    "46732001122"
  ],
  "message": {
    "type": "location",
    "lat": 21.590637,
    "lng": 39.185982,
    "name": "Taqnyat Communications APLS",
    "address": "Al Makarunah Rd, Ar Rabwah, Jeddah 23448, Saudi Arabia"
  }
}'

{
    "type": "whatsapp",
    "statuses": [
        {
            "message_id": "01F9V6SQD0AD630Z3WZZXF0695",
            "recipient": "+966590465693",
            "status": "success",
            "state": "queued"
        }
    ]
}

//Empty Numbers or Text Message is empty or message type is incorrect
{
    "message": "Validation Failed",
    "reason": "Field [to]: There is no list of numbers in the request"
}

//increct MSID format
{
    "message": "Validation Failed",
    "reason": "Field [message]: Parameter '{parameterPath}' must be provided."
}
 
//Invalid type for the message
{
    "message": "Validation Failed",
    "reason": "Line 15, Missing type id when trying to resolve subtype of : missing type id property 'type' (for POJO property 'message')"
}


{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

API Reference

APIs Features:

Before you go

Base URL

Authentication

Setup Bearer token

Let us Get started:

System

System status

Voice

Send a Voice

Voice Error codes

Status

Send a Voice

Opt Out

inbound Messages

Delivery Report

Template Text

Template Image

Template Audio

Template Video

Template Video

Template Document

Template Contact

Template Location

Conversation Text

Conversation Image

Conversation Audio

Conversation Video

Conversation Video

Conversation Document

Conversation Contact

Conversation Location

API Reference #

APIs Features: #

Before you go #

Base URL #

Authentication #

Setup Bearer token #

Let us Get started: #

System #

System status #

Voice #

Send a Voice #

Voice Error codes #

Status

Send a Voice

Opt Out

inbound Messages

Delivery Report

Template Text

Template Image

Template Audio

Template Video

Template Video

Template Document

Template Contact

Template Location

Conversation Text

Conversation Image

Conversation Audio

Conversation Video

Conversation Video

Conversation Document

Conversation Contact

Conversation Location

API Reference

APIs Features:

Before you go

Base URL

Authentication

Setup Bearer token

Let us Get started:

System

System status

Voice

Send a Voice

Voice Error codes