📖 Technical guide and links
Official documents for connecting external systems and infrastructure details
🔑 Identity verification (Authentication)
The portal uses a system HTTP Basic Auth With support for two levels of authentication:
📌 Level 1: API authentication (for external systems)
- Required data:
Username:Password:AppId(three parts separated by colons) - Encoding: Converting text to Base64
- Header:
Authorization: Basic [Token] - Also supports:
X-Authorization: Basic [Token](For environments that rewrite the Authorization header)
📌 Second level: Control Panel authentication (UI Admin)
- Required data:
Username:Password(two parts only) - Verification is done against credentials stored in
appsettings.json - Grants valid complete Admin privileges
💻 Example of encryption
# تشفير البيانات بصيغة Base64 TOKEN=$(echo -n "myuser:mypass:1" | base64) # النتيجة: bXl1c2VyOm15cGFzczox # استخدام التوكن في الطلب curl -H "Authorization: Basic $TOKEN" https://api.wss.sa/api/v1/...
// تشفير البيانات بصيغة Base64
const credentials = "myuser:mypass:1";
const token = btoa(credentials);
// النتيجة: "bXl1c2VyOm15cGFzczox"
// استخدام التوكن
fetch(url, {
headers: { "Authorization": `Basic ${token}` }
});// تشفير البيانات بصيغة Base64
var credentials = "myuser:mypass:1";
var token = Convert.ToBase64String(Encoding.UTF8.GetBytes(credentials));
// النتيجة: "bXl1c2VyOm15cGFzczox"
client.DefaultRequestHeaders.Add("Authorization", $"Basic {token}");📱 1. Sending mobile messages (SMS)
📋 Parameters
| field | Type | Description |
|---|---|---|
| appId * | Int | Unique application code |
| message * | Object | Message object |
| receiver * | String | Future number (9665xxxxxxxx) |
| message * | String | Text message content |
💻 Code samples
curl -X POST "https://api.wss.sa/api/v1/Notification/SMS" \
-H "Authorization: Basic [TOKEN]" \
-H "Content-Type: application/json" \
-d '{
"appId": 1,
"message": {
"receiver": "9665xxxxxxxx",
"message": "محتوى الرسالة النصية"
}
}'using System.Net.Http.Json;
var client = new HttpClient();
client.BaseAddress = new Uri("https://api.wss.sa/");
client.DefaultRequestHeaders.Add("Authorization", "Basic [TOKEN]");
var payload = new {
appId = 1,
message = new {
receiver = "9665xxxxxxxx",
message = "محتوى الرسالة النصية"
}
};
var response = await client.PostAsJsonAsync("api/v1/Notification/SMS", payload);
if (response.IsSuccessStatusCode) {
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}<?php
$url = "https://api.wss.sa/api/v1/Notification/SMS";
$data = [
"appId" => 1,
"message" => [
"receiver" => "9665xxxxxxxx",
"message" => "محتوى الرسالة"
]
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Basic [TOKEN]",
"Content-Type: application/json"
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>import requests
url = "https://api.wss.sa/api/v1/Notification/SMS"
headers = {
"Authorization": "Basic [TOKEN]",
"Content-Type": "application/json"
}
payload = {
"appId": 1,
"message": {
"receiver": "9665xxxxxxxx",
"message": "رسالة تجريبية"
}
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())import okhttp3.*;
OkHttpClient client = new OkHttpClient();
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
String json = "{\"appId\": 1, \"message\": {\"receiver\": \"9665xxxx\", \"message\": \"Test\"}}";
RequestBody body = RequestBody.create(json, JSON);
Request request = new Request.Builder()
.url("https://api.wss.sa/api/v1/Notification/SMS")
.addHeader("Authorization", "Basic [TOKEN]")
.post(body)
.build();
try (Response response = client.newCall(request).execute()) {
System.out.println(response.body().string());
}💬 2. WhatsApp sending
| field | Description |
|---|---|
| appId * | Application code |
| message.receiver * | WhatsApp number in international format |
| message.templateName | Template name (if using templates) |
| message.bodyParams | Template variables are separated by a comma |
curl -X POST "https://api.wss.sa/api/v1/Notification/WhatsApp" \
-H "Authorization: Basic [TOKEN]" \
-H "Content-Type: application/json" \
-d '{
"appId": 1,
"message": {
"receiver": "9665xxxxxxxx",
"templateName": "otp_verification",
"bodyParams": "1234, 5"
}
}'using System.Net.Http.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Basic [TOKEN]");
var payload = new {
appId = 1,
message = new {
receiver = "9665xxxxxxxx",
templateName = "otp_verification",
bodyParams = "1234, 5"
}
};
await client.PostAsJsonAsync("https://api.wss.sa/api/v1/Notification/WhatsApp", payload);<?php
$url = "https://api.wss.sa/api/v1/Notification/WhatsApp";
$data = [
"appId" => 1,
"message" => [
"receiver" => "9665xxxxxxxx",
"templateName" => "otp_verification",
"bodyParams" => "1234, 5"
]
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Basic [TOKEN]", "Content-Type: application/json"]);
$response = curl_exec($ch);
?>import requests
url = "https://api.wss.sa/api/v1/Notification/WhatsApp"
payload = {
"appId": 1,
"message": {
"receiver": "9665xxxxxxxx",
"templateName": "otp_verification",
"bodyParams": "1234, 5"
}
}
requests.post(url, json=payload, headers={"Authorization": "Basic [TOKEN]"})import okhttp3.*;
OkHttpClient client = new OkHttpClient();
String json = "{\"appId\": 1, \"message\": {\"receiver\": \"9665xx\", \"templateName\": \"otp\"}}";
RequestBody body = RequestBody.create(json, MediaType.parse("application/json"));
Request request = new Request.Builder()
.url("https://api.wss.sa/api/v1/Notification/WhatsApp")
.addHeader("Authorization", "Basic [TOKEN]")
.post(body)
.build();📧 3. Send an email
| field | Description |
|---|---|
| appId * | Application code |
| message.receiver * | Recipient's email |
| message.subject * | Message title |
| message.message * | Content (HTML supported) |
curl -X POST "https://api.wss.sa/api/v1/Notification/Email" \
-H "Authorization: Basic [TOKEN]" \
-H "Content-Type: application/json" \
-d '{
"appId": 1,
"message": {
"receiver": "user@domain.com",
"subject": "تنبيه من النظام",
"message": "<h1>محتوى HTML</h1>"
}
}'using System.Net.Http.Json;
var client = new HttpClient();
var data = new {
appId = 1,
message = new {
receiver = "user@domain.com",
subject = "Hello",
message = "<h1>World</h1>"
}
};
await client.PostAsJsonAsync("https://api.wss.sa/api/v1/Notification/Email", data);<?php
$url = "https://api.wss.sa/api/v1/Notification/Email";
$data = [
"appId" => 1,
"message" => [
"receiver" => "user@domain.com",
"subject" => "Subject",
"message" => "Body"
]
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Basic [TOKEN]", "Content-Type: application/json"]);
$response = curl_exec($ch);
?>import requests
url = "https://api.wss.sa/api/v1/Notification/Email"
payload = {
"appId": 1,
"message": {
"receiver": "user@domain.com",
"subject": "Hello",
"message": "Content"
}
}
requests.post(url, json=payload, headers={"Authorization": "Basic [TOKEN]"})import okhttp3.*;
OkHttpClient client = new OkHttpClient();
String json = "{\"appId\": 1, \"message\": {\"receiver\": \"u@d.com\"}}";
RequestBody body = RequestBody.create(json, MediaType.parse("application/json"));
Request request = new Request.Builder()
.url("https://api.wss.sa/api/v1/Notification/Email")
.addHeader("Authorization", "Basic [TOKEN]")
.post(body)
.build();🔔 4. Phone Notifications (FCM Push)
📋 Parameters
| field | Type | Description |
|---|---|---|
| appId * | Int | Unique application code |
| message * | Object | Notification object |
| receiver * | String | FCM Device Token of the target device |
| message * | String | Notice content |
💻 Code samples
curl -X POST "https://api.wss.sa/api/v1/Notification/FCM" \
-H "Authorization: Basic [TOKEN]" \
-H "Content-Type: application/json" \
-d '{
"appId": 1,
"message": {
"receiver": "fcm_device_token_here",
"message": "لديك إشعار جديد"
}
}'using System.Net.Http.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Basic [TOKEN]");
var payload = new {
appId = 1,
message = new {
receiver = "fcm_device_token_here",
message = "لديك إشعار جديد"
}
};
await client.PostAsJsonAsync("https://api.wss.sa/api/v1/Notification/FCM", payload);import requests
url = "https://api.wss.sa/api/v1/Notification/FCM"
payload = {
"appId": 1,
"message": {
"receiver": "fcm_device_token_here",
"message": "لديك إشعار جديد"
}
}
requests.post(url, json=payload, headers={"Authorization": "Basic [TOKEN]"})📨 5. Send bulk emails
This Endpoint allows sending a group of emails at once. Each message is processed independently—the failure of one message does not affect the rest.
📋 Parameters
| field | Type | Description |
|---|---|---|
| demand | Array | An array of EmailPublisher objects |
| appId * | Int | Application code |
| message.receiver * | String | Recipient's email |
| message.subject * | String | Message title |
| message.message * | String | Content (HTML supported) |
| message.emailCC | String | Carbon copy (separated by semicolons) |
| message.emailBCC | String | Hidden carbon copy |
💻 Code samples
curl -X POST "https://api.wss.sa/api/v1/Notification/Emails" \
-H "Authorization: Basic [TOKEN]" \
-H "Content-Type: application/json" \
-d '[
{
"appId": 1,
"message": {
"receiver": "user1@domain.com",
"subject": "تنبيه",
"message": "<h1>مرحباً</h1>"
}
},
{
"appId": 1,
"message": {
"receiver": "user2@domain.com",
"subject": "تنبيه",
"message": "<h1>أهلاً</h1>"
}
}
]'using System.Net.Http.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Basic [TOKEN]");
var emails = new[] {
new {
appId = 1,
message = new { receiver = "user1@domain.com", subject = "تنبيه", message = "مرحباً" }
},
new {
appId = 1,
message = new { receiver = "user2@domain.com", subject = "تنبيه", message = "أهلاً" }
}
};
await client.PostAsJsonAsync("https://api.wss.sa/api/v1/Notification/Emails", emails);🔍 6. Inquire about the status of the message
You can query the status of any sent message using the message identifier (MsgId) returned upon sending.
📋 Parameters
| field | Type | Description |
|---|---|---|
| appId * | Int | Application code |
| msgId * | Guid | Message ID (returned on sending) |
| messageType * | Enum | Channel type: SMS=1, WhatsApp=2, Email=3 |
💻 Code samples
curl -X GET "https://api.wss.sa/api/v1/Settings/MessageStatus?appId=1&msgId=a1b2c3d4-e5f6-7890-abcd-ef1234567890&messageType=1" \ -H "Authorization: Basic [TOKEN]"
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Basic [TOKEN]");
var appId = 1;
var msgId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
var messageType = 1; // SMS
var url = $"https://api.wss.sa/api/v1/Settings/MessageStatus?appId={appId}&msgId={msgId}&messageType={messageType}";
var response = await client.GetAsync(url);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);📊 7. Response codes
The system returns a standardized response code ServiceResponse Shows the status of the process. Here are all possible codes:
✅ Success codes
| Code | The constant | Description |
|---|---|---|
| 100 | Success | The request has been sent successfully and has been placed in the waiting list |
⚠️ Verification codes
| Code | The constant | Description |
|---|---|---|
| 11 | ExpireQuoata | The quota is insufficient — the application balance has been exhausted |
| 15 | AppNotActive | The application is inactive — it has been disabled by the administrator |
| 16 | SMSSettingNotActive | Mobile messaging setting is not functional for this app |
| 17 | EmailSettingNotActive | Email setting is not functional for this application |
| 18 | WhatsAppSettingNotActive | WhatsApp messaging setting is not functional for this app |
| 19 | PushNotificationSettingNotActive | The phone notifications setting is not functional for this app |
❌ Error codes
| Code | The constant | Description |
|---|---|---|
| -1 | Exception | Internal system error (database or message server is down) |
| -2 | FailDBSaved | Failed to save message to database |
| -3 | NotFound | The application (AppId) does not exist in the system |
| -4 | FailDBUpdate | The message was sent but the status update in the database failed |
| -5 | PushFail | Failed to send message to queue (RabbitMQ timeout) |
| -6 | ConnectionNotExists | No connection to message server (RabbitMQ) |
| -7 | BadParameter | The order data is incorrect or missing |
🏗️ System Architecture
The gateway is based on an architecture Microservices Flexible using RabbitMQ.
⬇
📄 Technical documents
All official documents of the project - you can view or download any document
Software Requirements Specification
System Requirements Specification - includes all functional and non-functional requirements for the system
High Level Design
Overall system design - includes the main components, their relationships, and the overall architecture
Low Level Design
Detailed design of the system - includes details of the classes, modules, and algorithms used
Implementation
Implementation document - details the development environment, technologies used, and the actual implementation mechanism of the system
API Docs + DB Docs
Documentation of programming interfaces and databases - details of endpoints, tables, and relationships
Deployment
Deployment and Deployment Document - Steps for deployment to production, test, and infrastructure environments
Flow Diagram
Process Flow Diagram - Visually shows the flow of data and processes within the system
Sequence Diagram
Sequence diagram - shows the chronological order of interactions between different components of a system