Introduction #

Taqnyat is a licensed company from CITC in the Saudi Arabia kingdom, recently we have signed an agreement with a verified WhatsApp Business Solutions Provider specializing in WhatsApp Business API Access and hosting.

As a Provider for official business solution providers, we host the WhatsApp Business API. You can access and use the API by calling the endpoints provided, The WhatsApp Business API uses a REST API Architecture with JSON data formats. The API follows the standard HTTP request-response exchange.

also in Taqnyat, we have many other channels that can be provided for our customers, like SMS, Voice, Email, and Push notification, we just recently added the WhatsApp business API to the list with a variety of features WhatsApp already included for years WhatsApp is known as a preferred channel for users with more than 2.4 billion around the globe.

Why Taqnyat #

why go with taqnyat no directly with Whatsapp or any other business solution providers.

first of all, we need to clarify that WhatsApp business API is a limited access service provided by Meta, Facebook company and going directly to WhatsApp is not recommended by WhatsApp them self, and they strongly advise businesses to work with one of the solution providers listed in a directory provided by Facebook.

most of the business solution providers are not available in the MENA, and if they are they don't have support for Arabic or are licensed from CITC, unlike us since taqnyat provide a flexible solution for the business and help them all the way to get started and keep them updated with 24/7/365 supporting, also taking care the tech, and business issues scale them and put 100% power to resolve them in no time.

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:

• Following Facebook Display Name Guidelines.
• Going through Business Verification.
• Following WhatsApp's legal policies, including the WhatsApp Commerce Policy and the WhatsApp Business Policy.

WhatsApp Business API Prerequisites #

Before a business can access the WhatsApp Business API, each client has to go through an approval procedure, and list of requirments are needed.

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, notification message (template) , and customer care messages , each customer care messages last for 24h of the last message sent by end user
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.
6. you must have all the prerequirments needed to activate the service

Pricing #

WhatsApp has switched from a notification-based pricing model to a conversation-based pricing model. Businesses are charged per conversation, which includes all messages delivered in a 24 hour session.

How It Works WhatsApp Business API conversations fall into two categories that are priced differently:

• User-initiated: A conversation that initiates in response to a user message. Whenever a business replies to a user within the 24 hour customer service window, that message will be associated with a user-initiated conversation. Businesses can send free-form messages within this 24 hour customer service window.
• Business-initiated: A conversation that initiates from a business sending a user a message outside the 24 hour customer service window. Messages that initiate a business-initiated conversation will require a message template.

All conversations are measured in fixed 24-hour sessions. A conversation starts when the first business message in a conversation is delivered, either initiated by the business or in reply to a user message. Businesses and users can exchange any number of messages, including template messages, within a 24 hour conversation session without incurring additional charges. Each 24 hour conversation session results in a single charge.

Charges for conversations are based on the user’s country code. A user here is defined as the customer that your business is communicating with. Rates for business-initiated and user-initiated conversations vary by country or region.

You can download the individual rate cards and find the country to region mapping for countries where regional rates apply whatsapp price list .

Prerequisites #

To start using the WhatsApp Business API, you will need the following:

• A Facebook Business ID (with a verified Business if possible)
• A valid phone number with the ability to receive phone calls or SMS
• A callback server (typically provided by your Software Partner)

Facebook Business ID #

You need to have a Facebook Business ID before you can proceed to the WhatsApp approval process. To find your Business ID, log into the Facebook Business Manager of the business and navigate to Business Settings. The Business Manager ID is displayed under the business name.

If you don’t have a verified Facebook Business account, you need to create a Facebook Business Manager. To create a Business Manager:

1. Go to business.facebook.com/overview.
2. Click Create Account.
3. Enter a name for your business, your name and work email address and click Next.
4. Enter your business details and click Submit. More information about the creation of the Facebook Business Manager you can find here .

Message On Behalf request #

After the Facebook Business Manager ID is provided, you will receive a Message on Behalf request. You need to accept it, so Taqnyat can send messages on your behalf with your Facebook Business Manager ID.

Please navigate in your Facebook Business Manager Account to Requests > Received to accept the request.

WhatsApp approval procedure #

Start the process of verifying your business in Facebook Business Manager. This procedure helps to protect users from false information.

It can take some time for Facebook to check all the details and approve your Business Verification.

Phone number, Display Name & Review Process #

After the verification is successful, you will be able to add your phone number and the Display Name for your WhatsApp business profile. During the WhatsApp approval procedure, the WhatsApp team reviews the client’s request according to the WhatsApp Business Policy . You can check the status in the Facebook Business Manager account.

Official Business Account (Green Badge) #

In contrast to the regular Business Account, an Official Business Account will receive a green checkmark in the WhatsApp profile.

Requirements for approval #

To receive the status, the company needs to reach a number of notability requirements.

This is why Official Business Account applications rarely get approved. Please apply for an OBA only if you're sure that your business is notorious and impactful enough for Facebook's requirements.

Understanding Notability #

Notability requires a business to represent a well-known, often searched brand or entity. This should not be taken as a signal of the authenticity of the business. A business is considered authentic if they have gone through the Business Verification which verifies the business as a legal entity and their access to the business.

Notability, on the other hand, reflects substantial presence in online news articles. Notability is assessed based on an account’s presence in news articles from publications with sizable audiences. Facebook does not consider paid or promotional content as sources for review, including business or app listings.

Official business accounts are issued at the phone number and display name level. Facebook assesses notability for the Display Name of the business account that is requesting OBA status —If the display name is changed after receiving the OBA status, the account will need to go through the approval process again.

Additionally, previous OBA approvals within a WhatsApp Business Account do not guarantee approval for other numbers (with different display names) associated with that account. If your WABA contains one main parent brand and the phone number associated with that brand meet notability requirements, we suggest updating the display names for the child brands as follows: '{{sub-brand name}} by {{notable name}}'.

Denied Requests #

If your OBA request has been denied, it means the Facebook team has carefully reviewed your account, and unfortunately, your account is not eligible for the OBA status at this time. Currently, these decisions cannot be appealed.

Businesses can continue to grow their presence and wait 90 days before submitting another Official Business Account request —It may take time to build the business's presence in news articles as described above.

In the meantime, this decision doesn't limit your ability to share your business details. Each phone number also has a business profile which includes profile picture, email, website, and business description. These are fields that you can edit at any time.

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 Content Types #

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.

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 #

version 1 /wa/v1/ endpoints have been deprecated and you must use the new version starting from 01/02/2022.

Enable Contacts #

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

• Expected: People have already opted in to receive this information from the business over WhatsApp so are not surprised when the business messages them.
• Relevant: The messages are personalized to the specific person (Ex: based on recent purchases or recent engagement with the business, personalized content in the message itself), concise, contain necessary information, and clearly outline any next steps for the person.
• Timely: People receive these messages when they are relevant.

Opt-In #

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

The WhatsApp Business Policy outlines the following requirements:

• Businesses must clearly state that a person is opting in to receive messages from the business over WhatsApp
• Businesses must clearly state the business’ name that a person is opting in to receive messages from
• Businesses must comply with applicable law

Constraints

• If you check too many phone numbers without sending messages to them, you will be banned. Only check only phone numbers critical to your business for which you have already received customer opt-in.
• At this time, there is no callback to inform you when a WhatsApp user joins or leaves the network, so you must check contacts frequently.

Blocking #

There are two options for the blocking parameter: no_wait and wait. If the blocking parameter is not specified in a call it is no_wait by default.

The blocking parameter determines whether the request should wait for the processing to complete (synchronous) or not (asynchronous).

no_wait : The processing of the phone numbers is asynchronous. he API response may include some numbers with status set to processing. If that happens, we recommend you follow these steps:

1. You get an API response with some numbers marked as processing.
2. Issue another check contact request including the numbers with the processing status.
3. If the processing is done in your new request, you get a correct status for that number (valid or invalid).
4. If you still see numbers marked as processing, repeat step 2 until you have an answer for each number.

wait : The processing of the numbers is synchronous. You see the final status for all of the contacts after syncing with server. This setting makes the query block wait until the numbers have all been checked before returning results. This might take some time.

Phone Number Formats #

The phone numbers in the contacts API request can be in any dialable format.

Settings #

Media Provider #

Media providers used for sending media links. A providers list allows you to have different media providers for the same provider type while being able to pick a provider to use on a per request basis.

Config Object #

the config object can be a number of types

Basic type

bearer token

Messages #

Use the messages node to send text messages, media/documents, and message templates to your customers.

Message API calls are sent to the /messages endpoint regardless of message type, but the content of the JSON message body differs for each type of message (text, image, etc.). See the following documentation for information regarding the type of messages you want to send:

Text Messages #

You need to meet all the prerequisites listed in the Before You Start section of the Messages documentation.

The following types of message are supported: text, message templates, images, documents and audio.

By default, the mobile WhatsApp application recognizes URLs and makes them clickable. To include a URL preview, include "preview_url": true in the message body and make sure the URL begins with http:// or https://. A hostname is required, IP addresses are not matched.

Text Object #

Template Messages #

You need to meet all the prerequisites listed in the Before You Start section of the Messages documentation.

Template Object #

The components object #

Parameter Objects #

Media Messages #

Use the messages node to send messages containing audio, documents, images, stickers, or videos to your customers.

In essence, when you send a message that includes media, you must provide a link to the media in the request body. You must also specify the type of media that you are sending: audio, document, image, sticker, or video. When the request is received, the media is uploaded to the WhatsApp server and sent to the user indicated in the to field.

Currently, there are two ways to send media messages with the WhatsApp Business API:

• IDs To use an ID, you must first upload the media using the media node to obtain the ID required for the messages API call.
• Links To use a link, you supply an HTTP(S) link from which the application will download the media, saving you the step of uploading media yourself.

Before You Start #

You need:

• To meet all the prerequisites listed in the Before You Start section of the Messages documentation.
• To upload the media you're sending or have a link to it.

Media Image #

Media Image is one of the whatsapp messages type can be send , it use /messages/ endpoint .

Image Object #

Provider Object #

Media Audio #

Audio Object #

Media Video #

Video Object #

Media Document #

Document Object #

Media Location #

Location Object #

Media Contacts #

Contacts Object #

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 #

Delivery Report Callback #

The following webhook is received when a business sends a message as part of a user-initiated conversation (if that conversation did not originate in a free entry point):

Message States #

Status: Message Sent #

{
   "statuses": [{
     "id": "ID",
     "recipient_id": "WHATSAPP_ID",
     "status": "sent",
     "timestamp": "TIMESTAMP",
     "type": "message",
     "conversation": {
       "id": "CONVERSATION_ID",
       "expiration_timestamp": TIMESTAMP,
       "origin": {
         "type": "user_initiated"
       }
      },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "user_initiated"
    }
   }]
}

The following webhook is received when a business sends a message as part of a business-initiated conversation:

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "sent",
    "timestamp": "TIMESTAMP",
    "type": "message",
    "conversation": {
      "id": "CONVERSATION_ID",
      "expiration_timestamp": TIMESTAMP,
      "origin": {
         "type": "business_initiated"
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "business_initiated"
    }
   }]
}

The following webhook is received when a business sends a message in reply to a user-initiated conversation originating from free entry points:

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "sent",
    "timestamp": "TIMESTAMP",
    "type": "message",
    "conversation": {
      "id": "CONVERSATION_ID",
      "expiration_timestamp": TIMESTAMP,
      "origin": {
         "type": "referral_conversion",
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": false,
      "category": "referral_conversion"
    }
   }]
}

Status: Message Delivered #

The following webhook is received when a business’ message is delivered and that message is part of a user-initiated conversation (if that conversation did not originate in a free entry point):

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "delivered",
    "timestamp": "TIMESTAMP",
    "type": "message",
    "conversation": {
      "id": "CONVERSATION_ID",
      "origin": {
         "type": "user_initiated"
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "user_initiated"
    }
  }]
}

The following webhook is received when a business’ message is delivered and that message is part of a business-initiated conversation:

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "delivered",
    "timestamp": "TIMESTAMP",
    "type": "message",
    "conversation": {
      "id": "CONVERSATION_ID",
      "origin": {
         "type": "business_initiated"
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "business_initiated"
    }
  }]
}

The following webhook is received when a business’ message is delivered and that message is part of a user-initiated conversation originating from a free entry point:

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "delivered",
    "timestamp": "TIMESTAMP",
    "type": "message",
    "conversation": {
      "id": "CONVERSATION_ID",
      "origin": {
         "type": "referral_conversion",
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": false,
      "category": "referral_conversion"
    }
  }]
}

Status: Message Read #

Standard callback for a message read:

{
  "statuses":[{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "read",
    "timestamp": "TIMESTAMP",
    "type": "message"
  }]
}

Status: Message Failed #

Error code 470

{
  "statuses": [{
    "errors": [{
      "code": 470,
      "title": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid HSM notification or reconsider." 
    }],
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "failed",
    "timestamp": "TIMESTAMP"
  }]
}

Error code 480

{
  "statuses": [{
      "errors": [{
          "code": 480,
          "title": "Failed to send message since we detect an identity change of the contact"
      }],
      "id": "ID",
      "recipient_id": "WHATSAPP_ID",
      "status": "failed",
      "timestamp": "TIMESTAMP"
   }]
}

Status: Message Deleted #

Standard callback for a deleted message:

{
  "statuses": [{
        "id": "ID",
        "recipient_id": "WHATSAPP_ID",
        "status": "deleted",
        "timestamp": "TIMESTAMP",
        "type": "message"
    }]
}