How to Set Up the WhatsApp Business API in Saudi Arabia

·9 min read
How to Set Up the WhatsApp Business API in Saudi Arabia

Setting up the WhatsApp Business API for a client or your own company in Saudi Arabia (+966) from Pakistan or India is not as simple as clicking "next" on a setup wizard. You have to deal with local telecom filters, strict commercial registration checks, and specific Arabic formatting quirks that can break your message templates.

This guide is a practical walkthrough of the entire setup process. It covers what you need before you start, the exact implementation steps, how to verify your setup, and how to troubleshoot the inevitable errors that occur along the way.

What You Need Before You Start

Do not start this process until you have collected these four items. If you try to wing it, Meta will pause your setup midway, and resolving those holds can take days.

  • A Clean Phone Number: This number must be able to receive an international SMS or voice call. It cannot be active on the standard WhatsApp or WhatsApp Business mobile apps. If the number is currently active on a phone, you must delete the account from the app settings first. Merely uninstalling the app does not work.
  • Saudi Commercial Registration (CR): To scale past Meta's initial trial limits, you need a 10-digit CR number issued by the Saudi Ministry of Commerce. Meta will require a PDF copy of this document to verify your business.
  • A Meta Business Portfolio: Formerly known as Business Manager, this is where your business assets live. It should ideally be verified, though you can start development with an unverified portfolio under Meta's sandbox limits.
  • An International Payment Method: Meta bills your credit card directly for conversation charges. If you are setting this up from Pakistan or India, ensure your card has international transactions enabled and can handle charges in USD or Saudi Riyals (SAR). State Bank of Pakistan (SBP) and Reserve Bank of India (RBI) regulations often block these transactions unless pre-authorized.

Step 1: Create Your Meta Developer Application

To use the Cloud API, you must register as a developer and create an app on the Meta developer portal.

  1. Go to the Meta for Developers portal and log in with your Facebook account.
  2. Click My Apps in the top right corner, then click Create App.
  3. Select Other as your use case, then click Next.
  4. Select Business as your app type.
  5. Enter an app name. Avoid using "WhatsApp" or "Meta" in the name, as Meta's automated systems will reject it instantly. Use something like "[Your Business Name] Messaging".
  6. Select your Meta Business Portfolio from the dropdown list and click Create App.

Step 2: Link the WhatsApp Product

Once your app is created, you will be redirected to the app dashboard. Scroll down to find the list of products you can add to your app.

Find WhatsApp and click Set Up. You will be asked to associate the product with your Meta Business Portfolio. Select the portfolio you chose in the previous step and click Continue.

Meta will automatically generate a temporary phone number and a test WhatsApp Business Account (WABA) for you. This temporary sandbox number allows you to test your API integration before adding your actual Saudi phone number.

Step 3: Add and Verify Your Saudi Phone Number

This is where things often go wrong due to local telecom routing in Saudi Arabia. Here is how to add your real +966 number.

  1. In the left-hand menu of your developer dashboard, navigate to WhatsApp > API Setup.
  2. Scroll down to Step 5: Add a phone number, and click Add Phone Number.
  3. Fill in your business profile display name, category, and business description. The display name must match your Saudi CR or your public brand name. If it does not, Meta will reject it during review.
  4. Select Saudi Arabia (+966) as the country code and enter your phone number.
  5. Choose your verification method: Text Message (SMS) or Phone Call.

Crucial Warning for Saudi Telecoms: Saudi network operators (STC, Mobily, and Zain) have aggressive spam filters that frequently block international SMS verification codes from Meta. If you select SMS and do not receive the code within two minutes, do not spam the "Resend" button. This will trigger a temporary lock on your number. Instead, wait for the countdown to end, select Phone Call, and try again. The voice call verification bypasses most SMS filters.

Step 4: Configure Your Webhooks

An API is useless if you cannot receive incoming messages. You must set up a webhook to listen for events from Meta's servers.

Go to WhatsApp > Configuration in your developer portal. Click Configure a Webhook. You will need to provide a secure URL (HTTPS) from your server and a custom Verification Token (a random string you create to verify the request is coming from Meta).

Your server must respond to Meta's GET request with the exact hub.challenge value sent in the query parameters. Here is what that logic looks like in a standard Node.js Express application:

app.get('/webhook', (req, res) => {
    const mode = req.query['hub.mode'];
    const token = req.query['hub.verify_token'];
    const challenge = req.query['hub.challenge'];

    if (mode && token) {
        if (mode === 'subscribe' && token === 'YOUR_CUSTOM_TOKEN') {
            res.status(200).send(challenge);
        } else {
            res.sendStatus(403);
        }
    }
});

Once verified, change the webhook subscription fields to subscribe to messages. This ensures you receive JSON payloads whenever a Saudi customer sends you a text, image, or location.

How to Confirm Your Setup is Working

Do not write any complex code until you have verified that your basic connection works. The easiest way to test this is by sending a template message using a simple Curl command in your terminal.

Go to your API Setup page, copy your Temporary Access Token, and run the following command in your terminal. Replace YOUR_PHONE_NUMBER_ID with the ID shown on your dashboard and RECIPIENT_PHONE_NUMBER with your personal WhatsApp number (including the 966 country code, without any plus signs or leading zeros):

curl -X POST \
  'https://graph.facebook.com/v18.0/YOUR_PHONE_NUMBER_ID/messages' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "messaging_product": "whatsapp",
    "to": "RECIPIENT_PHONE_NUMBER",
    "type": "template",
    "template": {
      "name": "hello_world",
      "language": {
        "code": "en_US"
      }
    }
  }'

If the request is successful, your phone will buzz with the "hello_world" template message, and you will receive a JSON response containing a message ID. If this works, your API connection is live.

What to Do When a Step Fails

During setup, you will likely encounter errors. Here are the three most common failures we see when setting up Saudi numbers, along with their exact fixes.

Error 131030: Payment Required

This error occurs when you try to send a message to a real number but have not attached a payment method to your WABA. Even though Meta offers 1,000 free service conversations per month, you cannot send utility, marketing, or authentication messages without a card on file.

The Fix: Go to your Meta Business Suite, open Billing & Payments, select your WhatsApp Account, and add a credit card. Ensure your bank does not block international recurring payments in USD.

Error 100: Invalid Parameter (Phone Number Format)

This happens when your payload has an incorrectly formatted recipient number. Saudi numbers must be formatted without any leading zeros, spaces, or plus signs. For example, the local Saudi number 050 123 4567 must be sent to the API as 966501234567.

Error 3684422: Template Rejected

Saudi Arabia has strict consumer protection laws regarding mobile spam. If your message template is flagged as spammy, or if you do not include clear transactional context, Meta's automated systems will reject it.

The Fix: Avoid using overly aggressive sales copy in your templates. When writing Arabic templates, ensure your variables (like {{1}}) are separated by spaces. If a variable sits directly next to Arabic characters, the formatting engine can break the RTL (Right-to-Left) rendering, causing the template to fail automated checks.

Saudi Arabia Specifics: Data Residency and CITC

If you are building this for a Saudi corporate client, you will eventually be asked about regulatory compliance. The Communications, Space and Technology Commission (CITC) regulates telecommunications in Saudi Arabia. The Saudi Personal Data Protection Law (PDPL) governs how personal data is handled.

Meta's Cloud API servers are located globally (primarily in the United States and Europe). For standard commercial use cases like e-commerce, retail, real estate, and customer support, using the Cloud API is perfectly acceptable and compliant under current regulations. However, if your client is a government entity, a defense contractor, or a highly regulated local bank, they may require all data to remain on-soil.

In those rare, highly regulated scenarios, you cannot use Meta's Cloud API. You would have to deploy the On-Premises API via Docker containers on local Saudi servers (such as AWS Riyadh region or local providers like STC Cloud). We do not recommend this unless it is legally mandated. The On-Premises API requires you to manage your own database, handle software updates manually, and pay significantly higher infrastructure costs.

What to Do Next

Once your API is verified and sending messages, you will quickly realize that Meta's developer portal does not provide an interface for your customer support agents to chat with customers. The API is just a pipeline.

You have two choices. You can build a custom chat interface from scratch using your webhook payloads and database, or you can connect your API to a customer communication platform.

This is where our platform, WA Link, can help. WA Link provides a multi-agent team inbox, a visual chatbot builder, and broadcast tools that connect directly to your WhatsApp Cloud API. We do not host your WhatsApp number or handle your Meta billing; you still pay Meta directly for your API usage. WA Link simply acts as the software layer that allows your sales and support teams in Saudi Arabia to manage incoming chats, assign conversations, and automate responses without writing code.

If you choose to build your own system, your next step is to write the backend logic to parse incoming webhook payloads and store them in a database like PostgreSQL or MongoDB, ensuring you handle media attachments by calling Meta's media download endpoint.

Frequently Asked Questions

Do I need a physical SIM card inside Saudi Arabia to use the API?

You need a physical SIM or a virtual number (like a unified 9200 or toll-free 800 number) only during the initial verification step to receive the 6-digit OTP via voice call or SMS. Once the number is registered on the API, you do not need the SIM card to be active in a phone. The number runs completely on Meta's cloud servers.

Can we send promotional offers and marketing messages in Saudi Arabia?

Yes, but you must use pre-approved Marketing templates. You must also provide a clear way for users to opt out of your messages. If Saudi users frequently block or report your number for spam, your quality rating will drop from High (Green) to Medium (Yellow) or Low (Red), and Meta will automatically restrict your daily messaging limits.

How much does Meta charge for conversations in Saudi Arabia (+966)?

Meta does not charge per individual message. They charge per 24-hour conversation window. The rates vary based on who initiates the chat and the category of the template (Marketing, Utility, Authentication, or Service). Because Meta updates these rates periodically, you should check the official Meta WhatsApp Business Platform Pricing Sheets for the exact current rates for country code +966.

Share:WhatsAppFacebookXLinkedIn

Read the API documentation