ابنِ مع واجهة واتساب

ادمج مراسلة واتساب في تطبيقاتك عبر واجهتنا RESTful.

RESTful JSON Webhooks

البدء

1 احصل على مفتاح API

ولّد مفتاح API من لوحة البوابة الخاصة بك: /my/whatsapp/api-keys

2 اضبط ترويسة Authorization

                                
                                Authorization: Bearer YOUR_API_KEY
                            

3 أرسل أول طلب

curl -X POST https://www.procomrades.com/api/v1/wa/send/text \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+1234567890", "text": "Hello from the API!"}'

نطاقات API

النطاق	الوصف
`messages`	إرسال واستقبال رسائل واتساب (نص، وسائط، قوالب)
`conversations`	قراءة المحادثات وإسنادها وإغلاقها
`contacts`	إدارة قوائم جهات اتصال واتساب وسماتها
`templates`	إنشاء وتحديث وحذف قوالب الرسائل
`campaigns`	إطلاق ومتابعة حملات الرسائل الجماعية

مرجع API

Messages

POST


                                                            /api/v1/wa/send/text

Send text message

Send a plain-text WhatsApp message to a phone number.

النطاقات المطلوبة: messages:write

محتوى الطلب

{
  "phone": "+1234567890",
  "text": "Hello from the API!",
  "account_id": 1
}

الاستجابة

{
  "success": true,
  "message_id": 42,
  "wa_id": "wamid.HBgL..."
}

POST


                                                            /api/v1/wa/send/template

Send template message

Send an approved WhatsApp template message with optional dynamic components.

النطاقات المطلوبة: messages:write

محتوى الطلب

{
  "phone": "+1234567890",
  "template_name": "order_confirmation",
  "language": "en_US",
  "components": [
    {
      "type": "body",
      "parameters": [
        {"type": "text", "text": "John"},
        {"type": "text", "text": "#ORD-1234"}
      ]
    }
  ]
}

الاستجابة

{
  "success": true,
  "message_id": 43,
  "wa_id": "wamid.HBgL..."
}

POST


                                                            /api/v1/wa/send/media

Send media message

Send an image, video, document, or audio message.

النطاقات المطلوبة: messages:write

محتوى الطلب

{
  "phone": "+1234567890",
  "media_type": "image",
  "media_url": "https://example.com/photo.jpg",
  "caption": "Check this out!",
  "account_id": 1
}

الاستجابة

{
  "success": true,
  "message_id": 44,
  "wa_id": "wamid.HBgL..."
}

POST


                                                            /api/v1/wa/send/interactive

Send interactive message

Send a message with buttons, lists, or other interactive elements.

النطاقات المطلوبة: messages:write

محتوى الطلب

{
  "phone": "+1234567890",
  "interactive": {
    "type": "button",
    "body": {"text": "Choose an option:"},
    "action": {
      "buttons": [
        {"type": "reply", "reply": {"id": "opt1", "title": "Option 1"}},
        {"type": "reply", "reply": {"id": "opt2", "title": "Option 2"}}
      ]
    }
  },
  "account_id": 1
}

الاستجابة

{
  "success": true,
  "message_id": 45,
  "wa_id": "wamid.HBgL..."
}

Conversations

GET


                                                            /api/v1/wa/conversations

List conversations

Retrieve a paginated list of WhatsApp conversations.

النطاقات المطلوبة: conversations:read

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

المعامل	النوع	مطلوب	الوصف
`status`	string	No	Filter by status (open, closed, expired)
`limit`	integer	No	Max records to return
`offset`	integer	No	Number of records to skip

الاستجابة

{
  "data": [
    {
      "id": 1,
      "phone": "+1234567890",
      "status": "open",
      "contact_name": "John Doe",
      "last_message_at": "2025-06-15T10:30:00Z"
    }
  ],
  "count": 124
}

GET


                                                            /api/v1/wa/conversations/{id}

Get conversation

Retrieve a single conversation with its last 50 messages.

النطاقات المطلوبة: conversations:read

الاستجابة

{
  "id": 1,
  "phone": "+1234567890",
  "status": "open",
  "contact": {
    "id": 10,
    "name": "John Doe",
    "phone": "+1234567890"
  },
  "messages": [
    {
      "id": 501,
      "direction": "inbound",
      "body": "Hi there!",
      "timestamp": "2025-06-15T10:30:00Z"
    }
  ]
}

POST


                                                            /api/v1/wa/conversations/{id}/reply

Reply to conversation

Send a text reply within an existing conversation.

النطاقات المطلوبة: conversations:write

محتوى الطلب

{
  "text": "Thanks for reaching out!"
}

الاستجابة

{
  "success": true
}

Contacts

GET


                                                            /api/v1/wa/contacts

List contacts

Retrieve a paginated list of WhatsApp contacts.

النطاقات المطلوبة: contacts:read

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

المعامل	النوع	مطلوب	الوصف
`limit`	integer	No	Max records to return
`offset`	integer	No	Number of records to skip

الاستجابة

{
  "data": [
    {
      "id": 10,
      "phone": "+1234567890",
      "name": "John Doe",
      "tags": ["vip", "support"]
    }
  ],
  "count": 350
}

POST


                                                            /api/v1/wa/contacts

Create or find contact

Create a new contact or return an existing one matched by phone number.

النطاقات المطلوبة: contacts:write

محتوى الطلب

{
  "phone": "+1234567890",
  "name": "John Doe"
}

الاستجابة

{
  "success": true,
  "contact_id": 10
}

PUT


                                                            /api/v1/wa/contacts/{id}

Update contact

Update an existing contact's name or tags.

النطاقات المطلوبة: contacts:write

محتوى الطلب

{
  "name": "John D.",
  "tags": ["vip"]
}

الاستجابة

{
  "success": true
}

Templates

GET


                                                            /api/v1/wa/templates

List approved templates

Retrieve all approved WhatsApp message templates for the account.

النطاقات المطلوبة: templates:read

الاستجابة

{
  "data": [
    {
      "id": 5,
      "template_name": "order_confirmation",
      "category": "UTILITY",
      "language": "en_US",
      "status": "approved",
      "body": "Hi {{1}}, your order {{2}} has been confirmed."
    }
  ]
}

Campaigns

GET


                                                            /api/v1/wa/campaigns

List campaigns

Retrieve a paginated list of WhatsApp campaigns.

النطاقات المطلوبة: campaigns:read

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

المعامل	النوع	مطلوب	الوصف
`state`	string	No	Filter by state (draft, scheduled, sent, cancelled)
`limit`	integer	No	Max records to return
`offset`	integer	No	Number of records to skip

الاستجابة

{
  "data": [
    {
      "id": 3,
      "name": "Summer Promo",
      "state": "draft",
      "template_id": 5,
      "audience_count": 1200,
      "scheduled_at": null
    }
  ],
  "count": 8
}

POST


                                                            /api/v1/wa/campaigns

Create campaign

Create a new WhatsApp campaign in draft state.

النطاقات المطلوبة: campaigns:write

محتوى الطلب

{
  "name": "Summer Promo",
  "template_id": 5,
  "audience_domain": [["tag_ids.name", "=", "vip"]],
  "scheduled_at": "2025-07-01T09:00:00Z"
}

الاستجابة

{
  "success": true,
  "campaign_id": 3
}

POST


                                                            /api/v1/wa/campaigns/{id}/send

Send campaign

Immediately send a draft or scheduled campaign.

النطاقات المطلوبة: campaigns:write

محتوى الطلب

{}

الاستجابة

{
  "success": true,
  "state": "sending"
}

Usage

GET


                                                            /api/v1/wa/usage

Get usage stats

Retrieve current subscription usage and quota information.

النطاقات المطلوبة: usage:read

الاستجابة

{
  "plan": "professional",
  "state": "active",
  "conversations_used": 847,
  "conversations_limit": 5000,
  "api_calls_used": 12340,
  "api_calls_limit": 100000,
  "renewal_date": "2025-07-15"
}

Webhooks

POST


                                                            /api/v1/wa/webhooks

النطاقات المطلوبة: webhooks:write

محتوى الطلب

{
  "url": "https://example.com/webhook",
  "events": ["message.received", "message.status"],
  "secret": "my_signing_secret"
}

الاستجابة

{
  "success": true,
  "webhook_id": 7
}

DELETE


                                                            /api/v1/wa/webhooks/{id}

Delete webhook

Remove a previously registered webhook.

النطاقات المطلوبة: webhooks:write

الاستجابة

{
  "success": true
}

أمثلة برمجية

أرسل رسالة نصية باللغة التي تفضّلها

curl -X POST https://www.procomrades.com/api/v1/wa/send/text \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+1234567890", "text": "Hello from our API!"}'

import requests

response = requests.post(
    "https://www.procomrades.com/api/v1/wa/send/text",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "phone": "+1234567890",
        "text": "Hello from our API!",
    },
)
print(response.json())

const response = await fetch("https://www.procomrades.com/api/v1/wa/send/text", {
    method: "POST",
    headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        phone: "+1234567890",
        text: "Hello from our API!",
    }),
});
const data = await response.json();
console.log(data);

$ch = curl_init("https://www.procomrades.com/api/v1/wa/send/text");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOUR_API_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "phone" => "+1234567890",
        "text" => "Hello from our API!",
    ]),
]);
$response = curl_exec($ch);
echo $response;

رموز الأخطاء

رمز الحالة	خطأ	الوصف
400	طلب غير صالح	محتوى الطلب غير صالح أو تنقصه حقول مطلوبة. تحقق من بيانات JSON وتأكد من توفير كل المعاملات المطلوبة.
401	غير مصرّح	مفتاح API مفقود أو غير صالح أو تم إلغاؤه. تحقق من أن ترويسة `Authorization` تحتوي على رمز Bearer صالح.
403	النطاق غير كافٍ	مفتاح API لديك لا يملك النطاق المطلوب لنقطة النهاية هذه. راجع النطاقات المطلوبة وحدّث صلاحيات مفتاحك.
404	غير موجود	المورد المطلوب غير موجود. تحقق من رابط نقطة النهاية ومعرّفات الموارد في المسار.
429	تم تجاوز حد المعدل / الحصة	لقد تجاوزت حد المعدل في الدقيقة أو حصتك الشهرية من استدعاءات API. انتظر قبل إعادة المحاولة أو ارفع باقتك لحدود أعلى.
500	خطأ داخلي في الخادم	حدث خطأ غير متوقع في الخادم. إن استمرت المشكلة، تواصل مع الدعم مع معرّف الطلب من ترويسات الاستجابة.

تحديد المعدل

لضمان الاستخدام العادل واستقرار المنصة، تخضع كل مفاتيح API لتحديد المعدل:

الافتراضي لكل مفتاح: 100 طلب في الدقيقة. الطلبات التي تتجاوز هذا الحد ستُدرج في قائمة انتظار أو تُرفض.
الحصة الشهرية من استدعاءات API: تتضمن كل باقة اشتراك حصة شهرية من استدعاءات API. عند استنفادها، تُرفض كل الاستدعاءات حتى دورة الفوترة التالية أو حتى ترفع باقتك.
استجابة HTTP 429: عند تجاوز حد المعدل في الدقيقة أو الحصة الشهرية، تُرجع الواجهة حالة 429 Too Many Requests. وتتضمن الاستجابة ترويسة Retry-After تبيّن عدد الثواني قبل إعادة المحاولة.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
    "error": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 30 seconds.",
    "retry_after": 30
}

Webhooks

استقبل إشعارات فورية عند وقوع أحداث على حساب واتساب لديك من خلال تسجيل نقاط نهاية Webhook.

التسجيل

سجّل رابط Webhook عبر واجهة API:

POST /api/v1/wa/webhooks

{
    "url": "https://your-server.com/webhook",
    "events": ["message.received", "message.status"],
    "secret": "your_webhook_secret"
}

الأحداث المدعومة

الحدث	الوصف
`message.received`	يُطلق عند استلام رسالة واردة جديدة من جهة اتصال
`message.status`	يُطلق عند تغيّر حالة الرسالة (أُرسلت، سُلّمت، قُرئت، فشلت)
`conversation.assigned`	يُطلق عند إسناد المحادثة إلى موظف أو فريق
`conversation.resolved`	يُطلق عند وضع علامة إغلاق على المحادثة

التحقق من توقيع HMAC-SHA256

يتضمن كل طلب Webhook ترويسة X-WA-Signature تحتوي على بصمة HMAC-SHA256 لمحتوى الطلب، موقّعة بسر Webhook الخاص بك. تحقق دائمًا من هذا التوقيع قبل معالجة البيانات.

import hmac
import hashlib

def verify_signature(payload_body, signature, secret):
    """Verify the X-WA-Signature header."""
    expected = hmac.new(
        secret.encode("utf-8"),
        payload_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

صيغة البيانات

{
    "event": "message.received",
    "timestamp": "2026-03-26T12:00:00Z",
    "data": {
        "message_id": "wamid.HBgN...",
        "from": "+1234567890",
        "type": "text",
        "text": "Hi, I need help with my order.",
        "conversation_id": 42
    }
}

جاهز للبناء؟

سجّل للحصول على تجربة مجانية واحصل على مفتاح API خلال دقائق.

ابدأ الآن