Introduction

The Washeej API follows RESTful architecture standards, offering clear and consistent resource-based endpoints. All requests and responses are transmitted in JSON format, leveraging standard HTTP verbs, status codes, and authentication protocols to enable secure, efficient, and scalable integrations.

API Base URL

Please note that Washeej does not provide a sandbox or test environment. All API requests are processed in the live environment, so ensure that all request data and parameters are accurate before making any calls.

https://app.washeej.com/external-api

Authentication

All requests to the Washeej API require authentication. Each API request must include a valid client-id and client-secret to the request header, which can be obtained from your Washeej Dashboard under Developer Tools.

In addition to credentials, Washeej enforces IP-based security. You must register and enable your server’s public IP address in the IP Whitelist section of the dashboard. Requests originating from non-whitelisted IP addresses will be automatically rejected.

Both valid API credentials and an approved IP address are mandatory. Without completing these two steps, authentication will fail and API access will not be granted.

Response Format

All responses from the Washeej API are returned in JSON format. Each response follows a consistent structure and includes a status indicator, message, and relevant data payload when applicable. Standard HTTP status codes are used to represent the outcome of each request.

نموذج استجابة ناجحة

{
"status": "success",
"remark": "contact_list",
"message":[
    "Contact list fetched successfully"
],
"data": {
   ...you get all data here
    }
}

نموذج استجابة الخطأ

{
    "remark": "Unauthorized",
    "status": "error",
    "message": [
        "The client secret is required"
    ]
}

 {
    "remark": "Unauthorized",
    "status": "error",
    "message": [
        "Access to this API endpoint is restricted to IP addresses that have been explicitly whitelisted.",
        "In order to access this API endpoint, please add your IP address (::1) to the white list from the user dashboard."
    ]
}

Cloud API مقابل Device API

We offer two types of WhatsApp APIs. Choose the one that fits your needs:

ميزة	واتساب سحابي هذا الـ API	واجهة الأجهزة
طريقة الاتصال	توثيق Meta Business	مسح رمز QR
اختيار الحساب	`from_number` (رقم الهاتف)	`instance_id` (UUID)
اختيار الحساب مطلوب	اختياري - يستخدم أول حساب إذا لم يُحدد	مطلوب - يجب تحديد instance_id
رسائل القوالب	مدعوم	غير مدعوم
رسائل حرة	فقط ضمن نافذة 24 ساعة	مسموح دائماً
أزرار تفاعلية	مدعوم	غير مدعوم
الأفضل لـ	إشعارات الأعمال، التسويق، خدمة العملاء	استخدام شخصي، إعداد سريع، لا يحتاج توثيق

أي API يجب أن أستخدم؟

استخدم Cloud API: If you need template messages, business verification, or interactive features.
استخدم Device API: If you want quick setup without Meta verification and only need basic messaging.

أمثلة اختيار الحساب

واتساب سحابي

استخدم معامل from_number:

{
  "mobile_code": "966",
  "mobile": "500000000",
  "from_number": "966512345678",
  "message": "Hello!"
}

واجهة الأجهزة

استخدم معامل instance_id:

{
  "instance_id": "8_abc123xyz",
  "to": "966500000000",
  "text": "Hello!"
}


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://app.washeej.com/extern-api/contact/list',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Get Contact List

This endpoint allows you to retrieve a complete list of contacts associated with your Washeej account.

GET

contact/list

معلمات الاستعلام

معاملات الاستعلام التي تسمح لك بتخصيص استجابة API.

الاسم	الوصف	مطلوب	افتراضي
`صفحة`	يحدد رقم الصفحة المراد استرجاعها.	لا	1
`ترقيم الصفحات`	يحدد عدد العناصر المعادة لكل صفحة.	لا	20
`بحث`	البحث عن جهات الاتصال بالاسم الأول أو الأخير أو رقم الهاتف.	لا	-


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://app.washeej.com/extern-api/contact/store',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('firstname' => 'John','lastname' => 'Doe','mobile_code' => '880','mobile' => '01988'),
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

إنشاء جهة اتصال جديدة

This endpoint allows you to add a new contact to your Washeej account. Provide the necessary contact details, and upon successful request, the API returns the created contact’s information in JSON format for easy integration.

POST

/contact/store

الحقول المطلوبة

الحقول التالية مطلوبة لإنشاء جهة اتصال جديدة في النظام.

الاسم	مطلوب	افتراضي
`الاسم الأول`	نعم	-
`الاسم الأخير`	نعم	-
`رمز الهاتف`	نعم	-
`الهاتف`	نعم	-
`المدينة`	لا	-
`الولاية/المنطقة`	لا	-
`الرمز البريدي`	لا	-
`العنوان`	لا	-
`صورة الملف الشخصي`	لا	-


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://app.washeej.com/extern-api/contact/update/{contactId}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('firstname' => 'John','lastname' => 'Doe','mobile_code' => '880','mobile' => '01988'),
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

تحديث جهة الاتصال

تتيح لك نقطة النهاية هذه تحديث جهة اتصال موجودة. تحتاج فقط إلى إرسال الحقول التي تريد تعديلها. أي حقل غير مضمن في الطلب سيبقى دون تغيير.

POST

/contact/update/{id}

الحقول المطلوبة

الحقول التالية مطلوبة لإنشاء جهة اتصال جديدة في النظام.

الاسم	مطلوب	افتراضي
`الاسم الأول`	نعم	-
`الاسم الأخير`	نعم	-
`رمز الهاتف`	نعم	-
`الهاتف`	نعم	-
`المدينة`	لا	-
`الولاية/المنطقة`	لا	-
`الرمز البريدي`	لا	-
`العنوان`	لا	-
`صورة الملف الشخصي`	لا	-


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://app.washeej.com/extern-api/contact/delete/{contactId}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_POSTFIELDS => array('firstname' => 'John','lastname' => 'Doe','mobile_code' => '880','mobile' => '01988'),
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

حذف جهة اتصال

تتيح لك نقطة النهاية هذه حذف جهة اتصال بمعرفها الفريد. قد يكون الحذف مقيداً إذا كانت جهة الاتصال لديها رسائل مرتبطة أو محظورة.

DELETE

/contact/delete/{id}


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://app.washeej.com/extern-api/inbox/conversation-list',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

قائمة المحادثات

استرجاع قائمة مرقمة من المحادثات للمستخدم المصادق، بما في ذلك معلومات جهة الاتصال وحالة المحادثة.

GET

/inbox/conversation-list

معلمات الاستعلام

الاسم	الوصف	افتراضي
`status`	تصفية المحادثات حسب الحالة. استخدم القيمة أدناه لتصفية المحادثة عبر الحالة. Done = 1; Pending = 2; Important = 3; Unread = 4;	الكل
`صفحة`	يحدد رقم الصفحة المراد استرجاعها.	1
`ترقيم الصفحات`	يحدد عدد العناصر المعادة لكل صفحة.	20


$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://app.washeej.com/extern-api/inbox/change-conversation-status/2',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('status' => '1'),
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

تغيير حالة المحادثة

تحديث حالة المحادثة مثل معلقة أو منجزة أو مهمة. هنا منجزة = 1، معلقة = 2، مهمة = 3، غير مقروءة = 4

POST

/inbox/change-conversation-status/{conversation_id}

معاملات الرابط

معامل	النوع	الوصف
`conversation_id`	integer	المعرف الفريد للمحادثة

جسم الطلب

الحقل	النوع	مطلوب
`status`	integer	YEs


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://app.washeej.com/extern-api/inbox/conversation-details/2',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_POSTFIELDS => array('status' => '1'),
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

تفاصيل المحادثة

استرجاع التفاصيل الكاملة للمحادثة بما في ذلك معلومات جهة الاتصال والملاحظات والوسوم وارتباطات القوائم.

GET

/inbox/conversation-details/{conversation_id}

معاملات الرابط

معامل	النوع	الوصف
`conversation_id`	integer	المعرف الفريد للمحادثة

إرسال رسالة

إرسال رسائل واتساب إلى رقم هاتف. تدعم نقطة النهاية هذه النصوص والوسائط والموقع والقوائم التفاعلية وروابط CTA ورسائل التجارة الإلكترونية. إذا لم يتم العثور على جهة اتصال أو محادثة موجودة للرقم المقدم، سيتم إنشاء جهة اتصال ومحادثة جديدة تلقائياً.

POST

/inbox/send-message

اختيار رقم المرسل

Use the from_number parameter to specify which WhatsApp account to send from when you have multiple accounts.

تنسيق: Phone number with country code, WITHOUT the + sign (e.g., 966500000000)
إذا لم يتم تحديده: سيستخدم النظام أول حساب واتساب مسجل في حسابك
مهم: يجب أن يكون الرقم حساب Cloud API (Meta Business)، وليس حساب جهاز/QR

جسم الطلب

الحقل	النوع	مطلوب	الوصف
`mobile_code`	string	نعم	Mobile country code WITHOUT the + sign. Example: `966` for Saudi Arabia, `1` for USA
`mobile`	string	نعم	Phone number WITHOUT country code. Example: `500000000`
`from_number`	string	اختياري	Your WhatsApp Business phone number to send from. Format: country code + number WITHOUT + sign. مثال: `966500000000` افتراضي: أول حساب واتساب مسجل
`message`	string	شرطي	نص الرسالة. مطلوب إذا لم يتم توفير وسائط أو موقع أو بيانات تفاعلية
`image`	file	لا	ملف صورة (jpg, jpeg, png – حد أقصى 5 ميجابايت)
`document`	file	لا	ملف مستند (pdf, doc, docx – حد أقصى 100 ميجابايت)
`video`	file	لا	ملف فيديو (mp4 – حد أقصى 16 ميجابايت)
`audio`	file	لا	ملف صوتي – حد أقصى 16 ميجابايت
`latitude`	decimal	شرطي	Latitude for location message. Required with longitude.
`longitude`	decimal	شرطي	Longitude for location message. Required with latitude.
`cta_url_id`	integer	لا	معرف رابط الدعوة للإجراء لرسائل الأزرار التفاعلية
`interactive_list_id`	integer	لا	معرف القائمة التفاعلية

طلب مثال

curl -X POST "https://app.washeej.com/extern-api/inbox/send-message" \
  -H "client-id: YOUR-CLIENT-ID" \
  -H "client-secret: YOUR-CLIENT-SECRET" \
  -F "mobile_code=966" \
  -F "mobile=500000000" \
  -F "from_number=966512345678" \
  -F "message=Hello! This is a test message."

نصيحة: Use the Developer Tools page to test the API with your actual credentials and generate ready-to-use code.

ملاحظات مهمة

At least one message type must be provided (text, media, or location).
Interactive messages require an active subscription plan.
جهات الاتصال المحظورة لا يمكنها إرسال أو استقبال الرسائل.
For Cloud API accounts, new conversations require a template message first (WhatsApp policy).

إرسال رسالة قالب

Send an approved WhatsApp template message to a contact. Template messages are required by WhatsApp for business-initiated conversations and are commonly used for notifications, alerts, and outbound marketing.

POST

/inbox/send-template-message

سياسة قوالب واتساب

وفقاً لسياسة واتساب للأعمال API:

محادثات جديدة: You MUST use a template message to initiate a conversation with a new contact or after 24 hours of inactivity.
نافذة 24 ساعة: Free-form messages are only allowed within 24 hours after the customer last messaged you.
موافقة القالب: Templates must be approved by Meta before use.

اختيار رقم المرسل

استخدم معامل from_number لتحديد حساب واتساب المرسل:

تنسيق: Phone number with country code, WITHOUT the + sign (e.g., 966500000000)
إذا لم يتم تحديده: سيستخدم النظام أول حساب واتساب مسجل في حسابك
مهم: القوالب مدعومة فقط على حسابات Cloud API، وليس حسابات الأجهزة/QR

جسم الطلب

الحقل	النوع	مطلوب	الوصف
`mobile_code`	string	نعم	Mobile country code WITHOUT the + sign. Example: `966` for Saudi Arabia
`mobile`	string	نعم	Phone number WITHOUT country code. Example: `500000000`
`from_number`	string	اختياري	Your WhatsApp Business phone number to send from. تنسيق: رمز الدولة + الرقم بدون علامة + مثال: `966500000000` افتراضي: أول حساب Cloud API مسجل
`template_id`	integer	نعم	The ID of an approved WhatsApp template. Get template IDs from your Templates page.
`body_variables`	array	شرطي	Array of values to replace template body variables. Example: `["John", "Order #123"]`
`header_variables`	array	شرطي	Array of values to replace template header variables (if any).

طلب مثال

curl -X POST "https://app.washeej.com/extern-api/inbox/send-template-message" \
  -H "client-id: YOUR-CLIENT-ID" \
  -H "client-secret: YOUR-CLIENT-SECRET" \
  -F "mobile_code=966" \
  -F "mobile=500000000" \
  -F "template_id=123" \
  -F "from_number=966512345678" \
  -F "body_variables=[\"John\", \"Order #456\"]"

نصيحة: Use the Developer Tools page to test the API with your actual credentials and generate ready-to-use code.

ملاحظات مهمة

يمكن إرسال قوالب واتساب المعتمدة فقط.
Template messages are required for business-initiated conversations (WhatsApp policy).
Templates are NOT supported on Device/QR channels - only Cloud API.
جهات الاتصال المحظورة لا يمكنها استقبال رسائل القوالب.
يجب ربط حساب واتساب قبل إرسال الرسائل.


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://app.washeej.com/extern-api/inbox/template-list',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

الحصول على قائمة القوالب

تتيح لك نقطة النهاية هذه جلب جميع قوالب واتساب المرتبطة بحسابك.

POST

/inbox/template-list