تواصل | مرجع API

واجهة تواصل البرمجية

واجهة RESTful لإرسال واستقبال رسائل واتساب برمجياً. كل الطلبات والردود بصيغة JSON عبر HTTPS.

الرابط الأساسي

https://twasel.io/api/v1/

البروتوكول

HTTPS فقط، UTF-8

طريقة المصادقة

API Key + Secret بالـ Headers

الحد اليومي

1,000 طلب/يوم (قابل للرفع)

المصادقة

أرفق الـ Headers التالية مع كل طلب. أنشئ المفتاح والسر من لوحة الإدارة ← تبويب API.

Header	الوصف
`X-API-Key`	المفتاح العام، يُنشأ من تبويب API بلوحة الإدارة
`X-API-Secret`	السر الخاص، يظهر مرة واحدة فقط عند الإنشاء
`Content-Type`	`application/json` لطلبات POST

حدود الاستخدام

لكل مفتاح حد يومي افتراضي 1,000 طلب. عند التجاوز يُرجع الخادم 429 Too Many Requests. تواصل مع الدعم لرفع الحد.

POST /api/v1/send/text

أرسل رسالة نصية حرة لرقم واتساب. تعمل فقط ضمن نافذة الرد الحر (24 ساعة من آخر رسالة للعميل).

المعاملات

الحقل	النوع		الوصف
`to`	string	مطلوب	رقم المستلم بصيغة دولية بدون + (مثال: 966501234567)
`body`	string	مطلوب	نص الرسالة، حد أقصى 4,096 حرف
`account_id`	integer	اختياري	معرّف الحساب، مطلوب فقط إذا كان المفتاح مرتبطاً بأكثر من حساب

مثال عملي

curl -X POST https://twasel.io/api/v1/send/text \
  -H "X-API-Key: wk_abc123..." \
  -H "X-API-Secret: ws_xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "966501234567",
    "body": "مرحباً! رسالة تجريبية من تواصل."
  }'

import requests

resp = requests.post(
    "https://twasel.io/api/v1/send/text",
    headers={
        "X-API-Key": "wk_abc123...",
        "X-API-Secret": "ws_xyz789...",
    },
    json={"to": "966501234567", "body": "مرحباً من تواصل!"}
)
print(resp.json())

const resp = await fetch("https://twasel.io/api/v1/send/text", {
  method: "POST",
  headers: {
    "X-API-Key": "wk_abc123...",
    "X-API-Secret": "ws_xyz789...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ to: "966501234567", body: "مرحباً من تواصل!" }),
});
console.log(await resp.json());

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

{
  "ok": true,
  "wa_message_id": "wamid.HBgLOTY2NTAxMjM0..."
}

{
  "ok": false,
  "error": "to_and_body_required"
}

⚡ جرّب مباشرة

X-API-Key

X-API-Secret

to

body

POST /api/v1/send/template

أرسل قالب رسالة معتمد من Meta. القوالب تعمل حتى خارج نافذة الرد الحر. كل قالب مُسلّم يُحاسب عليه لدى Meta مباشرة.

المعاملات

الحقل	النوع		الوصف
`to`	string	مطلوب	رقم المستلم بصيغة دولية بدون +
`template_name`	string	مطلوب	اسم القالب بالضبط كما هو مسجّل بـ Meta (مثال: order_confirmation)
`language`	string	اختياري	رمز اللغة (افتراضي: ar)
`components`	array	اختياري	متغيرات القالب بصيغة Meta components
`account_id`	integer	اختياري	معرّف الحساب، مطلوب فقط إذا كان المفتاح مرتبطاً بأكثر من حساب

مثال عملي

curl -X POST https://twasel.io/api/v1/send/template \
  -H "X-API-Key: wk_abc123..." \
  -H "X-API-Secret: ws_xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "966501234567",
    "template_name": "order_confirmation",
    "language": "ar",
    "components": [{
      "type": "body",
      "parameters": [
        { "type": "text", "text": "أحمد" },
        { "type": "text", "text": "ORD-1234" }
      ]
    }]
  }'

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

{
  "ok": true,
  "wa_message_id": "wamid.HBgLOTY2NTAxMjM0..."
}

{
  "ok": false,
  "error": "to_and_template_name_required"
}

⚡ جرّب مباشرة

X-API-Key

X-API-Secret

to

template_name

language

POST /api/v1/send/media

أرسل ملف وسائط (صورة، فيديو، مستند، صوت) عبر رابط HTTPS عام مباشر

المعاملات

الحقل	النوع		الوصف
`to`	string	مطلوب	رقم المستلم بصيغة دولية بدون +
`type`	string	مطلوب	image \| video \| document \| audio
`url`	string	مطلوب	رابط HTTPS مباشر وعام للملف
`caption`	string	اختياري	تعليق مرفق، حد أقصى 1,024 حرف
`account_id`	integer	اختياري	معرّف الحساب، مطلوب فقط إذا كان المفتاح مرتبطاً بأكثر من حساب

مثال عملي

curl -X POST https://twasel.io/api/v1/send/media \
  -H "X-API-Key: wk_abc123..." \
  -H "X-API-Secret: ws_xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "966501234567",
    "type": "image",
    "url": "https://example.com/product.jpg",
    "caption": "منتج جديد متوفر الآن!"
  }'

الصيغ المدعومة والحدود

النوع	الصيغ	الحد الأقصى
`image`	JPEG, PNG	5 MB
`video`	MP4, 3GPP	16 MB
`document`	PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX	100 MB
`audio`	AAC, MP3, MP4, AMR, OGG	16 MB

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

{
  "ok": true,
  "wa_message_id": "wamid.HBgLOTY2NTAxMjM0..."
}

{
  "ok": false,
  "error": "url_must_be_https"
}

POST /api/v1/trigger/flow

يشغّل مساراً من منشئ المسارات لرقم محدد عند وقوع حدث من نظامك. الحدث يجب أن يطابق المشغّل المضبوط بالمسار.

المعاملات

الحقل	النوع		الوصف
`event`	string	مطلوب	اسم الحدث كما هو مضبوط بمشغّل المسار
`to`	string	مطلوب	رقم المستلم بصيغة دولية بدون +
`vars`	object	اختياري	متغيرات إضافية تُمرر للمسار
`account_id`	integer	اختياري	معرّف الحساب، مطلوب فقط إذا كان المفتاح مرتبطاً بأكثر من حساب

مثال عملي

curl -X POST https://twasel.io/api/v1/trigger/flow \
  -H "X-API-Key: wk_abc123..." \
  -H "X-API-Secret: ws_xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order.created",
    "to": "966501234567",
    "vars": { "order_id": "ORD-1234" }
  }'

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

{
  "ok": true,
  "status": "flow_started"
}

{
  "ok": false,
  "status": "no_matching_flow"
}

GET /api/v1/templates

استعلم عن القوالب المعتمدة (APPROVED) المتاحة لحسابك أو لحساب محدد

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

الحقل	النوع		الوصف
`account_id`	integer	اختياري	تصفية حسب حساب معيّن

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

{
  "ok": true,
  "templates": [
    {
      "id": 1,
      "name": "order_confirmation",
      "category": "UTILITY",
      "language": "ar",
      "status": "APPROVED"
    },
    {
      "id": 2,
      "name": "welcome_message",
      "category": "MARKETING",
      "language": "ar",
      "status": "APPROVED"
    }
  ]
}

GET /api/v1/accounts

استعلم عن حسابات واتساب النشطة المتاحة لمفتاحك

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

{
  "ok": true,
  "accounts": [
    {
      "id": 1,
      "display_name": "الرقم الرئيسي",
      "phone_number": "+966501234567",
      "is_active": true
    }
  ]
}

جدول الأخطاء

عند حدوث خطأ، يحتوي الرد على "ok": false مع حقل error يوضّح السبب

أخطاء المصادقة

HTTP	error	السبب
`401`	`missing_credentials`	لم تُرفق Headers المصادقة مع الطلب
`401`	`invalid_key`	المفتاح غير موجود أو معطّل
`401`	`key_expired`	انتهت صلاحية المفتاح
`401`	`invalid_secret`	السر الخاص غير مطابق

أخطاء الاستخدام

HTTP	error	السبب
`429`	`rate_limit_exceeded`	تجاوز الحد اليومي للطلبات
`400`	`to_and_body_required`	حقلا to و body مطلوبان
`400`	`to_and_template_name_required`	حقلا to و template_name مطلوبان
`400`	`to_type_url_required`	حقول to و type و url مطلوبة، أو النوع غير مدعوم
`400`	`account_id_required`	المفتاح مرتبط بعدة حسابات، حدّد account_id
`400`	`url_must_be_https`	رابط الوسائط يجب أن يكون HTTPS
`422`	`outside_customer_window`	انتهت نافذة الرد الحر، يمكن إرسال قوالب فقط
`403`	`permission_denied`	المفتاح لا يملك صلاحية تنفيذ هذا الإجراء
`403`	`invalid_account`	الحساب لا ينتمي لمشروعك
`404`	`unknown_endpoint`	رابط API غير موجود
`404`	`account_not_found`	الحساب غير موجود أو معطّل
`405`	`method_not_allowed`	HTTP method غير مسموح (مثال: أرسلت GET بدل POST)
`502`	(Meta)	خطأ مباشر من خوادم Meta أثناء الإرسال

ملاحظات عامة

البند	التوضيح
نافذة الرد الحر	send/text يعمل فقط خلال 24 ساعة من آخر رسالة واردة من العميل. بعدها استخدم send/template. التسعير لدى Meta يكون لكل رسالة قالب مُسلّمة.
صيغة الرقم	رقم دولي كامل بدون + أو مسافات، مثال: 966501234567
الترميز	UTF-8، النصوص العربية مدعومة بالكامل بالرسائل والقوالب
HTTPS إلزامي	الطلبات عبر HTTP بدون تشفير مرفوضة
الصلاحيات	كل مفتاح له صلاحيات يحدّدها المدير، صلاحية ناقصة تُرجع 403