التوثيق والـAPI

كيف تعمل بيئة التجربة

• مساحة خاصة بك: كل مطور يحصل على مساحة خاصة تبدأ بـ50 رسالة و50 مكالمة كأمثلة.
• نفس شكل الردود: الطلب الصحيح يرجع نفس رد الـAPI الحقيقي، مع "simulated": true وتلميح للخطوة التالية.
• أخطاء تعلّمك: الطلب الخاطئ يخبرك أي حقل فيه خطأ، وما المتوقع، وما الذي وصل، ومثالاً صحيحاً.
• دورة حياة حية: الرسائل: أُرسلت ← وصلت (~5 ثوانٍ) ← قُرئت (~20 ثانية). إذن الاتصال يُمنح بعد ~10 ثوانٍ، والمكالمة تكتمل بعد ~15 ثانية مع نص المكالمة.

احصل على الوصول

1. اطلب رمز التجربة: راسلنا على maomel.hadi@adamhub.ai وينشئ فريقنا مساحتك ويرسل لك رمزاً شخصياً يبدأ بـrc_.
2. احفظه بسرية: الرمز يظهر مرة واحدة. لا تشاركه ولا تضعه في كود عام، واطلب منا إلغاءه إذا تسرّب.
3. أرسله مع كل طلب: أضف الترويسة Authorization: Bearer rc_YOUR_CODE. العنوان الأساسي: https://mockapi.adamhub.ai/api/v1/whatsapp

أول طلب

مثل الواتساب الحقيقي، الرسالة النصية الحرة تُرسل فقط خلال 24 ساعة من آخر رسالة للزبون. لذلك حاكِ أولاً زبوناً يراسلك، ثم رد عليه. أرقام الهاتف بالصيغة الدولية (+964…).

# 1. A customer writes to you
curl -X POST https://mockapi.adamhub.ai/api/v1/whatsapp/simulate/inbound \
  -H "Authorization: Bearer rc_YOUR_CODE" \
  -H "Content-Type: application/json" \
  -d '{"from": "+9647701234567", "body": "Hi, are you open today?", "ai_reply": false}'

# 2. You reply
curl -X POST https://mockapi.adamhub.ai/api/v1/whatsapp/send \
  -H "Authorization: Bearer rc_YOUR_CODE" \
  -H "Content-Type: application/json" \
  -d '{"to": "+9647701234567", "body": "Hello from Adam"}'

عندما يكون هناك خطأ

نفس الطلب برقم محلي (07…) يرجع خطأ يوضح طريقة التصحيح:

{
  "ok": false,
  "error": {
    "code": "phone_needs_plus",
    "message": "The real API requires the phone to start with '+'.",
    "field": "to",
    "got": "07701234567",
    "example": "+9647701234567"
  }
}

الرسائل

• POST /send: إرسال رسالة نصية واحدة: to و body.
• POST /send-bulk: إرسال لأرقام كثيرة، نصاً عادياً أو بقالب ومتغيرات؛ وينشئ حملة.
• POST /simulate/inbound: خاص ببيئة التجربة: محاكاة زبون يراسلك (from و body)، مع رد ذكي اختياري.
• GET /conversations: قائمة المحادثات؛ و GET /conversations/{id}/messages للرسائل.
• GET /templates: قوالب الرسائل المتاحة لك.
• GET /campaigns: الحملات وأرقام التوصيل؛ و GET /campaigns/{id} لحملة واحدة.
• GET /me · GET /balance: مساحتك، وعدد الرسائل والمكالمات المتبقية.

المكالمات

مكالمة الواتساب تحتاج موافقة الزبون أولاً، تماماً مثل المسار الحقيقي:

# 1. Ask the customer for permission (granted after ~10s in the sandbox)
POST /api/v1/whatsapp/call-permissions/request   {"customer_phone": "+9647701234567"}

# 2. Check it
GET  /api/v1/whatsapp/call-permissions/+9647701234567

# 3. Call (ringing -> completed after ~15s)
POST /api/v1/whatsapp/calls/initiate              {"customer_phone": "+9647701234567"}

# 4. Read the result
GET  /api/v1/whatsapp/calls/{call_id}/transcript

• GET /calls: سجل المكالمات؛ فلترة بـ ?direction=inbound أو outbound.
• GET /calls/{id}/recording-url: رابط تسجيل المكالمة المكتملة. بيئة التجربة ترجع url: null، والـAPI الحقيقي يرجع رابطاً مؤقتاً.
• PATCH /calls/{id}/outcome: تحديد النتيجة: order_placed أو question_answered أو callback_requested أو complaint أو no_answer أو other.
• POST /call-permissions/refresh: قراءة حالة الإذن الحالية للزبون.

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

• منصة واتساب للأعمال: ربط رسمي مع ميتا عن طريق Embedded Signup، للرسائل والمكالمات.
• إنستغرام وماسنجر: الرسائل عن طريق واجهات ميتا الرسمية.

الأسئلة الشائعة

هل ترسل بيئة التجربة رسائل واتساب حقيقية؟

لا. لا يصل شيء إلى ميتا أو إلى زبون حقيقي؛ كل شيء محاكاة داخل مساحتك.

هل الـAPI الحقيقي مفتوح؟

ليس للعموم بعد. عندما يعمل ربطك في بيئة التجربة، تواصل معنا لنقله إلى حسابك الحقيقي في آدم.

صفحات ذات صلة

• مركز المعرفة: أدلة خطوة بخطوة لآدم هاب: أنشئ حسابك، جهّز الوكيل، اربط رقم هاتف أو واتساب، أطلق حملة واقرأ التحليلات.
• واتساب وإنستغرام وماسنجر: آدم يرد على رسائل واتساب وإنستغرام وماسنجر باللهجة العراقية من صندوق واحد. آدم هاب مزوّد تقني معتمد من ميتا.
• الدعم: طرق التواصل مع دعم آدم هاب: البريد الإلكتروني، المساعدة من لوحة التحكم، وحجز مكالمة مع الفريق في بغداد. وماذا تكتب في طلبك حتى نساعدك أسرع.