SocialHook
الوثائق/API الصادر

API الصادر

أرسل رسائل WhatsApp وFacebook وInstagram من خادمك الخاص عبر SocialHook. نقطة نهاية موقّعة واحدة تغطي المنصات الثلاث — كودك لا يتغير عند إضافة منصة جديدة.

متى تستخدم هذا

تريد مراسلة جهات الاتصال من CRM أو مكتب مساعدة أو لوحة تحكم مخصصة.
تشغّل أتمتة (n8n أو Make أو Zapier أو worker خاص بك) تحتاج إلى توزيع الردود.
تبني chatbot يعيش عقله على خوادمك.
للردود الفردية، فقط اكتب في صندوق بريد SocialHook — لا تحتاج API. يمكن لـ webhook الخاص بك أيضًا الرد بـ { "reply": "..." } لإرسال رسالة رد تلقائيًا دون استدعاء هذه النقطة إطلاقًا. انظر الرد التلقائي أدناه.

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

افتح مفتاح API في لوحة التحكم وانقر على إنشاء. سترى المفتاح الكامل مرة واحدة — انسخه الآن واحفظه في مكان آمن (مثل مدير الأسرار). إذا فقدته، أنشئ مفتاحًا جديدًا؛ القديم يتوقف عن العمل فورًا.

تبدأ المفاتيح بـ sk_live_ متبوعة بـ 64 حرفًا سداسيًا عشريًا. عامله ككلمة مرور: لا تُلزمه في git، لا تكشفه في كود المتصفح.

2. نقطة النهاية

HTTP
POST https://api.socialhook.io/api/v1/outbound/<your_user_id>/send
Content-Type: application/json

يظهر user_id الخاص بك في URL في صفحة مفتاح API. المسار محدد بالمستخدم عمدًا حتى يؤثر المفتاح المسرَّب على حساب واحد فقط.

3. المصادقة

اختر الطريقة التي تناسب إعدادك. كلتاهما تعمل مع نفس نقطة النهاية.

الطريقة أ — مفتاح بسيط (n8n وMake وZapier وأدوات no-code)

أضف رأسًا واحدًا. لا توقيع مطلوب.

HTTP
X-Api-Key: <your_api_key>
n8n / عقدة HTTP Request
# Method: POST
# URL:    https://api.socialhook.io/api/v1/outbound/<your_user_id>/send
# Header: X-Api-Key  →  sk_live_…
# Body (JSON):
{
  "platform": "whatsapp",
  "to": "447911123456",
  "message_text": "Hello from n8n!"
}

الطريقة ب — طلب موقّع (HMAC-SHA256، خوادم مخصصة)

ابنِ التوقيع بتجزئة HMAC-SHA256 لـ <timestamp>.<raw_body> بمفتاح API الخاص بك، ثم أرسل الهاضم السداسي بأحرف صغيرة في رأس X-Socialhook-Signature مسبوقًا بـ sha256=. الطلبات ذات الطوابع الزمنية التي تبعد أكثر من 5 دقائق عن وقت الخادم تُرفض.

HTTP
X-Socialhook-Timestamp: <unix_seconds>
X-Socialhook-Signature: sha256=<hmac_hex>
Node.js
const crypto = require('crypto');

const API_KEY = process.env.SOCIALHOOK_API_KEY;     // sk_live_…
const USER_ID = process.env.SOCIALHOOK_USER_ID;     // shown on the API key page

const body = JSON.stringify({
  platform: 'whatsapp',
  to: '447911123456',
  message_text: 'Hello from your SocialHook integration!',
});
const ts  = Math.floor(Date.now() / 1000).toString();
const sig = crypto
  .createHmac('sha256', API_KEY)
  .update(`${ts}.${body}`)
  .digest('hex');

const res = await fetch(
  `https://api.socialhook.io/api/v1/outbound/${USER_ID}/send`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Socialhook-Timestamp': ts,
      'X-Socialhook-Signature': `sha256=${sig}`,
    },
    body,
  }
);

if (!res.ok) throw new Error(await res.text());
cURL
# Drop your real API_KEY and USER_ID in here
TS=$(date +%s)
BODY='{"platform":"whatsapp","to":"447911123456","message_text":"Hello!"}'
SIG=$(printf "%s.%s" "$TS" "$BODY" | openssl dgst -sha256 -hmac "$API_KEY" | awk '{print $2}')

curl -X POST https://api.socialhook.io/api/v1/outbound/$USER_ID/send \
  -H "Content-Type: application/json" \
  -H "X-Socialhook-Timestamp: $TS" \
  -H "X-Socialhook-Signature: sha256=$SIG" \
  -d "$BODY"
مهم: وقّع بايتات الجسم الخام بالضبط التي ترسلها. إعادة تسلسل JSON بين التوقيع والإرسال يغيّر البايتات ويكسر التوقيع.

4. جسم الطلب لكل منصة

WhatsApp

JSON
{
  "platform": "whatsapp",
  "to": "447911123456",
  "message_text": "Hello from your integration!"
}

"to" هو رقم هاتف المستلم بتنسيق E.164 (بدون + في البداية).

Facebook

JSON
{
  "platform": "facebook",
  "to": "<recipient_psid>",
  "page_id": "<your_facebook_page_id>",
  "message_text": "Hi from SocialHook"
}

"to" هو معرف المستخدم المحدد بالصفحة (PSID). "page_id" مطلوب حتى نعرف من أي صفحة نرسل.

Instagram

JSON
{
  "platform": "instagram",
  "to": "<recipient_psid>",
  "page_id": "<your_facebook_page_id>",
  "message_text": "Hey from SocialHook"
}

"to" هو معرف المستخدم المحدد بـ IG. "page_id" هو معرف صفحة Facebook المرتبطة (Instagram يستخدم OAuth الخاص بـ FB).

5. رموز الاستجابة

الرمزالمعنىما يجب فعله
200تم الإرسالالرسالة مقبولة من المنصة؛ تظهر في خيط الدردشة.
400طلب خاطئحقل مفقود أو غير صالح. تحقق من platform/to/message_text/page_id.
401غير مصرحX-Api-Key مفقود/غير صالح، أو X-Socialhook-Signature غير متطابق. أعد حسابه بالجسم الخام بالضبط.
403انتهت نافذة الإرسالنافذة المراسلة لمدة 24 ساعة مغلقة (FB / IG / WA). انتظر رسالة واردة قبل الرد.
408الطابع الزمني قديمX-Socialhook-Timestamp يبعد أكثر من 5 دقائق عن وقت الخادم. أعد الإرسال بطابع زمني جديد.
429تم تجاوز الحدطلبات كثيرة جدًا. أبطئ وأعد المحاولة.

الرد التلقائي (تخطَّ نقطة النهاية)

إذا كانت حاجتك الوحيدة للصادر هي الرد على الرسائل الواردة، لا تحتاج استدعاء هذه النقطة إطلاقًا. عندما يُسلَّم SocialHook webhook إليك، يمكن لخادمك الرد بأحد:

JSON
// Single reply
{ "reply": "Thanks — got your message!" }

// Or multiple in order
{ "replies": ["Thanks!", "We'll get back to you within an hour."] }

يرسل SocialHook كل رد على المنصة الصحيحة تلقائيًا ويسجله في خيط الدردشة. فشل الرد لا يحجب إقرار التسليم — webhook الخاص بك لا يزال مُعلَّمًا DELIVERED.

الحماية من إعادة التشغيل (الطلبات الموقّعة)

الطوابع الزمنية الأقدم من 5 دقائق تُرفض (متسامح مع انجراف الساعة).
التوقيعات تُقارن في وقت ثابت.
المسار محدد بالمستخدم، لذا المفتاح المسرَّب يؤثر على حساب واحد فقط.
إلغاء المفتاح (أو إنشاء مفتاح جديد) يحجب أي طلبات أخرى بالمفتاح القديم فورًا.

ما التالي

أنشئ مفتاح API الخاص بك إذا لم تفعل بعد.
اقرأ مرجع الـ payload لفهم ما يستقبله webhook الخاص بك — مفيد عند توصيل الرد التلقائي.
راجع التحقق من التوقيع لتسليمات webhook الواردة (نظام توقيع مختلف — نفس الفكرة).