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 vs Device API

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

ميزة	Cloud API This API	Device API
Connection Method	Meta Business Verification	QR Code Scan
Account Selection	`from_number` (phone number)	`instance_id` (UUID)
Account Selection Required	اختياري - Uses first account if not specified	مطلوب - Must specify instance_id
Template Messages	Supported	Not Supported
Free-form Messages	Only within 24-hour window	Always Allowed
Interactive Buttons	Supported	Not Supported
Best For	Business notifications, Marketing, Customer service	Personal use, Quick setup, No verification needed

Which API should I use?

Use Cloud API: If you need template messages, business verification, or interactive features.
Use Device API: If you want quick setup without Meta verification and only need basic messaging.

Account Selection Examples

Cloud API

Use from_number parameter:

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

Device API

Use instance_id parameter:

{
  "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

Sender Number Selection

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)
If not provided: The system will use the first WhatsApp account registered on your account
مهم: The number must be a Cloud API (Meta Business) account, not a Device/QR account

جسم الطلب

الحقل	النوع	مطلوب	الوصف
`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. Example: `966500000000` افتراضي: First registered WhatsApp account
`message`	string	Conditional	نص الرسالة. مطلوب إذا لم يتم توفير وسائط أو موقع أو بيانات تفاعلية
`image`	file	لا	ملف صورة (jpg, jpeg, png – حد أقصى 5 ميجابايت)
`document`	file	لا	ملف مستند (pdf, doc, docx – حد أقصى 100 ميجابايت)
`video`	file	لا	ملف فيديو (mp4 – حد أقصى 16 ميجابايت)
`audio`	file	لا	ملف صوتي – حد أقصى 16 ميجابايت
`latitude`	decimal	Conditional	Latitude for location message. Required with longitude.
`longitude`	decimal	Conditional	Longitude for location message. Required with latitude.
`cta_url_id`	integer	لا	معرف رابط الدعوة للإجراء لرسائل الأزرار التفاعلية
`interactive_list_id`	integer	لا	معرف القائمة التفاعلية

Example Request

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

Tip: 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

WhatsApp Template Policy

According to WhatsApp Business API policy:

New Conversations: You MUST use a template message to initiate a conversation with a new contact or after 24 hours of inactivity.
24-Hour Window: Free-form messages are only allowed within 24 hours after the customer last messaged you.
Template Approval: Templates must be approved by Meta before use.

Sender Number Selection

Use the from_number parameter to specify which WhatsApp account to send from:

تنسيق: Phone number with country code, WITHOUT the + sign (e.g., 966500000000)
If not provided: The system will use the first WhatsApp account registered on your account
مهم: Templates are ONLY supported on Cloud API accounts, not Device/QR accounts

جسم الطلب

الحقل	النوع	مطلوب	الوصف
`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. تنسيق: Country code + number WITHOUT + sign Example: `966500000000` افتراضي: First registered Cloud API account
`template_id`	integer	نعم	The ID of an approved WhatsApp template. Get template IDs from your Templates page.
`body_variables`	array	Conditional	Array of values to replace template body variables. Example: `["John", "Order #123"]`
`header_variables`	array	Conditional	Array of values to replace template header variables (if any).

Example Request

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\"]"

Tip: 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