للمطوّرين

اربط نظامك بوامي

وامي يوصل رسائل نظامك إلى جوال المستخدم كإشعار، ويعيد إليك ردوده. الواجهة JSON فوق HTTPS، وتعمل من أي لغة برمجة.

  1. افتح شركتكمن لوحة الشركة، وخذ مفتاحك.
  2. اربط المستخدمزر «استقبل التنبيهات على وامي» في حسابه عندك.
  3. أرسلطلب واحد عند كل حدث.
  4. استقبل الردوداختياري: لنظامك أو لفريقك في وامي.
افتح شركتك وخذ المفتاح

العنوان والمفتاح

كل الطلبات إلى هذا العنوان، ومعها المفتاح في الترويسة:

https://wamyapp.com/api/v1/

Authorization: Bearer wmy_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

المفتاح سرّي ويبقى في خادمك فقط. لا تضعه في صفحة ويب ولا في تطبيق جوال. الأخطاء ترجع بصيغة JSON فيها error و message.

أول رسالة في 5 دقائق

  1. افتح لوحة الشركة وأنشئ شركتك. يظهر لك المفتاح مرة واحدة: ضعه في متغير بيئة اسمه WAMY_KEY.
  2. في اللوحة اضغط «أرسل لي رسالة تجريبية»: تصلك في وامي فترى شكلها عند العميل، وتفعّل التنبيهات على جوالك.
  3. اطلب رابط ربط لحسابك أنت (القسم التالي) وافتحه، فيرتبط رقمك عندك بحسابك في وامي.
  4. أرسل بالمثال المجاور، وبدّل 42 برقمك.

أرسل

curl -X POST https://wamyapp.com/api/v1/send.php \
  -H "Authorization: Bearer $WAMY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": {"external_id": "42"},
       "title": "Order confirmed",
       "text": {"ar": "تم تأكيد طلبك رقم *5521*", "en": "Order *5521* is confirmed"},
       "ref": "order-5521-confirmed"}'

قواعد الشركات المسجّلة بنفسها

أي أحد يستطيع فتح شركة في وامي، لذلك تحمي القواعد التالية الناس من الرسائل غير المرغوبة، وتحمي حساباتهم. هي مبنية في الواجهة ولا يمكن تجاوزها.

  • تراسل من وافق فقطمن ربط حسابه بشركتك عبر رابط الربط، أو بدأ محادثة معك من رابط التواصل. إرسال رسالة لبريد لم يربط ولم يراسلك يرجع 404 recipient_not_found.
  • رابط الربط لا يدخل أحدًا بدلًا عنهمن يفتحه يسجّل الدخول إلى وامي ببريده هو (رمز أو Google)، ثم يُربط حسابه. لذلك لا فائدة من إرسال email في طلب الربط: يُتجاهل.
  • لا بريد من عنوانناemail_fallback و create غير متاحين للشركات المسجّلة بنفسها.
  • حد الطلباتحتى 120 طلبًا في الدقيقة لكل شركة.
  • الحساب غير موثّق في البدايةاطلب العلامة الخضراء من لوحة الشركة بعد أن تكمل بياناتك.
  • من يحظرك لا تصله رسائلك409 blocked_by_user

2. إرسال رسالة

/api/v1/send.phpPOST
الحقلالمعنى
to
مطلوب
المستقبل: {"external_id": "42"}
text
مطلوب
النص، أو {"ar": "…", "en": "…"} ليرى كل مستخدم لغته. حتى 4096 حرفًا. يدعم *عريض* و _مائل_ والروابط.
titleسطر عريض فوق النص (اختياري).
image_urlصورة برابط https (اختياري).
buttonsحتى 3 أزرار، نص الزر حتى 30 حرفًا: رابط {"type":"url","label":"…","url":"https://…"} أو رد سريع {"type":"reply","label":"…","payload":"…"}.
refرقمك المرجعي. نفس الرقم مرتين = نفس الرسالة، فإعادة المحاولة آمنة.
fileملف مرفق (انظر «المرفقات»).
senderأرسل باسم جهة (انظر «عدة جهات»).

pushed_devices: 0 تعني أن المستخدم لم يفعّل التنبيهات: الرسالة محفوظة له وتظهر حين يفتح وامي، لكنها لن تصله كإشعار.

curl -X POST https://wamyapp.com/api/v1/send.php \
  -H "Authorization: Bearer $WAMY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": {"external_id": "42"},
       "title": "Order confirmed",
       "text": {"ar": "تم تأكيد طلبك رقم *5521*", "en": "Order *5521* is confirmed"},
       "ref": "order-5521-confirmed"}'
الرد
201
{"id": 812, "status": "sent", "pushed_devices": 2, "emailed": false,
 "created_at": "2026-10-26T09:41:00+00:00", "delivered_at": null, "read_at": null,
 "ref": "order-5521-confirmed", "duplicate": false}
مثال أغنى
{"to": {"external_id": "42"},
 "title": "Appointment tomorrow",
 "text": {"ar": "موعدك غدًا الساعة 10:00", "en": "Your appointment is tomorrow at 10:00"},
 "image_url": "https://example.com/map.png",
 "buttons": [
   {"type": "url",   "label": {"ar": "الموقع", "en": "Location"}, "url": "https://maps.example.com/clinic"},
   {"type": "reply", "label": {"ar": "سأحضر", "en": "I will come"}, "payload": "confirm_1042"}
 ],
 "ref": "appt-1042-reminder"}

3. حالة الرسالة والمستخدم

قبل رسالة مهمة (رمز دخول، تأكيد دفع) اسأل: هل سيصله تنبيه؟ وبعدها اسأل: هل وصلت؟ فإن لم تصل تستعمل قناة أخرى.

/api/v1/user.php?external_id=42GET

linked · joined · notifications (عدد الأجهزة التي تستقبل التنبيهات) · blocked · muted · last_seen_at

/api/v1/message.php?ref=order-5521-confirmedGET
  • sent — محفوظة
  • delivered — وصلت إلى جهاز
  • read — فتحها المستخدم

تقبل id أو ref.

cURL
curl "https://wamyapp.com/api/v1/user.php?external_id=42" -H "Authorization: Bearer $WAMY_KEY"
# {"linked": true, "joined": true, "notifications": 2, "blocked": false, "muted": false, ...}

curl "https://wamyapp.com/api/v1/message.php?ref=order-5521-confirmed" -H "Authorization: Bearer $WAMY_KEY"
# {"id": 812, "status": "delivered", "pushed_devices": 2, ...}

4. استقبال الردود

ضع عنوان استقبال (Webhook) في لوحة الشركة وفعّل «يستطيع العملاء أن يكتبوا إلينا». كل رد أو ضغطة على زر رد سريع يصل إلى عنوانك هكذا:

POST https://your-app.example.com/wamy
X-Wamy-Timestamp: 1792800000
X-Wamy-Signature: sha256=…

{"event": "message", "id": 913, "app": "your-code",
 "from": {"external_id": "42", "email": null, "name": "Salem"},
 "text": "Great", "payload": "confirm_1042",
 "reply_to": {"id": 905, "ref": "appt-1042-reminder"},
 "file": null, "created_at": "2026-10-26T09:50:11+00:00"}
  • ردّ برمز نجاح من 200 إلى 299 خلال 6 ثوانٍ، وإلا نعيد المحاولة 5 مرات خلال ساعتين.
  • العنوان يجب أن يكون https عامًا يمكن الوصول إليه من الإنترنت. لا نتصل بعناوين الشبكات الداخلية.
  • من لم يربط حسابه (جاء من رابط التواصل) يصلك "external_id": null وبريده.
  • بعد أن تقرأ الرد استدع POST /api/v1/read.php {"id": 913} لتظهر للمستخدم العلامتان الزرقاوان.

تحقّق من التوقيع دائمًا

التوقيع هو HMAC-SHA256 للنص timestamp + "." + raw body بسرّ التوقيع الذي تجده في لوحة الشركة. ارفض الطلب إن مضى على الطابع الزمني أكثر من 5 دقائق.

<?php
$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_WAMY_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_WAMY_SIGNATURE'] ?? '';
$mine = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, getenv('WAMY_WEBHOOK_SECRET'));
if (!ctype_digit($ts) || abs(time() - (int) $ts) > 300 || !hash_equals($mine, $sig)) { http_response_code(401); exit; }
$event = json_decode($raw, true);   // {"event": "message", "id": 913, "from": {...}, "text": "..."}
http_response_code(204);            // any 2xx = received

رابط التواصل: الناس يبدؤون المحادثة

لكل شركة رابط تواصل. ضعه خلف زر «راسلنا على وامي» في موقعك، أو اطبعه رمز QR. من يفتحه يدخل ببريده إن لزم، ثم تُفتح له محادثة معك. لا تحتاج مفتاحًا ولا برمجة: تجده جاهزًا في لوحة الشركة.

/api/v1/contact.phpPOST

لتأخذه من الكود (أو لكل جهة ترسل باسمها): {"sender": {"id": "school-12", "name": "…"}}

  • open صحيحة حين تُقبل الردود ويوجد في الفريق من يرى الزوار. بدونها لا يعمل الرابط.
  • حماية من الإغراق: قبل أن تردّ أول مرة يرسل الشخص 5 رسائل في الساعة على الأكثر.
cURL
curl -X POST https://wamyapp.com/api/v1/contact.php -H "Authorization: Bearer $WAMY_KEY"
# {"url": "https://wamyapp.com/start.php?to=your-code", "open": true}
HTML
<a href="https://wamyapp.com/start.php?to=your-code" target="_blank" rel="noopener">
  Message us on Wamy
</a>

فريق الردود

من يرد باسم شركتك داخل وامي: موظف استقبال، معلم، فريق مبيعات. يدخل وامي فيجد تبويب «الردود» فيه كل من كتب إليكم. أسهل طريقة: أضفه ببريده من لوحة الشركة. ومن الكود:

/api/v1/agent.phpPOST
الحقلالمعنى
external_id
مطلوب
الشخص عندك. يجب أن يكون قد ربط حسابه أولًا.
titleالاسم الظاهر للناس على ردوده (الافتراضي: اسمه).
peopleقائمة أرقام: يرى محادثات هؤلاء فقط (معلم وأولياء أمور صفّه). بدونها يرى الكل.
scope"guests": يرى الزوار فقط، من ليسوا مستخدمين عندك بعد.
activefalse يزيله من الفريق.
cURL
curl -X POST https://wamyapp.com/api/v1/agent.php \
  -H "Authorization: Bearer $WAMY_KEY" -H "Content-Type: application/json" \
  -d '{"external_id": "u-15", "title": "Ms Huda, Grade 5 teacher", "people": ["p-101", "p-102"]}'

المرفقات: صور ومستندات

الرسالة تحمل ملفًا واحدًا: صورة (jpg، png، webp) أو مستندًا (pdf، doc/docx، xls/xlsx، ppt/pptx، txt، csv)، حتى 10 ميجابايت. يُعرف نوع الملف من محتواه لا من اسمه، وتُعاد رسم الصور فتسقط منها بيانات الكاميرا والموقع.

ملف يرسله المستخدم يصل إلى عنوان الاستقبال في الحقل "file": {"url", "name", "mime", "size"}. الرابط موقّع وصالح 7 أيام، فنزّل الملف إن احتجته.

JSON
{"to": {"external_id": "42"}, "text": "Your invoice",
 "file": {"name": "invoice.pdf", "data": "<base64 of the file>"}}

عدة جهات بمفتاح واحد

منصة تخدم عدة مدارس أو فروع أو عيادات؟ أضف الحقل sender عند الإرسال وعند طلب الربط، فتظهر كل جهة للمستخدم محادثة مستقلة باسمها وشعارها، وتُنشأ عند أول استعمال. المستخدمون مربوطون بشركتك: رقمهم عندك واحد في كل الجهات.

  • الردود تصل إلى عنوانك ومعها "sender": {"id": "school-12"}.
  • حالة المستخدم في جهة معينة: user.php?external_id=42&sender_id=school-12.
  • لكل جهة رابط تواصل خاص: يطلبه نظامك من contact.php.
JSON
"sender": {"id": "school-12",
           "name": {"ar": "مدرسة النور", "en": "Al Noor School"},
           "logo_url": "https://example.com/logo.png", "color": "#017672"}

الأخطاء والحدود

الرمزالمعنى
400 bad_jsonالجسم ليس JSON صحيحًا.
401 unauthorizedالمفتاح خطأ، أو الشركة موقوفة.
404 recipient_not_foundالمستخدم لم يربط حسابه بعد، أو لم يراسلك.
409 blocked_by_userالمستخدم حظر شركتك.
413 file_too_bigالملف أكبر من 10 ميجابايت.
422 text_requiredلا نص ولا عنوان ولا صورة ولا ملف.
422 text_too_longالنص أطول من 4096 حرفًا.
422 buttons_invalidأكثر من 3 أزرار، أو نص زر أطول من 30 حرفًا، أو رابط غير صحيح.
422 image_must_be_httpsرابط الصورة يجب أن يبدأ بـ https.
429 rate_limitedتجاوزت حد الطلبات في الدقيقة. الرد يذكر الحد، وأعد المحاولة بعد قليل.

نصائح

  • أرسل ref مع كل رسالة، فتكون إعادة المحاولة بعد انقطاع الشبكة آمنة.
  • لا تُوقف عمل نظامك إن تعذّر الإرسال: سجّل الخطأ وتابع.
  • للمهم جدًا (رمز دخول) اسأل حالة المستخدم أولًا، واحتفظ بقناة بديلة.
  • لا تراسل إلا من ربط حسابه أو راسلك: هذا ما نفرضه، وهذا ما يريده الناس.

التنزيلات

لا تحتاج مكتبة: كل ما فوق يعمل بطلب HTTP عادي. لمن يستعمل PHP ملف واحد يغلّف الطلبات ويتحقق من توقيع الردود.

WamyClient.php
PHP
require 'WamyClient.php';
$wamy = new WamyClient('https://wamyapp.com', getenv('WAMY_KEY'));
$url = $wamy->linkUrl((string) $user->id);                       // 1. link
$wamy->send(['external_id' => (string) $user->id],               // 2. send
    ['ar' => 'تم تأكيد طلبك', 'en' => 'Your order is confirmed'],
    ['ref' => 'order-5521-confirmed']);
$ok = WamyClient::verifyWebhook($raw, $ts, $sig, $secret);       // 4. verify a reply