WhatsApp API للمطورين — ابنِ وأطلق وتوسّع

واجهة WhatsApp API محورها المطور، مع نقاط نهاية REST نظيفة وwebhooks ونماذج كود بست لغات وبنية تحتية تتوسع مع مشروعك.

const response = await fetch('https://api2whats.com/send-text', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '971501234567',
    message: 'Hello from my app!'
  })
});
const data = await response.json();
console.log(data.id); // message ID

لماذا يختار المطورون هذه الواجهة

صُممت معظم حلول WhatsApp API للمستخدمين غير التقنيين أولاً وللمطورين ثانياً. فالتوثيق مقتضب ورسائل الخطأ غير مفيدة، وتقضي وقتاً أطول في مصارعة الواجهة بدلاً من البناء بها. لقد بنينا هذه الواجهة بالعكس — المطور أولاً وكل شيء آخر ثانياً.

تُرجع كل نقطة نهاية JSON منظماً مع رموز خطأ واضحة. ولكل طلب صيغة استجابة قابلة للتنبؤ. ويتضمن التوثيق نماذج كود قابلة للتشغيل يمكنك نسخها وتشغيلها فوراً. ويسلّم نظام webhook الرسائل الواردة إلى خادمك في الوقت الفعلي مع حمولات موقّعة حتى تتمكن من التحقق من صحتها.

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

نظرة عامة على البنية

تقع الواجهة بين تطبيقك وخوادم WhatsApp. إليك ما يحدث عندما ترسل رسالة:

1. يرسل تطبيقك طلب HTTP POST إلى نقطة نهاية الواجهة
2. تصادق الواجهة على طلبك باستخدام مفتاح API في ترويسة Authorization
3. تُوجَّه الرسالة إلى مثيل WhatsApp الصحيح (إذا كان لديك أكثر من مثيل)
4. تُسلَّم الرسالة عبر اتصال WebSocket دائم إلى WhatsApp
5. تستقبل استجابة تحتوي على معرّف الرسالة وحالة التسليم
6. تُدفع تحديثات الحالة اللاحقة (مُسلّمة، مقروءة) إلى webhook الخاص بك

تستغرق الرحلة الكاملة عادةً أقل من 50 مللي ثانية. لا يوجد متصفح ولا معالجة لقطات شاشة ولا معالجة DOM. واتصال WebSocket دائم ويتعامل مع إعادة الاتصال وتحديث المصادقة واستعادة الأخطاء تلقائياً.

مرجع REST API

تتبع جميع نقاط النهاية اصطلاحات REST. تستخدم الطلبات أجسام JSON. وتستخدم الاستجابات JSON. وتتم المصادقة عبر رموز Bearer في ترويسة Authorization.

إرسال الرسائل

إدارة المثيلات

Webhooks

تكامل Webhook

الـ webhooks هي الطريقة التي تستقبل بها الرسائل الواردة. عندما يرسل شخص ما رسالة إلى رقم WhatsApp المتصل لديك، ترسل الواجهة طلب POST إلى عنوان URL الخاص بالـ webhook مع بيانات الرسالة.

تبدو حمولة webhook على هذا النحو:

{
  "event": "message",
  "instance": "instance_abc123",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "from": "971501234567",
    "message": "Hi, I need help with my order",
    "timestamp": 1691234567,
    "type": "text"
  }
}

يعالج معالج الـ webhook لديك هذه البيانات ويمكنه تشغيل أي استجابة آلية. ويدعم نظام webhook منطق إعادة المحاولة — إذا كان خادمك غير متاح مؤقتاً، تعيد الواجهة محاولة التسليم عدة مرات قبل الاستسلام.

ولأغراض الأمان، تتضمن جميع حمولات webhook ترويسة X-Signature يمكنك التحقق منها للتأكد من أن الطلب جاء فعلاً من واجهتنا وليس من جهة خارجية.

نماذج كود بست لغات

نوفر نماذج كود قابلة للتشغيل لكل عملية شائعة. كل نموذج هو سكربت كامل قابل للتشغيل — وليس مقتطفاً يتركك تتخبط بشأن الاستيرادات أو معالجة الأخطاء أو الإعداد.

PHP

<?php
$ch = curl_init('https://api2whats.com/send-text');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ***',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to' => '971501234567',
        'message' => 'Hello from PHP!',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Python

import requests

response = requests.post(
    'https://api2whats.com/send-text',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'to': '971501234567',
        'message': 'Hello from Python!',
    }
)
print(response.json())

JavaScript (Node.js)

const response = await fetch('https://api2whats.com/send-text', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        to: '971501234567',
        message: 'Hello from Node.js!',
    }),
});
const data = await response.json();
console.log(data);

معالجة الأخطاء

تستخدم الواجهة رموز حالة HTTP القياسية وتُرجع استجابات خطأ منظمة:

{
    "success": false,
    "error": {
        "code": "INSTANCE_DISCONNECTED",
        "message": "The WhatsApp instance is not connected"
    }
}

تشمل رموز الخطأ الشائعة:

• 401 Unauthorized — مفتاح API غير صالح أو مفقود
• 400 Bad Request — حقول إلزامية مفقودة أو بيانات غير صالحة
• 404 Not Found — المثيل أو المورد غير موجود
• 429 Too Many Requests — تم تجاوز حد المعدل
• 500 Internal Server Error — حدث خطأ من جانبنا (نادر)

أمان Webhook

يتضمن كل طلب webhook ترويسة X-Signature تحتوي على توقيع HMAC-SHA256 لجسم الطلب. ويجب على معالج الـ webhook لديك التحقق من هذا التوقيع للتأكد من أن الطلب جاء فعلاً من واجهتنا وليس من جهة خارجية.

// Node.js webhook signature verification
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
    const expected = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected)
    );
}

app.post('/webhook', (req, res) => {
    const sig = req.headers['x-signature'];
    const body = JSON.stringify(req.body);

    if (!verifySignature(body, sig, WEBHOOK_SECRET)) {
        return res.status(401).json({ error: 'Invalid signature' });
    }

    // Process the message...
    res.json({ success: true });
});

الاختبار وتصحيح الأخطاء

توفر الواجهة عدة أدوات لاختبار التكامل لديك وتصحيح أخطائه:

• سجلات لوحة التحكم — عرض جميع طلبات API واستجاباتها في الوقت الفعلي من لوحة التحكم
• نقطة نهاية اختبار webhook — إرسال webhook اختباري للتحقق من أن معالجك يعمل بشكل صحيح
• تتبع حالة الرسالة — الاستعلام عن حالة أي رسالة بمعرّفها
• مراقبة معدل الأخطاء — تتبع معدلات أخطاء API لديك بمرور الوقت في لوحة التحكم

نوصي بالبدء بمثيل اختباري متصل برقمك الشخصي. أرسل رسائل اختبارية وتحقق من الـ webhooks وافحص معالجة الأخطاء قبل الانتقال إلى الإنتاج مع مرور حقيقي.

أفضل الممارسات للمطورين

• خزّن مفاتيح API بشكل آمن — استخدم متغيرات البيئة، وليس السلاسل المضمّنة في الكود. ولا ترفع مفاتيح API إلى نظام التحكم بالإصدارات أبداً.
• تعامل مع الأخطاء بأناقة — نفّذ منطق إعادة محاولة مع تراجع أُسّي للأخطاء العابرة (5xx وانقطاعات الشبكة).
• تحقق من توقيعات webhook — لا تثق أبداً بطلبات webhook غير المتحقق منها. افحص ترويسة X-Signature دائماً.
• استخدم تجميع الاتصالات — أعد استخدام اتصالات HTTP عبر الطلبات بدلاً من إنشاء اتصالات جديدة لكل استدعاء API.
• راقب حدود المعدل — افحص ترويسة X-RateLimit-Remaining ونفّذ تقييداً استباقياً عند الاقتراب من الحدود.
• سجّل كل شيء — سجّل أزواج الطلب/الاستجابة لتصحيح الأخطاء. واحجب البيانات الحساسة (أرقام الهواتف ومحتوى الرسائل) في سجلات الإنتاج.

حدود المعدل

تُطبق حدود المعدل لكل مفتاح API وتختلف حسب الخطة. وتُرجع الواجهة رمز حالة 429 مع ترويسة Retry-After عند بلوغ الحد. إليك القيم الافتراضية:

• الخطة الأساسية — 100 طلب في الدقيقة
• الخطة الاحترافية — 300 طلب في الدقيقة
• خطة Enterprise — 1000 طلب في الدقيقة

إذا كنت تبلغ حدود المعدل باستمرار، ففكّر في ترقية خطتك أو تجميع الطلبات حيثما أمكن.

صيغ حمولات Webhook

تصل الرسائل الواردة بصيغ مختلفة حسب نوع الرسالة:

رسالة نصية

{
  "event": "message",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "from": "971501234567",
    "message": "Hello!",
    "type": "text",
    "timestamp": 1691234567
  }
}

رسالة صورة

{
  "event": "message",
  "data": {
    "id": "3EB0A1B2C3D4E5F7",
    "from": "971501234567",
    "type": "image",
    "caption": "Check this out!",
    "mediaUrl": "https://api2whats.com/media/...",
    "mimeType": "image/jpeg",
    "timestamp": 1691234568
  }
}

تحديث الحالة

{
  "event": "status",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "status": "delivered",
    "timestamp": 1691234600
  }
}

تشمل قيم الحالة: sent (سُلّمت إلى WhatsApp) وdelivered (وصلت إلى الجهاز) وread (فتحها المستلم).

البدء

1. أنشئ حساباً (مجاناً، دون بطاقة ائتمان)
2. اختر خطة من صفحة الأسعار
3. أنشئ مثيلاً من لوحة التحكم
4. اربط رقم هاتفك عبر رمز QR أو رمز الاقتران
5. اقرأ توثيق API الكامل
6. أرسل رسالتك الأولى وابدأ البناء

المجتمع والدعم

انضم إلى مجتمع المطورين لدينا للحصول على المساعدة ومشاركة التكاملات والبقاء على اطلاع بالميزات الجديدة. لدينا مجتمع نشط من المطورين يبنون تكاملات WhatsApp في كل صناعة.

• التوثيق — مرجع API شامل مع أمثلة قابلة للتشغيل
• نماذج الكود — سكربتات كاملة قابلة للتشغيل بـ PHP وPython وJavaScript وcURL
• دعم عبر البريد الإلكتروني — استجابة خلال 24 ساعة لجميع فئات الخطط
• سجلات لوحة التحكم — رؤية فورية لطلبات API وعمليات تسليم webhook
• صفحة الحالة — حالة النظام المباشرة وسجل الحوادث

سواء كنت تبني أول تكامل WhatsApp لك أو توسّع تكاملاً قائماً، فإن مواردنا وفريق الدعم لدينا هنا لمساعدتك على النجاح.