Saudi Telecom Carrier APIs Integration Skill - STC, Mobily, Zain for SMS, OTP and Carrier Billing

Developing the Saudi Market? This Tool Handles All Three Operators' APIs

Recently, I've been working on an application targeting the Middle East market, and I found that integrating communication services in Saudi Arabia is a real headache. STC, Mobily, and Zain each have their own developer platforms with different documentation styles—some are even only available in Arabic, which is a real pain to go through. Then I stumbled upon this skill on GitHub, and it felt like finding a lifesaver.

This skill is essentially a Skill package that consolidates the developer APIs of Saudi Arabia's three major telecom operators. You don't need to dig through each official website's documentation one by one, nor do you need to worry about whether the authentication methods of each API are the same—it's all organized for you. Common needs like SMS sending, OTP verification codes, and carrier billing payments all come with ready-to-use curl examples you can copy directly.

First, Let's Talk About STC, the Saudi Telecom Company

STC is the largest operator in Saudi Arabia, and its developer platform, developers.stc.com.sa, offers the most comprehensive services. Besides the basic SMS and OTP APIs, there's an Identity API for user authentication, a Payment API that supports phone bill payments, and even an IoT API for managing connected devices. If you're working on smart hardware or connected vehicle projects, STC is almost the only choice.

The integration process is also quite simple. First, register an account on the developer platform, create an application to get an API Key, and then you can send requests using curl. For example, here's what sending an SMS looks like:

curl -X POST "https://developers.stc.com.sa/api/sms/v1/send" \
  -H "Authorization: Bearer ${STC_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "مرحبًا من تطبيقنا",
    "recipients": ["+966500000000"],
    "sender": "MyApp"
  }'

Notice that the message content is directly in Arabic, which makes it especially convenient when building localized applications. The OTP API is similar—just pass in the phone number, and it will automatically send the verification code using the template you specify.

Mobily's Highlights Are Email and QR Codes

Mobily's developer platform, developer.mobily.com.sa, surprisingly offers Email API and QR Code API in addition to the standard SMS and OTP services. This is quite interesting—for instance, if you want to run a marketing campaign that sends both SMS and emails while also generating QR codes with parameters, one platform can handle it all.

However, Mobily's authentication method is a bit more cumbersome, as you need to exchange your App ID and App Secret for a token. But fortunately, the documentation provides clear guidance, so just follow the steps. When sending OTPs, it also allows you to specify a language parameter, lang—passing "ar" sends an Arabic SMS, which is great for multi-language support.

Zain's Payment API Is Worth Attention

Zain's platform, developer.sa.zain.com, operates on a different set of systems: SPS is the SMS value-added service, TABS is the telecom application billing system, and SDP is the service delivery platform. What interests me most is its TABS API, which allows direct deductions from the phone bill. Users don't need to link a credit card, making it particularly useful in a country like Saudi Arabia where credit card penetration isn't very high.

For example, if you want to offer a subscription service that automatically deducts 5 riyals from the phone bill each month, you just need to call the charge endpoint:

curl -X POST "https://developer.sa.zain.com/api/tabs/v1/charge" \
  -H "Authorization: Bearer ${ZAIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "+966590000000",
    "amount": "5.00",
    "currency": "SAR",
    "description": "اشتراك شهري"
  }'

Of course, for all requests, it's strongly recommended to test in the sandbox environment first. Don't go straight to using real user phone numbers—if something goes wrong, it could negatively impact the user, and that wouldn't be good.

Installation and Configuration Are Quite Hassle-Free

This skill is installed using npx, and a single command pulls it down:

npx skills add https://github.com/Moshe-ship/hurmoz --skill saudi-telecom

After installation, you need to set three environment variables: STC_API_KEY, MOBILY_TOKEN, and ZAIN_TOKEN, corresponding to the credentials for the three operators. Then you can directly call these curl commands within your project.

A Few Tips from Experience

First, make sure to use the sandbox environment for testing. The documentation repeatedly emphasizes using test data—don't try with real identity information or payment tokens.

Second, the API styles of the three operators vary significantly. STC uses Bearer tokens, while Mobily requires exchanging credentials for a token first. Each has its own quirks, so take the time to understand the specific requirements of each platform before diving in.