awam for developers

نظامك يظل الواجهة. أوام تشغّل واتساب.

اربط نظامك برقم أوام المشترك أو برقم النشاط المتصل عبر Meta. لكل نشاط اتصال ومفتاح ورصيد ومسار مستقل.

POST /api/v1/events/{connection-token}ابدأ بسرعة ↓تعليمات جاهزة للمطور وAI ↓

اتصال منفصل لكل نشاط

أنشئ حسابًا واتصال نظام لكل نشاط. احفظ المفتاح في الخادم فقط؛ تدويره يُبطل القديم.

اختر رقم الإرسال

رقم أوام يستخدم قوالب أوام. رقم النشاط الخاص يتطلب موافقة صاحبه داخل Meta ويستخدم قوالبه المعتمدة.

اربط الحالات بالمراحل

دخول مرحلة ذات رسالة يرسل قالبها المعتمد. تابع النتائج والردود عبر API.

الإعداد خطوة بخطوة

أنشئ مساحة عمل أوام لكل نشاط واختر رقم أوام أو وصّل الرقم الخاص في الإعدادات ← واتساب.

من الإعدادات ← الربط مع الأنظمة، أنشئ اتصالًا واختر المسار. احفظ مفتاح API الذي يظهر مرة واحدة في خادمك. استخدم رابط Event API للبيانات الموضحة هنا؛ رابط Webhook الخام للأنظمة ذات الحقول المختلفة.

اضبط قالب المرحلة ومتغيراته. أرسل عينة أولى؛ تُسجّل العينة فقط ولا ترسل رسالة. اربط قيمة event بمرحلة من شاشة الاتصال، ثم أرسل حدثًا ثانيًا بمعرف event_id جديد.

افحص account API قبل الإطلاق، ثم راقب نتائج الرسائل والردود. الحصة السارية أولًا؛ بعد نفادها يلزم رصيد مدفوع. رصيد التجربة محدود وينتهي.

UNIVERSAL QUICK START

حدث واحد واضح

استخدم event_id فريد وثابت لكل تغيير. إعادة نفس الحدث آمنة. اربط event بالمرحلة أولًا، وأرسل الخدمة أو الموعد إذا كان القالب يحتاجهما.

event قيمة الحالة الخارجية التي ربطتها بمرحلة
object.id معرف السجل في نظامك
object.customer الاسم ورقم واتساب الدولي والموافقة
object.scheduled_at موعد ISO 8601 إذا يطلبه القالب

curl -X POST "https://awam.io/api/v1/events/YOUR_CONNECTION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "workspace-42-record-100-update",
    "event": "workflow.status_changed",
    "object": {
      "id": "RECORD-100",
      "type": "request",
      "customer": {"name": "Mariam", "phone": "+201001112222", "language": "ar", "consent": true},
      "details": "General consultation",
      "scheduled_at": "2026-10-08T09:30:00.000Z"
    }
  }'

احمِ الاتصال والرسائل

مفتاح API خاص بمساحة عمل واحدة ومحفوظ مجزأ. لا تضعه في المتصفح أو تطبيق الهاتف أو السجلات أو محادثات AI. لا يختار طلب API رقم المرسل أو قالبًا عشوائيًا؛ يحدد ذلك إعداد المرحلة والاتصال.

موافقة المستلم على واتساب مطلوبة، واحترم طلبات إيقاف الرسائل
رابط ربط الرقم الخاص منفصل عن مفتاح API ومخصص للمتصفح
أوقف اتصال النظام أو دوّر المفتاح عند انكشافه
202 يعني قبول الطلب وليس وصول الرسالة

واجهات الإنتاج

POST/api/v1/events/{token}

أرسل JSON كما في المثال بمعرف event_id فريد وثابت لكل تغيير. أول حدث قد يكون عينة فقط؛ 202 لا يعني وصول الرسالة.

GET/api/v1/account/{token}

حالة النشاط والرقم، القوالب المعتمدة للرقم المستخدم، الرصيد بالقروش، الحصة و otp.available.

GET/api/v1/messages/{token}?limit=30&before_id=...

نتائج رسائل هذا الاتصال فقط، من الأحدث للأقدم. اقرأ status و error؛ استخدم next_before_id للصفحة التالية.

GET/api/v1/responses/{token}?after_id=0

ردود الأزرار الخاصة فقط بسجلات هذا الاتصال. خزّن next_after_id للجولة التالية.

POST/GET/api/v1/otp/{token}

أوام تنشئ رمز OTP وترسله، وتعرض حالة الرسالة. التحقق من الرمز في واجهة منفصلة أدناه.

POST/api/v1/otp/{token}/verify

تحقق من الرمز الذي أدخله العميل. النجاح verified:true مرة واحدة فقط؛ التحقق لا يخصم رسالة.

LINK/connect/whatsapp#{connect-token}

رابط مستقل لربط رقم النشاط عبر Meta. افتحه في المتصفح ولا تستخدمه كمفتاح API.

OPTIONAL AUTHENTICATION API

OTP من رقم أوام

من الإعدادات ← الربط مع الأنظمة، افتح اتصال API واختر تفعيل رمز التحقق. صاحب الحساب يفعّله بنفسه؛ لا يحتاج موافقة إدارة أوام. يتطلب قالب awam_verification_code المعتمد من Meta ورقم أوام. أخبر المستلم أن الرمز سيأتي من أوام. أوام تنشئه وتتحقق منه؛ نظامك يقرر الدخول بعد نجاح التحقق.

POST /api/v1/otp/{token} أرسل request_id فريدًا، رقمًا دوليًا، purpose مثل signup أو login، و consent:true. لا ترسل code كي تنشئه أوام
GET /api/v1/otp/{token}?request_id=… افحص حالة الإرسال فقط؛ هذه الواجهة لا تتحقق من الرمز
POST /api/v1/otp/{token}/verify أرسل request_id، رقم الموبايل، purpose والرمز الذي أدخله العميل من خادمك. verified:true يسمح لك بإكمال العملية مرة واحدة.
قالب Meta قُدم بصلاحية 10 دقائق. أوام تُلغي مهمة لم تُرسل بعد 10 دقائق. أوام تفرض انتهاء التحقق بعد 10 دقائق، وتوقف التحقق بعد خمس محاولات خاطئة، وترفض إعادة الاستخدام.
حد الإرسال لكل نشاط عبر كل اتصالات API: 3 طلبات للرقم خلال 10 دقائق و60 طلبًا في الدقيقة. الإعادة بنفس request_id لا تعيد الإرسال.
الإرسال يُحسب من الحصة السارية أولًا، ثم الرصيد المدفوع للزيادة. التحقق نفسه لا يخصم رصيدًا أو رسالة. ويمكن استخدام رصيد تجربة متاح دون خطة.
للتكاملات القديمة: إذا أرسلت code من نظامك، تظل أوام ترسل الرسالة فقط، ويجب أن يتحقق نظامك من الرمز بنفسه. واجهة verify لا تعمل مع هذا الوضع.

curl -X POST "https://awam.io/api/v1/otp/YOUR_CONNECTION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"signup_72658432","phone":"+201001112222","purpose":"signup","consent":true}'

# Replace 482916 with the code the person entered; call from your SERVER:
curl -X POST "https://awam.io/api/v1/otp/YOUR_CONNECTION_TOKEN/verify" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"signup_72658432","phone":"+201001112222","purpose":"signup","code":"482916"}'

ما الذي يجب أن يعرضه نظامك؟

اعرض الحالة والرصيد داخل واجهتك. عندما status ليست connected اعرض زر ربط واتساب. عندما reauthorization_required تساوي true اعرض إعادة الربط. وعند انخفاض الرصيد اعرض إضافة رصيد أو تواصل مع مسؤول الحساب.

available_balance_minor / 100
messages_remaining
overage_price_minor / 100
whatsapp.status

الاستجابات وحالات الرسالة

202تم الاستلام؛ افحص نتيجة الإرسال لاحقًا200قراءة أو حدث مكرر403/409اتصال موقوف، ميزة غير مفعلة، قالب غير متاح429انتظر Retry-After وأعد الطلب بنفس المعرف

الحالات تشمل pending و sent و delivered و read و failed و waiting_template و blocked_balance. sent تعني أن Meta قبلت الطلب، وليس أنه وصل. blocked_balance تعني حصة أو رصيدًا غير كافٍ.

لو الرسالة لم تصل، افحص بالترتيب

sampleReceived: true يعني أن أول حدث سجّل عينة فقط. اربط قيمة event بالمرحلة، ثم أرسل حدثًا جديدًا بمعرف مختلف.

needsMapping: true يعني أن الحالة الخارجية غير مربوطة بمرحلة. أضف ربط الحالة من شاشة الاتصال؛ ستتم إعادة معالجة الأحداث المناسبة.

waiting_template يعني أن القالب غير متاح. لرقم أوام اختر قالبًا معتمدًا ومتاحًا للمرحلة؛ لرقم النشاط حدّث قوالب Meta الخاصة به واختر المعتمد. أكمل متغيرات الخدمة والموعد التي يتطلبها القالب.

blocked_balance يعني أن الحصة والرصيد المؤهل لا يكفيان. افحص billing في account API. أما sent فتعني قبول Meta فقط؛ تابع delivered أو read أو failed لمعرفة النتيجة.

تعليمات جاهزة للمطور أو AI

انسخ التعليمات، وحدد نوع رقمك وحالة استخدامك. لا تلصق المفتاح الحقيقي في محادثة AI؛ ضعه في متغير بيئة على الخادم.

Integrate my server with https://awam.io/developers. My sender is [Awam number / own coexistence number] and my use case is [appointments/orders/OTP/other]. Never request or paste a live API token in this chat; use a server environment variable. Each business needs its own Awam workspace and Settings → Connect your system API connection. Use the canonical Event API URL for the JSON schema below; the raw Webhook URL is for external providers with their own field names. Call GET /api/v1/account/{token} to inspect whatsapp.mode/status, integration.status, billing.subscription.messages_remaining, paid_balance_minor and otp.available. Configure approved templates and variable mappings on workflow stages (Awam templates for the shared number, customer WABA templates for coexistence). POST /api/v1/events/{token} with a unique stable event_id for each change, event matching a mapped external status, object.id, customer name/international phone/consent, details and scheduled_at when the stage template needs them. First POST captures a sample only: map its event value to a stage in Awam, then send a NEW event_id. 202 is not WhatsApp delivery. Poll GET /api/v1/messages/{token}?before_id=... for outcomes and GET /api/v1/responses/{token}?after_id=... for replies; persist cursors. For OTP on Awam's number, the workspace owner enables it on the API connection in Settings → Connect your system. Check otp.available=true. For the recommended managed flow POST /api/v1/otp/{token} with unique request_id, phone, purpose and consent:true (omit code); Awam generates and sends a six-digit code. Poll GET /api/v1/otp/{token}?request_id=... for message delivery only. On my server POST /api/v1/otp/{token}/verify with the same request_id, phone, purpose and code entered by the person. Only verified:true permits my app to complete signup/login. Keep request_id bound to my own pending user/session. A wrong code, expiry, fifth wrong attempt or reuse fails; verification is free, the message uses quota then paid overage. The legacy POST with a developer-generated code still works but my server must verify that code itself. Respect 429 Retry-After; handle paused connection, unavailable templates and blocked_balance. Show exact backend code, stage/status mapping, idempotent retries, safe test and failure handling. Ask for field names but never my live secret.