توثيق API - واتساب

البدء السريع

ثلاث خطوات فقط لإرسال أول طلب.

1
أنشئوا مفتاح وصول
انتقلوا إلى صفحة مفاتيح الوصول وأنشئوا مفتاحًا جديدًا
إنشاء مفتاح وصول
2
أضيفوا المفتاح إلى ترويسة الطلب
Authorization: YOUR_ACCESS_…
3
أرسلوا طلبكم الأول
استخدموا أمثلة الكود أدناه

جديد · v2026-10-13

Vibrate API Skill

علّموا أداة الذكاء الاصطناعي لديكم واجهة Vibrate البرمجية بالكامل بعملية لصق واحدة. تعمل مع ChatGPT وClaude وClaude Code وCursor وGitHub Copilot.

01انسخوا المهارة (Skill)، أو الموجّه القصير إذا كانت أداتكم قادرة على فتح الروابط.
02الصقوا ما نسختموه في ChatGPT أو Claude أو Cursor أو Claude Code كأول رسالة.
03اطلبوا ما تحتاجون إليه: "أرسل SMS من خادم Node الخاص بي"، "تحقق من حالة التسليم"، "أرسل قالب واتساب إلى قائمتي".

تعمل مع: ChatGPT ·Claude ·Claude Code ·Cursor ·GitHub Copilot

Claude Code / Cursor: تثبيت لمرة واحدة

mkdir -p .claude/skills/vibrate-api
curl -fsSL https://www.vibrate.co.il/vibrate-api-skill.md -o .claude/skills/vibrate-api/SKILL.md

/vibrate-api-skill.md · 41.5 KBفتح الملف الخام صفحة عامة

نظرة عامة

إرسال رسائل القوالب عبر WhatsApp Business API

whatsappNumberId — انتقلوا إلى قنوات واتساب وانسخوا معرّف الرقم المطلوب

templateId — انتقلوا إلى قوالب الرسائل وانسخوا معرّف القالب المطلوب

المعلمات

المعلمة	النوع	إلزامي	الوصف
`whatsappNumberId`	string	نعم	معرّف رقم واتساب الذي سيتم الإرسال منه
`templateId`	string	نعم	معرّف القالب (بما في ذلك اللغة)
`recipient`	string	نعم	رقم هاتف المستلم (بأي تنسيق)
`bodyVariables`	string[]	لا	مصفوفة قيم لمتغيرات نص الرسالة ({{1}}، {{2}})
`headerVariables`	string[]	لا	مصفوفة قيم لمتغيرات الترويسة
`headerMediaUrl`	string	لا	رابط URL للوسائط (صورة/فيديو/مستند)

تنسيق رقم الهاتف

يمكن إرسال أرقام الهواتف بأي تنسيق - سيحولها النظام تلقائيًا إلى التنسيق الصحيح:

0501234567972501234567+972501234567

نقاط النهاية

هاتان النقطتان موجودتان على www.vibrate.co.il وليس على api.vibrate.co.il، بنفس مفتاح الوصول.

متغيرات القوالب

مرحبًا {{1}}، تم شحن طلبك رقم {{2}}!

مرحبًا أحمد، تم شحن طلبك رقم ORD-12345!

مهم: يجب أن يطابق ترتيب القيم في المصفوفة bodyVariables ترتيب المتغيرات في القالب.

أنواع الترويسات (Headers)

TEXT

نص عادي، ويمكن أن يحتوي على متغيرات

IMAGE

JPG/PNG، حتى 5MB

VIDEO

MP4، حتى 16MB

DOCUMENT

يفضل PDF، حتى 100MB

أخطاء شائعة

INVALID_TEMPLATEالقالب غير موجود أو غير معتمد

INVALID_PHONEرقم الهاتف غير صالح

MISSING_VARIABLESبعض المتغيرات المطلوبة مفقودة

INVALID_MEDIA_URLرابط الوسائط غير صالح أو يتعذر الوصول إليه

INVALID_WHATSAPP_NUMBERمعرّف قناة واتساب غير صالح

Webhook لحالة التسليم

بدلاً من الاستعلام المتكرر، يمكن لـ Vibrate إرسال حدث موقّع إليك عند كل تغيير في حالة رسالة واتساب: sent أو delivered أو read أو failed. إنه نفس webhook الخاص بالرسائل القصيرة، نفس العنوان ونفس سر التوقيع، مع اسم حدث مختلف فقط.

1احفظ عنوان HTTPS في صفحة WhatsApp → API و Webhooks. يُعرض السر مرة واحدة.
2في الصفحة نفسها فعّل "إرسال تحديثات حالة WhatsApp أيضًا" وأرسل حدث اختبار واتساب.
3تحقق من كل طلب: HMAC-SHA256 على "timestamp.body" بالسر، مقارنةً بترويسة X-Vibrate-Signature. الكود الذي يتحقق من أحداث SMS يعمل دون تغيير.

نص الحدث

{
  "apiVersion": "v1",
  "event": "whatsapp.status",
  "messageId": "wamid.HBgLOTcyNTAxMjM0NTY3...",
  "whatsappNumberId": "c1f7c0e4-2b6e-4f3a-9d2a-5e8b1a2c3d4e",
  "templateId": "8a4f2d1e-6c3b-4a5d-9e8f-1b2c3d4e5f6a",
  "batchId": "batch_abc123",
  "campaignId": null,
  "subAccountId": null,
  "recipient": "972501234567",
  "status": "failed",
  "final": true,
  "error": { "message": "Message undeliverable", "code": "131026" },
  "sentAt": "2026-10-13T10:12:00.000Z",
  "occurredAt": "2026-10-13T10:12:07.000Z"
}

read نهائية. failed ليست دائماً كذلك: تراجع Meta أحياناً رسالة فاشلة إلى delivered أو read لاحقاً، فيُرسل حدث آخر. دع الحالة اللاحقة تستبدل failed.

أجب بـ 2xx خلال 10 ثوانٍ. يُعاد المحاولة مرتين عند الفشل (بعد نحو 5 و30 ثانية). قد تصل الأحداث أكثر من مرة وبغير ترتيب؛ أزل التكرار حسب messageId + status.

فتح إعدادات Webhook

الحسابات الفرعية

يعمل مفتاح الحساب الفرعي على جميع نقاط نهاية واتساب، لكن فقط مع الأرقام المخصصة لحسابه الفرعي: أي whatsappNumberId آخر يُرفض بـ 403 FORBIDDEN، ونقاط نهاية القوائم تعيد تلك الأرقام وقوالبها فقط. أحداث حالة تلك الأرقام تحمل subAccountId وتُرسل إلى webhook الحساب الفرعي إن كان لديه واحد، وإلا إلى webhook الحساب. تُخصص الأرقام في صفحة WhatsApp → API و Webhooks.

إرسال تلقائي من APIبدون كود

بدلاً من كتابة كود يستدعي Vibrate API، دع Vibrate يستدعي API الخاص بك. تسحب الأتمتة قائمة أشخاص من أي عنوان يعيد JSON وفق جدول زمني، وترسل لكل واحد منهم قالب واتساب معتمداً - مرة واحدة. مناسب لتذكيرات المواعيد وتحديثات الطلبات ومتابعة العملاء المحتملين.

فتح الأتمتة

كيف يعمل

1.المصدر
عنوان API (GET أو POST)، معاملات الاستعلام، الترويسات التي تحمل مفتاح API، وجسم الطلب. قيم الترويسات مشفرة ولا تُعرض مرة أخرى بعد الحفظ.
2.الاستخراج
أين توجد القائمة في الاستجابة، أين رقم الهاتف داخل كل عنصر، اسم للعرض، فلاتر، ومفتاح "نفس الشخص" يمنع الإرسال المزدوج.
3.الرسالة
رقم واتساب، قالب معتمد، ومتغير واحد لكل {{N}} في القالب. كل متغير هو نص مع عناصر نائبة مأخوذة من العنصر.
4.الجدول الزمني
كم مرة يُستدعى API (5 دقائق كحد أدنى)، نافذة إرسال بتوقيت إسرائيل، وكم مرة يمكن مراسلة نفس الشخص مجدداً.
5.الموافقة
افتراضياً تنتظر كل دفعة الموافقة: ترى كل شخص والرسالة بالضبط ثم تضغط إرسال. في الوضع التلقائي تخرج الرسائل بمجرد جاهزية القائمة.

مثال: تذكير بموعد الغد

لنفترض أن نظام الحجز يجيب على /appointments?from={{today+1}}&to={{today+1}} بهذه الاستجابة:

{
  "data": [
    {
      "id": "apt_18233",
      "status": "confirmed",
      "startTime": "2026-09-09T07:00:00.000Z",
      "customer": {
        "firstName": "דנה",
        "lastName": "לוי",
        "mobile": "050-1234567"
      }
    },
    {
      "id": "apt_18234",
      "status": "cancelled",
      "startTime": "2026-09-09T08:30:00.000Z",
      "customer": {
        "firstName": "יוסי",
        "lastName": "כהן",
        "mobile": "052-7654321"
      }
    }
  ]
}

الإعدادات المطابقة لهذه الاستجابة

الإعداد	القيمة
مسار القائمة	`data`
حقل الهاتف	`customer.mobile`
الاسم	`{{item.customer.firstName}} {{item.customer.lastName}}`
مفتاح "نفس الشخص"	`{{item.id}}`
فلتر	`status يساوي confirmed`
متغيرات نص الرسالة	`{{item.customer.firstName}} · {{item.startTime\|date}} · {{item.startTime\|time}}`

النتيجة: تتلقى دانا "مرحباً دانا، تذكير بموعدك غداً، 09/09/2026 الساعة 10:00". تعرض لسانية المعاينة هذا بالضبط قبل إرسال أي شيء.

عناصر التاريخ النائبة في الطلب

معظم واجهات API تتوقع نطاق تواريخ، وكل مزود يكتبه بشكل مختلف. اكتب صيغة المزود حول عناصر نائبة تُملأ وقت الطلب بتوقيت إسرائيل. تعمل في العنوان ومعاملات الاستعلام والترويسات والجسم. يقبل كل منها إزاحة بالأيام: {{today+1}}، {{startOfDay-7}}.

العنصر النائب	مثال للقيمة
`{{now}}`	2026-09-08T11:05:00.000Z	اللحظة الحالية بتوقيت UTC (ISO)
`{{unix}}`	1788001500	اللحظة الحالية بثواني epoch
`{{today}}`	2026-09-08	اليوم التقويمي في إسرائيل
`{{today+1}}`	2026-09-09	اليوم التقويمي في إسرائيل
`{{startOfDay}}`	2026-09-07T21:00:00.000Z	منتصف الليل في إسرائيل، بتوقيت UTC
`{{endOfDay}}`	2026-09-08T20:59:59.999Z	23:59:59.999 في إسرائيل، بتوقيت UTC
`{{startOfDay+1}}`	2026-09-08T21:00:00.000Z	منتصف الليل في إسرائيل، بتوقيت UTC
`{{endOfDay+1}}`	2026-09-09T20:59:59.999Z	23:59:59.999 في إسرائيل، بتوقيت UTC
`{{startOfDayLocal}}`	2026-09-08T00:00:00.000	منتصف الليل في إسرائيل، توقيت محلي بدون منطقة زمنية
`{{endOfDayLocal}}`	2026-09-08T23:59:59.999	نهاية اليوم في إسرائيل، توقيت محلي بدون منطقة زمنية

العناصر النائبة في الرسالة

الاسم ومفتاح "نفس الشخص" ومتغيرات القالب هي نص حر مع ثلاثة أنواع من العناصر النائبة:

{{fieldKey}}حقل عرّفته تحت "حقول للاستخراج". يُحل أولاً، لذا {{firstName}} أقصر من مسار خام ويصبح أيضاً عموداً في قائمة المستلمين.
{{item.path}}أي مسار داخل العنصر الخام، بما في ذلك المصفوفات: {{item.customer.phones[0]}}.
{{index}}موضع العنصر في الاستجابة، بدءاً من 1.

المنسقات

أضف خطاً عمودياً ومنسقاً بعد أي عنصر نائب. التواريخ (ISO أو epoch) تُعرض بتوقيت إسرائيل، لذا يصل 2026-09-09T07:00:00.000Z إلى العميل كـ 10:00 وليس كنص خام.

{{item.startTime|date}}09/09/2026

{{item.startTime|time}}10:00

{{item.startTime|datetime}}09/09/2026 10:00

{{item.startTime|weekday}}الأربعاء (بالعبرية)

{{item.startTime|dayMonth}}9/9

{{item.startTime|upper}}أحرف كبيرة

{{item.startTime|lower}}أحرف صغيرة

{{item.startTime|first}}الكلمة الأولى فقط

لماذا لا يتلقى شخص ما رسالة

يمر كل عنصر يُقرأ من الاستجابة بهذه الفحوصات بالترتيب. يظهر أول سبب مطابق بجانب العنصر في المعاينة وفي التشغيل، لذا المعاينة هي بالضبط ما سيفعله التشغيل.

1filteredرفض أحد الفلاتر العنصر.
2invalid_phoneلا يوجد رقم قابل للاتصال في حقل الهاتف. تُعرض القيمة الخام لمعرفة السبب.
3suppressedالرقم في قائمة "عدم الإرسال" الخاصة بالحساب (إلغاء اشتراك).
4duplicate_in_batchظهر نفس مفتاح "نفس الشخص" سابقاً في هذه الاستجابة.
5already_sentتمت مراسلة هذا المفتاح من قبل وسياسة التكرار تقول "ليس بعد".
6sendتُرسل الرسالة (أو تنتظر الموافقة).

الحدود والأمان

الفاصل بين الاستدعاءات: من 5 دقائق إلى 90 يوماً. يعمل المجدول كل 5 دقائق، لذا قد يبدأ التشغيل متأخراً حتى 5 دقائق.
حتى 300 رسالة في التشغيل الواحد. ما يتبقى يخرج في تشغيل متابعة بعد 5 دقائق.
تُقرأ حتى 5,000 عنصر من استجابة واحدة. الاستجابة محدودة بـ 8MB و20 ثانية.
يُسجل كل مستلم في السجل قبل استدعاء واتساب. حتى لو تعطل التشغيل في منتصفه، لن يتلقى نفس الشخص الرسالة مرتين.
تنتهي صلاحية الدفعة المنتظرة للموافقة بعد 7 أيام، ولا تُحضّر دفعة جديدة ما دامت واحدة مفتوحة.
وضع الاختبار يرسل كل شيء إلى رقمك، 5 رسائل في التشغيل، دون تعليم العملاء كمراسَلين.
قوالب معتمدة غير OTP فقط، على نفس الحساب التجاري للرقم. تمر الرسائل بنفس مسار API الإرسال وتظهر في الرسائل المرسلة وفي صندوق الوارد.