API الصادر
أرسل رسائل WhatsApp وFacebook وInstagram من خادمك الخاص عبر SocialHook. نقطة نهاية موقّعة واحدة تغطي المنصات الثلاث — كودك لا يتغير عند إضافة منصة جديدة.
متى تستخدم هذا
{ "reply": "..." } لإرسال رسالة رد تلقائيًا دون استدعاء هذه النقطة إطلاقًا. انظر الرد التلقائي أدناه.1. احصل على مفتاح API
افتح مفتاح API في لوحة التحكم وانقر على إنشاء. سترى المفتاح الكامل مرة واحدة — انسخه الآن واحفظه في مكان آمن (مثل مدير الأسرار). إذا فقدته، أنشئ مفتاحًا جديدًا؛ القديم يتوقف عن العمل فورًا.
تبدأ المفاتيح بـ sk_live_ متبوعة بـ 64 حرفًا سداسيًا عشريًا. عامله ككلمة مرور: لا تُلزمه في git، لا تكشفه في كود المتصفح.
2. نقطة النهاية
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)
أضف رأسًا واحدًا. لا توقيع مطلوب.
X-Api-Key: <your_api_key>
# 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 دقائق عن وقت الخادم تُرفض.
X-Socialhook-Timestamp: <unix_seconds> X-Socialhook-Signature: sha256=<hmac_hex>
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());# 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"4. جسم الطلب لكل منصة
{
"platform": "whatsapp",
"to": "447911123456",
"message_text": "Hello from your integration!"
}"to" هو رقم هاتف المستلم بتنسيق E.164 (بدون + في البداية).
{
"platform": "facebook",
"to": "<recipient_psid>",
"page_id": "<your_facebook_page_id>",
"message_text": "Hi from SocialHook"
}"to" هو معرف المستخدم المحدد بالصفحة (PSID). "page_id" مطلوب حتى نعرف من أي صفحة نرسل.
{
"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 إليك، يمكن لخادمك الرد بأحد:
// 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.