API Reference

Taqnyat WhatsApp Business API provides a rich, enterprise grade messaging solution for clients who wish to communicate with their customers via WhatsApp.

WhatsApp is the most popular communication and chatting app for the past few years. With its rich features, it can be a powerful platform for business owners to communicate with their clients. Therefore, WhatsApp for Business API has been introduced as a business version of WhatsApp.



Overview

WhatsApp helps more than 2 billion people connect and share with the people they care about. For businesses, WhatsApp is a simple, secure, and reliable way to reach customers.

WhatsApp offers the following solutions for businesses looking to connect with their customers: WhatsApp Business API: Recommended for medium and large businesses, the API allows companies to communicate with their customers at scale.



About whatsApp API

The WhatsApp Business API client offers many of the features provided by the WhatsApp applications you already know from Android, iOS, and Web.

The difference is that this application can be deployed on a server, providing a local API that allows you to programmatically send and receive messages and integrate this workflow with your own systems (e.g., CRMs, contact center platforms, etc.).

Be aware that, to use our API, businesses must complete a series of requirements, including, but not limited to:



Before you go

  1. We recommended the one who is going to use this documentation or APIs to have programming skills.
  2. WhatsApp business API is paid service unlike whatsapp user app and whatsapp business app.
  3. WhatsApp has two types of messages, template messages, and conversation messages and the Cost varies depending on the type of messages you are sending and destination, for WhatsApp template you may see whatsapp price list .
  4. When you send whatsApp through API, mobile numbers that will receive the message must be in international format without 00 or symbol (+)
  5. You must have an active account Registered with facebook before you go, you may contact support@taqnyat.sa or account manager to get more details about the requirements and how to activate or your Registered your number.




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.

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

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



WhatsApp Message flow

  1. Customer opt-in is essential before sending any messages.
  2. Businesses can only start a conversation with a defined message template.
  3. Once you get a reply from your customer, a customer care session starts. You can then send “session” rich content messages for 24 hours.
  4. Every time a customer replies to one of your messages, a new 24-hour cycle starts.
  5. If a “session” expires, you’ll need to re-initiate a conversation, starting with a defined message template again.
  6. Customers can start a rich content conversation with a business at any time this opens up a new 24-hour session.



Supported ContentTypes

Any media file sent through the Taqnyat WhatsApp API will be processed before it's sent to the recipient. While the maximum file size for every uploaded media is 100 MB, be aware that the file also needs to meet the post-processing limits listed below. This means that a message with a file size that is larger than the post-processing limits is not guaranteed to be sent successfully. The result will depend on whether WhatsApp's post-processing of the media file can reduce the file size sufficiently or not.

type Supported content types Limit
Image image/jpeg, image/png 5 MB
Audio audio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg, audio/opus 16 MB
Video video/mp4, video/3gpp 16 MB
Sticker image/webp 100 KB
Document Any content type listed for other message types,
text/plain,
text/csv,
application/pdf,
application/msword,
application/x-tar,
application/rtf.0,
application/vnd.ms-powerpoint,
application/vnd.openxmlformats-officedocument.presentationml.presentation,
application/vnd.openxmlformats-officedocument.wordprocessingml.document,
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,
application/vnd.oasis.opendocument.presentation,
application/vnd.oasis.opendocument.spreadsheet, application/vnd.ms-excel,
application/vnd.oasis.opendocument.text		 100 MB



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:

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

×



Base URL

Currently all WhatsApp URLs referenced in the WhatsApp documentation has the base URL: https://api.taqnyat.sa/wa/v1/



  • All Business initiated conversations via the Taqnyat WhatsApp Business API must start with an “Opt-In” by the user.
  • This can be collected through any third party. For example in an SMS message, In-Line with a Web Form, in an Email, or even via a deep-link in print media.
  • You can record an OPT-IN by the API call described below and once the “Opt-In” is recorded you’ll be able to message that customer via the Taqnyat WhatsApp Business API template messages.
  • Businesses must provide a method by which customers may OPT-OUT of receiving future messages from your organisation. The opt-out should be handled using the API call below.




Opt-In and Opt-Out

Opt-In

Opt-in numbers to enable the receiving of business messages via WhatsApp.

POST /provision/optin/

Parameters Description required
numbers number or numbers for users who is going to receive messages from the enterprise. Yes

If a customer initiates contact with a WhatsApp Business, this will constitute as a temporary opt-in meaning that the business is allowed to send messages to that customer for 24 hours since the last received message. After that period has expired, a active opt-in is required before the business is allowed to send messages to that customer again.

Opt-Out

Opt-out number(s) to prevent them from receiving messages from the business.

Delete /provision/optin/

Parameters Description required
numbers number or numbers for users who is going to receive messages from the enterprise. Yes


Opt-in policy change 9th July 2020


Updated requirements:

  • Businesses must clearly state that a user is opting in to receive messages from the business over WhatApp
  • Businesses must clearly state the name of the business that the user is opting in to receive messages from
  • Businesses must comply with applicable law

The policy will no longer dictate the following requirements that are in the current opt-in policy:

  • That opt-ins must be obtained in a third-party channel
  • That opt-in permission is obtained in-line and contextually during the relevant user flows
  • That there is a visual element (e.g. a check box) next to the WhatsApp name and logo, with adjacent language stating type of information that will be messaged
  • That businesses provide an ability to edit which WhatsApp number is used for the opt-in

Additionally, businesses should:

  • Explicitly call out the types of messages that the user is opting in to (e.g. delivery updates)
  • Avoid messaging people too frequently
  • Provide instructions for how customers can opt out and honor these requests
  • Monitor their quality rating, especially when rolling out new opt-in methods




Call Back

A callback is a HTTP POST request with a notification made by Taqnyat WhatsApp API to a URI of your choosing. Taqnyat WhatsApp API expects the receiving server to respond with a response code within the 2xx Success range. If no successful response is received then the API will retry up to three attempts.



Callback Structure

Name Description Type
type Will always be whatsapp String
statuses Array of delivery reports Array[Object]
contacts Array of inbound messages contact Array[Object]
notifications Array of inbound messages Array[Object]

  • A callback from Taqnyat WhatsApp API can contain both delivery reports and inbound messages.
  • Contacts might be placed only for text, contact and location inbound messages.



Delivery Report Callback

Name Description Type
status The status of the message, either success or failure String
state The state of the message String
message_id The message id of the message to which this delivery report belong to String
details Detailed message containing information. String
recipient The recipient of the message that this delivery report belong to String
timestamp ISO-8601 datetime of the status update String



Message States

State Description
queued Message has been received and queued by Taqnyat WhatsApp API
dispatched Message has been dispatched by Taqnyat WhatsApp API to WhatsApp servers
sent Message has been sent by WhatsApp to end-user
delivered Message has been successfully delivered to end-user by WhatsApp
read Message has been read by the end-user in the WhatsApp application
deleted Message has been deleted or expired in the application
failed Message has failed
no_opt_in Message rejected by Taqnyat API as recipient is not registered to have opted in
no_capability Message rejected by Taqnyat API as the recipient lacks WhatsApp capability




Inbound message callback

An inbound message or MO (Mobile Originated) is a message sent to one of your bots from a WhatsApp user. The format is as follows:


Notifications

Name Description Type
from MSISDN of the user sending the message String
to The identifier of the receiving bot String
replying_to A context object, present only if the user is replying to a specific thread Object
message_id Generated message id for the inbound message String
message Message object describing the inbound message Object
timestamp ISO-8601 datetime of the status update String
forwarded Boolean object stating if message was forwarded Boolean
frequently_forwarded Boolean object stating if message was frequently forwarded Boolean
referral A referral object, if the message is sent in reponse to an ad or a post Object



The following MO notification types can include a referral object:
  • Text
  • location
  • contacts
  • image
  • video
  • document
  • voice
  • sticker




Template Messages

Message API is use to send Messages to all numbers are pre opt-in only

when sending message , you should initiat the conversation with template type message , and you can spicify which template by using one of pre define templates.

other than this you are free to use the free form messages if the end user reply to your Template message or send you a message.

also you may want to specify the conversation time to live in queue waiting for receptors to receive the message using the parameter ttl (Time To Live) default time is 7 days, after that message will be deleted from the queue and fail error will be return.

Template Text Message

POST /messages/

Name Description Type Constraints Required
To List of MSISDNs String array 1 to 20 elements Yes
message Message object Object Valid Message object Yes

Template Image Message

POST /messages/



Any media file sent through the Taqnyat WhatsApp API can be at most 100.0 MB

Refer to the Supported ContentTypes for more information .

JSON object parameters:

Name Description Type Default Constraints Required
type Constant value image String N/A N/A Yes
url Public url of the image file. Should be either HTTP or HTTPS link. String N/A Accepted Content-Type header Yes
caption Optional caption that will be displayed underneath the image. String None N/A No
provider Optional name of a provider to be used when trying to download the file. String None N/A No



Template Video Message

POST /messages/



Any media file sent through the Taqnyat WhatsApp API can be at most 100.0 MB

Refer to the Supported ContentTypes for more information .

JSON object parameters:

Name Description Type Default Constraints Required
type Constant value video String N/A N/A Yes
url Public url of the video file (mp4). Should be either HTTP or HTTPS link. String N/A Accepted Content-Type header Yes
caption Optional caption that will be displayed underneath the video. String None N/A No
provider Optional name of a provider to be used when trying to download the file. String None N/A No



Template Document Message

POST /messages/



Any media file sent through the Taqnyat WhatsApp API can be at most 100.0 MB

Refer to the Supported ContentTypes for more information .

JSON object parameters:

Name Description Type Default Constraints Required
type Constant value document String N/A N/A Yes
url Public url of the document file. Should be either HTTP or HTTPS link. String N/A Accepted Content-Type header Yes
filename Optional parameter that describes the filename of the document. String None N/A No
caption Optional caption that will be displayed as the document title. String None N/A No
provider Optional name of a provider to be used when trying to download the file. String None N/A No



Template Audio Message

POST /messages/



Any media file sent through the Taqnyat WhatsApp API can be at most 100.0 MB

Refer to the Supported ContentTypes for more information .

JSON object parameters:

Name Description Type Default Constraints Required
type Constant value audio String N/A N/A Yes
url Public url of the audio file. Should be either HTTP or HTTPS link. String N/A Accepted Content-Type header Yes
provider Optional name of a provider to be used when trying to download the file. String None N/A No



Template Location Message

POST /messages/



Refer to the Supported ContentTypes for more information .

JSON object parameters:

Name Description JSON Type Default Constraints Required
type Constant value location String N/A N/A Yes
lat The latitude position as a float number. Number N/A [-90, 90] Yes
lng The longitude position as a float number. Number N/A [-180, 180] Yes
name The name for the location. Will be displayed in the message. String N/A N/A No
address The address for the location. Will be displayed in the message. String N/A N/A No



Template Contact Message

Refer to the Supported ContentTypes for more information .

POST /messages/

JSON object parameters:

Name Description JSON Type Default Constraints Required
type Constant value contacts String N/A N/A Yes
contacts List of contact cards Object array N/A Valid contact cards Yes

Conversation Messages

Message API is use to send Messages after session is beeing opened

unlike template messages you may send messages to your customer during the 24 session houre with no restrection .



Conversation Text message

Available formatting and using emojis for the text message content can be found in the introduction.

Refer to the Supported ContentTypes for more information .

POST /messages/



JSON object parameters:

Name Description Type Default Constraints Required
type Constant value text String N/A N/A Yes
preview_url Message object Boolean false true or false No
text The text message content String N/A Up to 4096 characters Yes



Conversation Image message

Any media file sent through the Taqnyat WhatsApp API can be at most 100.0 MB

Refer to the Supported ContentTypes for more information .

POST /messages/



JSON object parameters:

Name Description Type Default Constraints Required
type Constant value image String N/A N/A Yes
url Public url of the image file. Should be either HTTP or HTTPS link. String N/A Accepted Content-Type header Yes
caption Optional caption that will be displayed underneath the image. String None N/A No
provider Optional name of a provider to be used when trying to download the file. String None N/A No



Conversation Video message

Any media file sent through the Taqnyat WhatsApp API can be at most 100.0 MB

Refer to the Supported ContentTypes for more information .

POST /messages/



JSON object parameters:

Name Description Type Default Constraints Required
type Constant value video String N/A N/A Yes
url Public url of the video file (mp4). Should be either HTTP or HTTPS link. String N/A Accepted Content-Type header Yes
caption Optional caption that will be displayed underneath the video. String None N/A No
provider Optional name of a provider to be used when trying to download the file. String None N/A No



Conversation Document message

Any media file sent through the Taqnyat WhatsApp API can be at most 100.0 MB

Refer to the Supported ContentTypes for more information .

POST /messages/



JSON object parameters:

Name Description Type Default Constraints Required
type Constant value document String N/A N/A Yes
url Public url of the document file. Should be either HTTP or HTTPS link. String N/A Accepted Content-Type header Yes
filename Optional parameter that describes the filename of the document. String None N/A No
caption Optional caption that will be displayed as the document title. String None N/A No
provider Optional name of a provider to be used when trying to download the file. String None N/A No



Conversation Audio message

Any media file sent through the Taqnyat WhatsApp API can be at most 100.0 MB

Refer to the Supported ContentTypes for more information .

POST /messages/



JSON object parameters:

Name Description Type Default Constraints Required
type Constant value audio String N/A N/A Yes
url Public url of the audio file. Should be either HTTP or HTTPS link. String N/A Accepted Content-Type header Yes
provider Optional name of a provider to be used when trying to download the file. String None N/A No



Conversation Location message

Refer to the Supported ContentTypes for more information .

POST /messages/



JSON object parameters:

Name Description JSON Type Default Constraints Required
type Constant value location String N/A N/A Yes
lat The latitude position as a float number. Number N/A [-90, 90] Yes
lng The longitude position as a float number. Number N/A [-180, 180] Yes
name The name for the location. Will be displayed in the message. String N/A N/A No
address The address for the location. Will be displayed in the message. String N/A N/A No



Conversation Contacts message

Refer to the Supported ContentTypes for more information .

POST /messages/



JSON object parameters:

Name Description JSON Type Default Constraints Required
type Constant value contacts String N/A N/A Yes
contacts List of contact cards Object array N/A Valid contact cards Yes