وثائق مدعوم للمطوّرين

نظرة عامة على المنصّة #

منصّة مدعوم للمطوّرين مبنية على ثلاث واجهات مستقلة في المصادقة، متكاملة في الوظيفة. اختر الواجهة حسب ما تريد عمله — لا تحتاج الثلاثة معًا.

أيّ واجهة تختار؟

العناوين الأساسية #

الدومين الرسمي للمنصّة هو mad3oom.com. كل مسارات MCP وOAuth تُخدَم منه مباشرة بلا أي إعادة توجيه.

جدول العناوين الكامل

واجهة WhatsApp تُخدَم من نطاق Supabase مباشرةً — ليست ضمن إعادة الكتابة على mad3oom.com. التفاصيل في قسم WhatsApp.

المصادقة والمفاتيح #

كل طلب على /mcp لازم يحمل ترويسة Authorization. مفيش استثناء — الطلب بلا ترويسة بيرجع 401.

Authorization: Bearer <credential>
Content-Type: application/json

نوعا الاعتماد

لوحة المطوّرين بتولّد نوعين من الاعتماد — الخادم بيقبل الاتنين على نفس الترويسة، ويفرّق بينهم بوجود نقطة . في القيمة.

إنشاء مفتاح

الصلاحيات (Scopes) #

كل أداة مربوطة بصلاحية واحدة. tools/list بيرجّع الأدوات اللي مفتاحك يملك صلاحيتها فقط — فلو أداة مش ظاهرة عندك، غالبًا الـ scope ناقص.

الصلاحيات المستخدَمة فعليًا في الأدوات

باقي الصلاحيات المتاحة عند الإصدار

الصلاحيات دي مقبولة عند توليد المفتاح وفي OAuth، لكن مفيش أداة MCP بتستهلكها حاليًا — بتستخدمها واجهات داخلية تانية:

tickets:delete · knowledge_base:read · knowledge_base:write · customers:read · customers:write · whatsapp:read · analytics:read · settings:manage · oauth:manage · mcp:connect · chatbot:read · admin:full

الصلاحيات الافتراضية لو مبعتّش scopes عند الإنشاء: tickets:read، tickets:write، whatsapp:send، whatsapp:read، chatbot:read.

أول طلب #

أسرع طريقة تتأكد إن المفتاح شغّال: اطلب قائمة الأدوات. مش محتاج initialize قبلها — الخادم عديم الحالة (stateless).

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer YOUR_API_KEY.YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

const res = await fetch("https://mad3oom.com/mcp", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY.YOUR_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list" }),
});
const data = await res.json();
console.log(data.result.tools.map(t => t.name));

import requests

resp = requests.post(
    "https://mad3oom.com/mcp",
    headers={"Authorization": "Bearer YOUR_API_KEY.YOUR_SECRET"},
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/list"},
)
print([t["name"] for t in resp.json()["result"]["tools"]])

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      { "name": "create_ticket", "description": "…", "inputSchema": { … } },
      { "name": "list_tickets",  "description": "…", "inputSchema": { … } }
    ]
  }
}

لو رجع 401 راجع شكل الترويسة. ولو رجعت قائمة أقصر من المتوقّع، فالمفتاح ناقصه scopes.

بروتوكول JSON-RPC #

كل شيء بيمرّ من POST /mcp بجسم JSON-RPC 2.0 واحد. الـmethod بتحدّد العملية.

initialize

اختياري للاستخدام المباشر، لكنه إلزامي لو بتبني عميل MCP كامل. بيرجّع نسخة البروتوكول المتفق عليها وترويسة Mcp-Session-Id.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": {} },
    "serverInfo": {
      "name": "mad3oom-mcp",
      "version": "1.1.0"
    }
  }
}

النسخ المدعومة: 2025-06-18 (الافتراضية)، 2025-03-26، 2024-11-05، 2025-11-25. لو بعتّ نسخة غير معروفة، الخادم بيرجع للافتراضية بدل ما يرفض الطلب. الخادم يعلن قدرة tools فقط — لا resources ولا prompts.

tools/list

بيرجّع مصفوفة الأدوات بعد فلترتين: أدوات مفتاحك يملك صلاحيتها، وغير مُعطَّلة من إدارة المنصّة. كل عنصر فيه name وdescription وinputSchema (JSON Schema).

tools/call

بياخد params.name (اسم الأداة) وparams.arguments (كائن المعاملات).

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<tool_name>",
    "arguments": { … }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[\n  {\n    \"id\": \"…\"\n  }\n]"
      }
    ]
  }
}

const { result, error } = await res.json();
if (error) throw new Error(error.message);

// نتيجة الأداة نص JSON — لازم parse
const data = JSON.parse(result.content[0].text);

في كل أمثلة مرجع الأدوات تحت، «الرد» معروض بعد هذا الـ parsing مباشرةً.

مرجع الأدوات #

18 أداة، كلها تُستدعى بنفس الطريقة: POST /mcp بـmethod: "tools/call". الجدول تحت فهرس سريع، وتحته بطاقة تفصيلية لكل أداة.

التذاكر #

إدارة تذاكر الدعم — قراءة وإنشاء وتعديل وإغلاق.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_tickets",
    "arguments": {
      "status": "open",
      "limit": 5
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_tickets","arguments":{"status":"open","limit":5}}}'

[
  {
    "id": "3f0a…",
    "ticket_number": 128,
    "title": "مشكلة تسجيل دخول",
    "description": "…",
    "status": "open",
    "priority": "high",
    "ticket_type": "problem",
    "category": null,
    "user_id": "9c1e…",
    "created_at": "2026-09-18T10:00:00+00:00"
  }
]

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_ticket",
    "arguments": {
      "ticket_id": "TICKET_ID"
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_ticket","arguments":{"ticket_id":"TICKET_ID"}}}'

{
  "id": "TICKET_ID",
  "ticket_number": 128,
  "title": "مشكلة تسجيل دخول",
  "status": "open",
  "priority": "high",
  "created_at": "2026-09-18T10:00:00+00:00"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_ticket",
    "arguments": {
      "title": "عندي مشكلة في الدخول",
      "description": "الصفحة بترجعني لتسجيل الدخول كل مرة",
      "priority": "medium"
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_ticket","arguments":{"title":"عندي مشكلة في الدخول","description":"الصفحة بترجعني لتسجيل الدخول كل مرة","priority":"medium"}}}'

{
  "id": "e5f6…",
  "ticket_number": 129,
  "user_id": "9c1e…",
  "title": "عندي مشكلة في الدخول",
  "description": "الصفحة بترجعني لتسجيل الدخول كل مرة",
  "status": "open",
  "priority": "medium",
  "ticket_type": "problem",
  "created_at": "2026-09-19T08:12:00+00:00"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_ticket",
    "arguments": {
      "ticket_id": "TICKET_ID",
      "updates": {
        "priority": "high"
      }
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"update_ticket","arguments":{"ticket_id":"TICKET_ID","updates":{"priority":"high"}}}}'

{
  "id": "TICKET_ID",
  "priority": "high",
  "status": "open",
  "last_updated_at": "2026-09-19T08:20:00+00:00"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "close_ticket",
    "arguments": {
      "ticket_id": "TICKET_ID"
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"close_ticket","arguments":{"ticket_id":"TICKET_ID"}}}'

{
  "id": "TICKET_ID",
  "status": "closed"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_dashboard_stats",
    "arguments": {}
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_dashboard_stats","arguments":{}}}'

{
  "total": 37,
  "resolved": 27,
  "confirmed": 8,
  "rejected": 2
}

العملاء #

قراءة بيانات العملاء ضمن نطاق رؤية المفتاح.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_customers",
    "arguments": {
      "limit": 20
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_customers","arguments":{"limit":20}}}'

[
  {
    "id": "9c1e…",
    "email": "ahmed@example.com",
    "full_name": "أحمد محمد",
    "phone": "+201001234567",
    "role": "user",
    "user_type": "individual",
    "city": "القاهرة",
    "country": "EG",
    "created_at": "2026-05-02T09:00:00+00:00",
    "is_verified": true,
    "super_user_id": null
  }
]

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_customer",
    "arguments": {
      "customer_id": "CUSTOMER_ID"
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_customer","arguments":{"customer_id":"CUSTOMER_ID"}}}'

{
  "id": "CUSTOMER_ID",
  "email": "ahmed@example.com",
  "full_name": "أحمد محمد",
  "phone": "+201001234567",
  "role": "user",
  "user_type": "individual",
  "city": "القاهرة",
  "country": "EG",
  "created_at": "2026-05-02T09:00:00+00:00",
  "is_verified": true,
  "super_user_id": null
}

واتساب #

إرسال رسائل واتساب من رقم مربوط بحسابك.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "send_whatsapp",
    "arguments": {
      "to": "201001234567",
      "message_type": "text",
      "text": "أهلاً بيك في مدعوم!"
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"send_whatsapp","arguments":{"to":"201001234567","message_type":"text","text":"أهلاً بيك في مدعوم!"}}}'

{
  "ok": true,
  "status": 200,
  "data": {
    "messaging_product": "whatsapp",
    "contacts": [
      {
        "input": "201001234567",
        "wa_id": "201001234567"
      }
    ],
    "messages": [
      {
        "id": "wamid.HBgM…"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "send_whatsapp",
    "arguments": {
      "to": "201001234567",
      "message_type": "template",
      "template": {
        "name": "TEMPLATE_NAME",
        "language": "ar",
        "components": []
      }
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"send_whatsapp","arguments":{"to":"201001234567","message_type":"template","template":{"name":"TEMPLATE_NAME","language":"ar","components":[]}}}}'

{
  "ok": true,
  "status": 200,
  "data": {
    "messaging_product": "whatsapp",
    "messages": [
      {
        "id": "wamid.HBgM…"
      }
    ]
  }
}

الاشتراكات #

طلب وتجديد وإلغاء الاشتراكات وعرض الخطط.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_subscriptions",
    "arguments": {
      "status": "active",
      "limit": 20
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_subscriptions","arguments":{"status":"active","limit":20}}}'

[
  {
    "id": "7ab2…",
    "user_id": "9c1e…",
    "ticket_id": "3f0a…",
    "plan": "bundle",
    "billing_cycle": "monthly",
    "status": "active",
    "start_date": "2026-09-01T00:00:00+00:00",
    "end_date": "2026-10-01T00:00:00+00:00",
    "is_renewal": false,
    "duration_days": 30
  }
]

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_subscription",
    "arguments": {
      "subscription_id": "SUBSCRIPTION_ID"
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_subscription","arguments":{"subscription_id":"SUBSCRIPTION_ID"}}}'

{
  "id": "SUBSCRIPTION_ID",
  "plan": "bundle",
  "billing_cycle": "monthly",
  "status": "active",
  "start_date": "2026-09-01T00:00:00+00:00",
  "end_date": "2026-10-01T00:00:00+00:00"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_subscription_plans",
    "arguments": {}
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_subscription_plans","arguments":{}}}'

[
  {
    "id": "c31f…",
    "key": "bundle",
    "name": "Bundle",
    "name_ar": "دعم فني + واتساب",
    "price_monthly": "1500.00",
    "price_yearly": "15000.00",
    "currency": "EGP",
    "is_active": true,
    "sort_order": 3,
    "features": [
      {
        "plan_id": "c31f…",
        "...": "…"
      }
    ]
  }
]

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_subscription",
    "arguments": {
      "plan": "support",
      "billing_cycle": "monthly"
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_subscription","arguments":{"plan":"support","billing_cycle":"monthly"}}}'

{
  "ticket": {
    "id": "3f0a…",
    "title": "طلب اشتراك - الدعم الفني (شهري)",
    "status": "open",
    "priority": "high"
  },
  "subscription": {
    "id": "7ab2…",
    "plan": "support",
    "billing_cycle": "monthly",
    "status": "pending",
    "is_renewal": false,
    "duration_days": 30
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "renew_subscription",
    "arguments": {
      "plan": "support",
      "billing_cycle": "monthly"
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"renew_subscription","arguments":{"plan":"support","billing_cycle":"monthly"}}}'

{
  "ticket": {
    "id": "3f0b…",
    "title": "طلب تجديد اشتراك - الدعم الفني (شهري)",
    "status": "open"
  },
  "subscription": {
    "id": "7ab3…",
    "plan": "support",
    "status": "pending",
    "is_renewal": true,
    "previous_end_date": "2026-10-01T00:00:00+00:00"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "cancel_subscription",
    "arguments": {
      "subscription_id": "SUBSCRIPTION_ID"
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"cancel_subscription","arguments":{"subscription_id":"SUBSCRIPTION_ID"}}}'

{
  "id": "SUBSCRIPTION_ID",
  "status": "rejected",
  "rejection_reason": "تم الإلغاء بواسطة العميل",
  "reviewed_at": "2026-09-19T09:00:00+00:00"
}

الإشعارات #

قراءة وإرسال وإدارة إشعارات المنصّة.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_notifications",
    "arguments": {
      "status": "unread",
      "limit": 20
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_notifications","arguments":{"status":"unread","limit":20}}}'

[
  {
    "id": "a1b2…",
    "user_id": "9c1e…",
    "title": "تم تحديث تذكرتك",
    "message": "فريق الدعم ردّ على التذكرة رقم 128",
    "type": "info",
    "is_read": false,
    "link": "/tickets.html",
    "created_at": "2026-09-19T07:40:00+00:00"
  }
]

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "send_notification",
    "arguments": {
      "user_id": "USER_ID",
      "title": "عنوان الإشعار",
      "message": "نص الإشعار",
      "type": "info"
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"send_notification","arguments":{"user_id":"USER_ID","title":"عنوان الإشعار","message":"نص الإشعار","type":"info"}}}'

{
  "id": "b2c3…",
  "user_id": "USER_ID",
  "title": "عنوان الإشعار",
  "message": "نص الإشعار",
  "type": "info",
  "is_read": false,
  "created_at": "2026-09-19T09:10:00+00:00"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "manage_notification",
    "arguments": {
      "notification_id": "NOTIFICATION_ID",
      "action": "mark_read"
    }
  }
}

curl -X POST https://mad3oom.com/mcp \
  -H "Authorization: Bearer $MAD3OOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"manage_notification","arguments":{"notification_id":"NOTIFICATION_ID","action":"mark_read"}}}'

{
  "id": "NOTIFICATION_ID",
  "is_read": true,
  "title": "تم تحديث تذكرتك",
  "type": "info"
}

الأخطاء #

الأخطاء بترجع بشكل JSON-RPC قياسي. انتبه: جزء من الأخطاء بيرجع بحالة HTTP 200 — فلا تعتمد على res.ok وحده، افحص وجود error في الجسم.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32003,
    "message": "Missing required scope: tickets:write"
  }
}

جدول الأكواد الكامل

معالجة صحيحة للأخطاء

async function callTool(name, args = {}) {
  const res = await fetch("https://mad3oom.com/mcp", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      jsonrpc: "2.0", id: Date.now(),
      method: "tools/call", params: { name, arguments: args },
    }),
  });

  // 429 قابل لإعادة المحاولة — بقية الأخطاء لا
  if (res.status === 429) throw new Error("RATE_LIMITED");

  const data = await res.json();

  // أخطاء كتير بترجع HTTP 200 — الفحص على الجسم لا على res.ok
  if (data.error) {
    throw new Error(`[${data.error.code}] ${data.error.message}`);
  }

  return JSON.parse(data.result.content[0].text);
}

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

حد /mcp بيتحسب من عدّاد طلبات آخر 60 ثانية لنفس المفتاح. التجاوز يرجع 429 مع -32001.

الترقيم (Pagination)

كل الأدوات اللي بترجع قوائم بتاخد limit وoffset. الافتراضي limit=20 وoffset=0، والحد الأقصى limit=100 — أي رقم أكبر بيتقصّ بصمت لـ 100، فلا تفترض إنك هتستقبل 500 صف.

إعادة المحاولة والتكرار

أعد المحاولة على 429 و5xx فقط، بتراجع أُسّي (2s، 4s، 8s، 16s) وبحد أقصى 5 محاولات. أخطاء 4xx الأخرى تحتاج إصلاح الطلب نفسه — إعادة المحاولة لن تغيّر النتيجة.

OAuth 2.1 #

لو بتبني Connector لعميل MCP خارجي، استخدم OAuth بدل مفتاح ثابت — المستخدم بيوافق بنفسه، والتوكن بيتجدّد تلقائيًا.

نقاط الاكتشاف

{
  "issuer": "https://mad3oom.com",
  "authorization_endpoint": "https://mad3oom.com/oauth/authorize",
  "token_endpoint": "https://mad3oom.com/oauth/token",
  "registration_endpoint": "https://mad3oom.com/oauth/register",
  "scopes_supported": ["tickets:read", "tickets:write", "…"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_post", "client_secret_basic"]
}

{
  "resource": "https://mad3oom.com/mcp",
  "authorization_servers": ["https://mad3oom.com"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://mad3oom.com"
}

التدفّق

الربط بـ Claude وعملاء MCP #

نفس الـ endpoint اللي بتستخدمه من كودك هو اللي بتحطّه في أي عميل MCP يدعم Streamable HTTP. مفيش إعداد إضافي.

طريقتان للربط

ملاحظات لبناة العملاء

• النقل: Streamable HTTP — طلب POST واحد لكل رسالة. لا SSE ولا WebSocket.
• الخادم بيرجع Mcp-Session-Id على initialize، لكنه عديم الحالة: مش شرط ترجّعه في الطلبات التالية.
• القدرات المُعلَنة: tools فقط. مفيش resources ولا prompts ولا sampling.
• ترويسات CORS مفتوحة (*) وبتقبل mcp-session-id وmcp-protocol-version.
• notifications/initialized بيرجع 202 بلا جسم — لا تحاول تعمل .json() عليه.

مدعوم كعميل MCP

في الاتجاه المعاكس، لوحة الإدارة في مدعوم تقدر تتصل بخوادم MCP خارجية (Supabase، GitHub…) نيابةً عن الأدمن. دي ميزة داخلية للوحة — مش جزء من الواجهة اللي بتستهلكها كمطوّر خارجي، وتُدار من تبويب MCP → العميل.

نظرة عامة #

تطبيقك الخارجي يعرف ثلاثة أشياء فقط: اسم القالب المنطقي، رقم المستقبِل، المتغيّرات. كل ما عداه — التوكنات، رقم الإرسال، اسم القالب لدى ميتا، الرصيد — مسؤولية مدعوم.

تطبيقك  →  Integration API  →  حلّ القالب  →  طبقة الرسائل  →  WhatsApp Cloud API

الفرق بينها وبين أداة send_whatsapp

العنوان الأساسي

كل المسارات تحت /v1/…، فالمسار الكامل للإرسال مثلًا:

الدالة تقبل كذلك بادئة /api (/api/v1/messages/template) لو اتحطّ نطاق مخصّص أمامها لاحقًا — فكود المتصل ما يتغيّرش عند نقل النطاق.

ربط رقم واتساب #

قبل أي إرسال، لازم يكون فيه رقم واتساب مربوط بحساب مدعوم. الربط بيتم من لوحة واتساب بتدفّق Meta Embedded Signup — مش عبر الـ API العام.

مفاتيح التكامل #

ترويسة واحدة على كل المسارات عدا /v1/health:

X-API-Key: mad3_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

ويُقبل كذلك Authorization: Bearer <key> لمن يفضّله. شكل المفتاح: mad3_live_ أو mad3_test_ متبوعًا بـ 20–120 حرفًا من A-Z a-z 0-9 _ -.

GET /v1/health #

فحص حياة الخدمة. بلا مصادقة، ولا يكشف أي شيء عن حسابك.

curl https://srnelrdpqkcntbgudyto.supabase.co\
/functions/v1/integrations-api/v1/health

{
  "status": "ok",
  "service": "integrations-api",
  "version": "v1"
}

كل رد من الواجهة بيحمل ترويسة x-request-id — اذكرها عند الإبلاغ عن أي مشكلة. تقدر تبعت واحدة من عندك وهتترجّعلك.

GET /v1/templates #

بيرجّع القوالب المتاحة لتكاملك بعقودها. استخدمه كمصدر الحقيقة لأسماء المتغيّرات قبل أول إرسال — القوالب بتتغيّر من جهة مدعوم بلا تغيير في كودك.

Authentication

X-API-Key: mad3_live_…

curl -H "X-API-Key: $MAD3OOM_API_KEY" \
  "https://srnelrdpqkcntbgudyto.supabase.co/functions/v1/integrations-api/v1/templates"

{
  "success": true,
  "environment": "live",
  "templates": [
    {
      "template": "time_getting",
      "channel": "whatsapp",
      "language": "ar",
      "category": "utility",
      "required_variables": [
        "tenant_name",
        "collection_phone"
      ],
      "optional_variables": [],
      "status": "active"
    }
  ]
}

حالات القالب

لا يظهر في الرد أي اسم قالب لدى المزوّد ولا معرّف رقم — العقد فقط.

POST /v1/messages/template #

طلب إرسال رسالة واتساب بقالب معتمد.

Authentication

X-API-Key: mad3_live_…
Content-Type: application/json

Request body

{
  "template": "time_getting",
  "recipient": "+201001234567",
  "variables": {
    "tenant_name": "أحمد محمد",
    "collection_phone": "01000000000"
  },
  "idempotency_key": "visit_827_tenant_55_2026-09-19",
  "metadata": {
    "source": "aqar",
    "event": "visit_scheduled"
  }
}

curl -X POST \
  "https://srnelrdpqkcntbgudyto.supabase.co/functions/v1/integrations-api/v1/messages/template" \
  -H "X-API-Key: $MAD3OOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "time_getting",
    "recipient": "+201001234567",
    "variables": {
      "tenant_name": "أحمد محمد",
      "collection_phone": "01000000000"
    },
    "idempotency_key": "visit_827_tenant_55_2026-09-19"
  }'

const BASE = "https://srnelrdpqkcntbgudyto.supabase.co"
  + "/functions/v1/integrations-api";

const res = await fetch(`${BASE}/v1/messages/template`, {
  method: "POST",
  headers: {
    "X-API-Key": process.env.MAD3OOM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    template: "time_getting",
    recipient: "+201001234567",
    variables: {
      tenant_name: "أحمد محمد",
      collection_phone: "01000000000",
    },
    // نفس الحدث ⇒ نفس المفتاح، دائمًا
    idempotency_key: `visit_${visitId}_tenant_${tenantId}_${dueDate}`,
  }),
});

const body = await res.json();
if (!body.success) {
  // تفرّع على error.code وحده — لا على النص
  if (body.error.retryable) scheduleRetry();
  else throw new Error(body.error.code);
}

{
  "success": true,
  "message_id": "msg_9f2c1ab34d5e6f708192a3b4",
  "status": "queued",
  "template": "time_getting",
  "recipient": "+2010*****567",
  "environment": "live",
  "sandbox": false,
  "idempotency_key": "visit_827_tenant_55_2026-09-19",
  "idempotent_replay": false
}

{
  "success": false,
  "error": {
    "code": "MISSING_TEMPLATE_VARIABLE",
    "message": "One or more required template variables are missing.",
    "retryable": false,
    "details": {
      "template": "time_getting",
      "missing_variables": ["collection_phone"],
      "required_variables": [
        "tenant_name", "collection_phone"
      ]
    }
  }
}

حقول رد النجاح

منع التكرار (Idempotency) #

idempotency_key إلزامي. اجعله معبّرًا عن الحدث نفسه لا عن لحظة الإرسال.

rent_due_property_827_tenant_55_2026-09-01   ✅ نفس الحدث ⇒ نفس المفتاح
send_1724180000123                           ❌ يتغيّر كل محاولة — بلا فائدة

سياسة إعادة المحاولة

• أعد المحاولة فقط عند retryable: true — وهي 429، 5xx، 402، وREQUEST_IN_PROGRESS.
• استخدم نفس idempotency_key — هذا بالضبط ما يمنع الازدواج.
• تراجع أُسّي: 2s، 4s، 8s، 16s — بحد أقصى 5 محاولات.
• على 429 احترم ترويسة Retry-After بالثواني.
• رموز جديدة قد تُضاف لاحقًا — عامل الرمز غير المعروف كخطأ غير قابل لإعادة المحاولة ما لم يقل retryable: true.

رموز أخطاء WhatsApp #

تفرّع على error.code وحده. النص (message) للبشر وقد يتغيّر أو يُترجَم؛ الرمز لا يتغيّر معناه أبدًا بعد نشره. وكل رمز مقترن بحالة HTTP واحدة فقط.

الصندوق الرملي #

مفتاح mad3_test_… بيشغّل المسار كاملًا — مصادقة، حدّ معدل، تحقّق من القالب والمتغيّرات والرقم، منع تكرار، استجابة — بلا نداء واتساب، بلا رسالة حقيقية، بلا خصم رصيد.

• environment: "test" وsandbox: true في الرد.
• message_id بيبدأ بـmsg_test_.
• القوالب في حالة draft بتشتغل في الصندوق الرملي فقط — فتقدر تبني على عقد قالب قبل اعتماده في واتساب.
• الانتقال للإنتاج بتبديل المفتاح فقط — لا تغيير في الكود ولا في المسار.

التكلفة والرصيد

Webhooks #

الرسائل الواردة وحالات التسليم بتوصل من ميتا على webhook مدعوم، وبتتخزّن في حسابك وتشغّل الأتمتة. ميتا هي اللي بتنادي المسار ده، مش تطبيقك.

١. مصافحة التحقّق — GET

ميتا بتنادي المسار بـGET ومعاه ثلاثة باراميترات. لو hub.mode=subscribe وhub.verify_token طابق التوكن المضبوط، بيرجع hub.challenge نصًّا خامًا بحالة 200. غير كده 403 Forbidden.

GET /functions/v1/whatsapp-webhook
      ?hub.mode=subscribe
      &hub.verify_token=<WEBHOOK_VERIFY_TOKEN>
      &hub.challenge=1158201444

200 OK
1158201444

٢. استقبال الأحداث — POST

الحمولة بشكل Meta Cloud API القياسي. الخادم بيمرّ على كل entry وكل changes داخلها — لا يكتفي بالأول — وبيعالج كل value بمعزل عن الباقي، فخطأ في واحدة لا يُسقط البقية.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": { "phone_number_id": "…" },
            "messages": [ … ],
            "statuses": [ … ]
          }
        }
      ]
    }
  ]
}

٣. الحقول المطلوب الاشتراك فيها

عند ربط الرقم بيتم الاشتراك على مستوى الـ WABA، وبيتقرا الاشتراك الفعلي للتأكد. الحقول المطلوبة:

نقص أي حقل من دول بيظهر كتحذير وقت الربط بدل ما يتحوّل لمشكلة «الرسائل مش بتوصل» بعد أيام.

واجهات واتساب في اللوحة #

الدوال دي جزء من منظومة واتساب لكنها ليست واجهة عامة للمطوّرين. موثّقة هنا عشان تعرف الحدود بالضبط.

POST /functions/v1/send-whatsapp

نسخة REST من أداة send_whatsapp، بنفس مصادقة مفاتيح API وبنفس صلاحية whatsapp:send.

الردود المتحقَّق منها: بلا ترويسة ⇒ 401 {"error":"Missing Authorization header"}، وGET ⇒ 405 {"error":"Only POST is supported"}. عند النجاح بيرجع نفس كائن { ok, status, data }، وعند فشل المزوّد بيرجع حالة المزوّد نفسها أو 502.

POST /functions/v1/whatsapp-graph-request

وسيط محروس لعمليات Graph من اللوحة — بمصادقة جلسة مستخدم، مش بمفتاح API. جسم الطلب { "operation": "…", "payload": { … } }، أو multipart/form-data لرفع الوسائط.

العمليات المسموحة حصرًا (أي غيرها ⇒ 400 unsupported_operation):

sendText · sendMedia · uploadMedia · sendTemplate · getTemplates · createTemplate · deleteTemplate · getBillingStatus · updateBusinessProfile · verifyContacts

POST /functions/v1/register-whatsapp وwhatsapp-phone-status

بمصادقة جلسة مستخدم كذلك. بلا ترويسة بيرجعوا 401 بالشكل {"code":"UNAUTHORIZED_NO_AUTH_HEADER","message":"Missing authorization header"}.

ما لا تفعله واجهة WhatsApp

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

غلاف جاهز (SDK) #

كلاس بسيط بيلفّ الـ JSON-RPC، يعمل الـ parsing، ويطلّع أخطاء واضحة — أسهل من إعادة كتابة نفس الكود كل مرة.

class Mad3oomClient {
  constructor(token, baseUrl = "https://mad3oom.com/mcp") {
    this.token = token;
    this.baseUrl = baseUrl;
  }

  async call(method, params) {
    const res = await fetch(this.baseUrl, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${this.token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        jsonrpc: "2.0", id: Date.now(), method, params,
      }),
    });

    if (res.status === 429) {
      throw Object.assign(new Error("Rate limited"), { retryable: true });
    }

    const data = await res.json();
    if (data.error) {
      throw new Error(`[${data.error.code}] ${data.error.message}`);
    }
    return data.result;
  }

  async tool(name, args = {}) {
    const result = await this.call("tools/call", { name, arguments: args });
    // نتيجة الأداة نص JSON داخل content[0].text
    return JSON.parse(result.content[0].text);
  }

  listTools() {
    return this.call("tools/list").then(r => r.tools);
  }
}

// الاستخدام
const client = new Mad3oomClient(process.env.MAD3OOM_TOKEN);
const tickets = await client.tool("list_tickets", { status: "open", limit: 10 });
const stats   = await client.tool("get_dashboard_stats");

import json, os, requests


class Mad3oomClient:
    def __init__(self, token, base_url="https://mad3oom.com/mcp"):
        self.token = token
        self.base_url = base_url

    def call(self, method, params=None):
        resp = requests.post(
            self.base_url,
            headers={
                "Authorization": f"Bearer {self.token}",
                "Content-Type": "application/json",
            },
            json={"jsonrpc": "2.0", "id": 1,
                  "method": method, "params": params},
            timeout=30,
        )
        if resp.status_code == 429:
            raise RuntimeError("Rate limited (60 req/min)")

        data = resp.json()
        if "error" in data:
            err = data["error"]
            raise RuntimeError(f"[{err['code']}] {err['message']}")
        return data["result"]

    def tool(self, name, args=None):
        result = self.call("tools/call",
                           {"name": name, "arguments": args or {}})
        # نتيجة الأداة نص JSON داخل content[0]["text"]
        return json.loads(result["content"][0]["text"])

    def list_tools(self):
        return self.call("tools/list")["tools"]


# الاستخدام
client = Mad3oomClient(os.environ["MAD3OOM_TOKEN"])
tickets = client.tool("list_tickets", {"status": "open", "limit": 10})
stats = client.tool("get_dashboard_stats")

Postman Collection #

كل الـ 18 أداة كـ requests جاهزة، مقسّمة بمجلدات حسب المجال، بالإضافة لـinitialize وtools/list. بعد التحميل، اضبط متغيّر البيئة token بمفتاحك.

تحميل Postman Collection

اصطلاحات عامة #

آخر التحديثات #

توحيد الدومين على mad3oom.com

• كل نقاط OAoth والاكتشاف و/mcp بقت تُخدَم من mad3oom.com بلا أي إعادة توجيه.
• issuer وauthorization_servers وresource كلها بقت تُعلن الدومين الرسمي — ده اللي بيخلّي عملاء MCP الصارمين يقبلوا البيانات الوصفية (RFC 9728 §3.3).
• الدومين القديم mad3oom.online انتهى. لو عندك Connector قديم، حدّث عنوانه.

تتبّع الاستخدام

• سجل الاستخدام بقى يسجّل اسم الأداة المستخدمة فعليًا (/mcp:tools/call:list_tickets) بدل قيمة ثابتة.
• status_code بقى يتسجّل بالقيمة الحقيقية للرد.
• عدّاد الاستخدام على كل مفتاح بقى يتحدّث فعليًا.

واتساب

• مسار الإرسال عبر أداة MCP بقى يمرّ بفحص المحفظة والخصم زي باقي المسارات.
• القالب time_getting بقى active ومربوطًا، ومتغيّراته المطلوبة tenant_name وcollection_phone.