معظم ما يُطلب من واجهة API لواتساب يرجع إلى أربعة أمور: إرسال رسالة، والبحث عن شيء، وتعديل سجل، وتلقي إشعار حين يحدث أمر ما. يتيح Spun الأربعة كلها عبر HTTP عادي على الرقم نفسه الذي يرد منه فريقك في صندوق الوارد، مع مصادقة بمفتاح تنشئه بنفسك وتحدد صلاحياته بما يحتاجه التكامل بالضبط.
هذه الصفحة هي النسخة العملية: ما نقاط النهاية، وكيف تعمل المصادقة والصلاحيات، وماذا يحدث حين يكون خط واتساب لديك غير متصل لحظة الاستدعاء، وأين يوجد العقد المقروء آليًا.
المفاتيح والصلاحيات، وحجم الضرر إذا تسرّب مفتاح
المصادقة برمز Bearer. تنشئ مفتاحًا في التطبيق، فيُعرض عليك مرة واحدة، ويحمله كل طلب في ترويسة Authorization. لا يخزّن Spun سوى قيمة مجزّأة (hash) للمفتاح، لذا لا يمكن استعادة مفتاح مفقود، بل استبداله فقط.
الجزء الذي يستحق دقيقة من وقتك هو الصلاحيات. المفتاح ليس مجرد «وصول إلى الحساب»: بل يحمل قائمة صلاحيات، وكل نقطة نهاية تتحقق من الصلاحية المحددة التي تحتاجها. المفتاح الذي لا يحمل إلا read_contacts لا يستطيع إرسال رسالة. والمفتاح الذي لا يحمل إلا send_message لا يستطيع سرد قائمة جهات الاتصال لديك. وفوق الصلاحيات، يمكن أن يحمل المفتاح تاريخ انتهاء وقائمة عناوين IP مسموح بها، فيتوقف المفتاح الصادر لخادم ذي عنوان ثابت عن العمل لحظة استخدامه من أي مكان آخر.
- send_message يشمل إرسال النصوص والوسائط، وقراءة حالة إرسال موضوع في قائمة الانتظار.
- read_contacts و read_messages و read_labels هي جانب القراءة، ويمكن منح كل منها على حدة.
- manage_contacts و manage_labels تشملان الإنشاء والتحديث ووضع التسميات.
- check_phone يجيب عمّا إذا كان الرقم متاحًا على واتساب.
- manage_webhooks ينشئ اشتراكات Webhooks ويسردها ويحذفها.
الطلب
curl -X POST https://api.spun.com/api/integrations/send-message \
-H "Authorization: Bearer wap_0f3c9a1d7b524e86a1c05d9e2f7b48ac" \
-H "Content-Type: application/json" \
-d '{
"to": "+14155550142",
"text": "Your appointment is confirmed for Thursday at 10:00.",
"idempotency_key": "booking-8871"
}'الاستجابة
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"message_id": "yq0Zt9C1sK2mfE7x"
}المفاتيح المنشأة لخادم Spun MCP تُرفض عمدًا على هذه الواجهة حتى عندما تكون مفاتيح صالحة. فللواجهتين دلالات موافقة مختلفة، والمفتاح الصادر لإحداهما لا يصبح صالحًا للأخرى بصمت.
ما الذي تغطيه نقاط نهاية API واتساب فعلًا
الواجهة صغيرة ومستقرة عن قصد، وليست نسخة شاملة من المنتج. وُجدت كي يتمكن نظام خارجي من أداء ما تحتاج الأنظمة الخارجية فعلًا إلى أدائه.
- الإرسال: رسالة نصية، أو وسائط على شكل رابط URL أو base64، مع تعليق اختياري.
- جهات الاتصال: إنشاء جهة اتصال، وتحديثها، وسرد جهات الاتصال مع ترقيم صفحات بالمؤشر.
- التسميات: سرد التسميات في مساحة العمل، وتطبيق تسمية على محادثة، وإزالتها.
- الرسائل: سرد الرسائل مع ترقيم صفحات بالمؤشر، للمزامنة مع مستودع بيانات أو نظام CRM.
- فحص الرقم: التأكد من أن الرقم على واتساب قبل أن تبني قائمة حوله.
- قائمة الانتظار: الاستعلام عن إرسال وُضع في قائمة الانتظار لأن الخط كان غير متصل.
- Webhooks: إنشاء الاشتراكات وسردها وحذفها.
العقد المقروء آليًا منشور على /api/integrations/openapi.json ولا يحتاج إلى مفتاح لقراءته، فيستطيع مطوّر عقدة n8n أو منشئ تطبيق Zapier أو مولّد الكود الخاص بك سحب المواصفات قبل أن تُصدر لهم أي بيانات اعتماد.
ماذا يحدث حين يكون خط واتساب غير متصل
هذا هو الجزء الذي يفاجئ الناس، لذا يستحق التوضيح الصريح. يرسل Spun عبر جلسة واتساب حية، وقد تكون الجلسة الحية متوقفة في الثانية نفسها التي يستدعي فيها الكود الخاص بك. لا تتظاهر الواجهة بغير ذلك، وهي تتصرف مع النص بشكل مختلف عن الوسائط عن قصد.
إرسال نص إلى خط غير متصل يعيد 202 بدلًا من خطأ، مع معرّف في قائمة الانتظار. تُحتجز الرسالة وتُسلَّم حين يعود الخط للاتصال، ويمكنك الاستعلام من نقطة نهاية قائمة الانتظار عن مصيرها. أما إرسال وسائط إلى خط غير متصل فيعيد تعارضًا بدلًا من ذلك، ولا يُرسل شيئًا. وهذا التفاوت مقصود: فقائمة الانتظار تفرّغ الرسائل كنص، فكانت الصورة المنتظرة ستصل كتعليق بلا صورة. والفشل الواضح هو النتيجة الأفضل، ومنطق إعادة المحاولة لديك هو الذي يقرر.
حد المعدل 60 طلبًا في الدقيقة لكل مفتاح، مع ترويسات حد المعدل القياسية في كل استجابة، فيستطيع برنامج العميل أن يبطئ بناءً على الترويسات بدلًا من رمز 429 لم يتوقعه.
Webhooks: أن تُبلَّغ بدلًا من الاستعلام المتكرر
الاستعلام عن نقطة نهاية الرسائل على مؤقت أسلوب غير مناسب للمحادثة، لذا تستطيع الواجهة أن ترسل إليك بدلًا من ذلك. تسجّل عنوان URL والأحداث التي تهمك، فيرسل Spun إليه محتوى JSON فور وقوعها.
يحمل كل تسليم اسم الحدث ومعرّف تسليم فريدًا في الترويسات، وعندما يكون للاشتراك سر توقيع، يحمل أيضًا توقيع HMAC-SHA256 للمحتوى كما هو بالضبط. تحقق من التوقيع قبل أن تثق بالبيانات: فهو الشيء الوحيد الذي يفصل نقطة النهاية لديك عن أي شخص يعرف عنوانها. ويُعاد السر مرة واحدة، عند إنشاء الاشتراك، ولا يُعاد بعدها أبدًا.
- أحداث الرسائل، الواردة والصادرة.
- إنشاء جهة اتصال وتحديثها وحذفها.
- تعيين تسمية.
- اكتمال تدفق دردشة، ومعالجة إرسال من قائمة الانتظار، وتأهيل عميل محتمل.
- إغلاق محادثة، واكتمال مكالمة، وتغيّر مرحلة في مسار المبيعات.
ذات صلة: ربط Spun مع Zapier و Make · ربط Spun مع n8n · ربط نظام مكتب مساعدة: Zendesk، Zoho Desk، Freshdesk، HubSpot Service Hub، Jira
الحدود والتحفظات بصراحة
- هذه ليست واتساب Business API. إنها واجهة API خاصة بـ Spun أمام رقمك المرتبط، فلا توجد قوالب رسائل تحتاج إلى موافقة ولا رسوم على كل رسالة، وبالمقابل لا توجد ضمانات رسمية من Meta.
- ستون طلبًا في الدقيقة لكل مفتاح. العمل بالجملة مكانه الحملات، التي تضبط سرعتها كما ينبغي، لا حلقة API متلاحقة.
- قائمة نقاط النهاية أعلاه هي الواجهة كلها اليوم. ما ليس فيها غير متاح، ولا ينبغي الاعتماد على أي نقطة نهاية غير موثقة.
- المفتاح محدد الصلاحيات لكنه ليس خاصًا بمستخدم بعينه. تعامل معه كبيانات اعتماد لمساحة العمل، وغيّره حين يغادر شخص لديه صلاحية الوصول.
- الإرسال إلى أشخاص لم يوافقوا قط سيؤدي إلى تقييد الرقم من واتساب، أيًا كان المسار الذي سلكته الرسالة.
ذات صلة: كيف يتصل Spun بواتساب