انتقل إلى المحتوى
المطورون

مرجع Entagl API

مرجع الـ API
v1
98 endpoint
58 حدث webhook

الـ API بتاع Entagl بيخلّي برنامجك يشتغل مع الـ workspace بتاع Entagl: جهات الاتصال، المحادثات، الرسائل، الحجوزات، التذكيرات، الطلبات، المنتجات، مكالمات الـ AI والحملات. والـ webhooks بتبلّغ أنظمتك لحظة ما أي حاجة تحصل. وهو نفس الـ API اللي تطبيق Entagl على Make بيستخدمه.

الـ Base URL

HTTPS
https://api.entagl.com/api/v1

الـ requests والـ responses بصيغة JSON فوق HTTPS. أسماء الـ fields بتكون بـ snake_case. الـ IDs أرقام صحيحة إلا لو الـ endpoint قال غير كده. الأوقات نصوص بصيغة ISO 8601، والـ responses بتستخدم UTC.

المصادقة

ابعت token مع كل request في الـ header بتاع Authorization: Authorization: Bearer <token>. فيه نوعين من الـ token بيشتغلوا:

مفتاح API

للكود بتاع السيرفر الخاص بيك. اعمل واحد من تطبيق Entagl تحت الإعدادات → مفاتيح API. المفاتيح بتبدأ بـ ai_. المفتاح بيشتغل على الـ workspace اللي اتعمل فيه وليه صلاحيات المالك هناك، فخلّيه سري ومتحطوش أبدًا في متصفح أو تطبيق موبايل.

افتح مفاتيح API

OAuth 2.0 access token

بتستخدمه الـ connectors زي تطبيق Entagl على Make. الشخص بيسجّل دخول بحساب Entagl بتاعه، والـ connector بيشتغل نيابة عنه بدوره في الـ workspace. لو عايز تبني OAuth integration خاص بيك، كلّم support@entagl.com.

الطلب
curl "https://api.entagl.com/api/v1/contacts?limit=2" \
  -H "Authorization: Bearer ai_your_api_key"

لو الـ header ناقص الرد هيبقى 401 unauthenticated. المفتاح الغلط أو الملغي بيرد بـ 401 invalid_api_key. الـ OAuth token المنتهي بيرد بـ 401 invalid_token: جدّده وجرّب تاني.

الـ Workspaces والصلاحيات

كل request بيشتغل على workspace واحد بالظبط. مفتاح الـ API دايمًا بيستخدم الـ workspace بتاعه. الـ OAuth login ممكن يبقى تابع لأكتر من workspace (بتملكها أو انضممت لها كعضو فريق): ابعت header اسمه X-Entagl-Workspace ومعاه الـ ID بتاع الـ workspace علشان تختار واحد. لو فيه workspace واحد الـ header اختياري. الـ GET /me بيشتغل من غير الـ header وبيعرض كل الـ workspaces اللي الـ login يقدر يستخدمها.

الطلب
curl "https://api.entagl.com/api/v1/me" \
  -H "Authorization: Bearer <oauth_access_token>"

curl "https://api.entagl.com/api/v1/contacts" \
  -H "Authorization: Bearer <oauth_access_token>" \
  -H "X-Entagl-Workspace: <workspace_id from /me>"

من غير الـ header على login فيه أكتر من workspace هتاخد 400 workspace_required؛ وأي workspace الـ login ماعندوش وصول ليه بيرد بـ 403 workspace_forbidden. أي ID بتاع workspace تانية بيرد دايمًا بـ 404 not_found، عمره ما بيبقى 403.

كل endpoint تحت بيوضّح الصلاحية اللي محتاجها. المالكين والـ admins ومفاتيح الـ API بيعدّوا كل الفحوصات. أعضاء الفريق بيعدّوا لو دورهم عليه الصلاحية دي معلّمة في إعدادات الفريق: contacts أو inbox أو calendar أو orders أو business_pages أو call_agent أو campaigns أو integrations. من غيرها الـ API بيرد بـ 403 insufficient_permissions.

الـ Requests والأخطاء

ابعت الـ bodies بصيغة JSON مع Content-Type: application/json. أغلب الـ endpoints بترفض أي field مش معروف في الـ body بـ 422، فأي غلطة إملائية مش هتعدّي بصمت. كل الأخطاء ليها نفس الشكل: code ثابت تقدر تبني عليه، وmessage مقروء، وفي أخطاء التحقق قايمة details بتشاور على كل field غلط.

422
{
  "error": {
    "code": "validation_failed",
    "message": "Invalid email address",
    "details": [
      { "path": "email", "message": "Invalid email address" }
    ]
  }
}
  • 400request غلط: ID غير صالح، cursor غير صالح، أو header الـ workspace ناقص.
  • 401token ناقص أو غير صالح أو منتهي.
  • 402الـ credits مش كفاية للعملية (مثلاً لما تبعت حملة).
  • 403اتعمل تسجيل دخول بس مش مسموح: صلاحية ناقصة أو مفيش وصول للـ workspace.
  • 404مش موجود، وده يشمل الـ IDs بتاعة workspace تانية.
  • 409تعارض: اسم مكرر، حالة غلط، أو تضارب في Idempotency-Key.
  • 422فشل التحقق، أو قاعدة شغل رفضت التغيير.
  • 429وصلت لحد الاستخدام. بص على Retry-After.
  • 500 / 502Entagl أو قناة المراسلة فشلت. اتأكد من النتيجة قبل ما تعيد أي عملية كتابة.

المسارات اللي عليها علامة تنسيق الرد القديم أقدم من القواعد دي: بترجّع JSON objects أو arrays عادية وبترد على أغلب الأخطاء بـ { "message": "…" }.

تقسيم الصفحات

الـ endpoints اللي عليها علامة مقسّم لصفحات بترجّع أحدث العناصر الأول، جوه كائن list. اطلب لحد 100 عنصر بـ limit (الافتراضي 25). لما has_more تبقى true، ابعت next_cursor على إنه starting_after علشان تجيب الصفحة اللي بعدها. باقي القوايم بترجّع كل حاجة مرة واحدة مع has_more: false.

الرد
{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": 6789,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "phone": "+15551234567",
      "tags": ["vip"]
    }
  ],
  "has_more": true,
  "next_cursor": "6789"
}
الصفحة اللي بعدها
curl "https://api.entagl.com/api/v1/contacts?limit=100&starting_after=6789" \
  -H "Authorization: Bearer ai_your_api_key"

Idempotency

كل POST endpoint بالتنسيق العادي بيقبل header Idempotency-Key (لحد 200 حرف). استخدم قيمة مختلفة لكل عملية، زي UUID. Entagl بيحفظ أول رد لمدة 24 ساعة: لو كررت الطلب بنفس المفتاح ونفس الـ body هيرجعلك نفس الرد مع Idempotent-Replayed: true، ومفيش حاجة بتتنفذ مرتين. المسارات اللي عليها تنسيق الرد القديم بتشتغل بشكل مختلف، شوف تحت.

الطلب
curl -X POST "https://api.entagl.com/api/v1/contacts" \
  -H "Authorization: Bearer ai_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f9c1d2e-order-7781" \
  -d '{ "first_name": "Jane", "phone": "+15551234567", "tags": ["vip"] }'
  • نفس المفتاح مع body مختلف بيرد بـ 409 idempotency_key_reused.
  • لو أول request لسه شغال، أو لو ماخلصش أبدًا، إعادة المحاولة بترد بـ 409 request_in_progress. اتأكد من النتيجة الأول، وبعدين جرّب بمفتاح جديد.
  • كل نتيجة بتتخزن، حتى الأخطاء. لو عايز تجرّب request فشل تاني، استخدم مفتاح جديد.
  • المفاتيح مرتبطة بالـ workspace وبالـ credential.

المسارات القديمة. POST /messages كمان بيقبل Idempotency-Key (أو message_id في الـ body): لو كررت رسالة اتقبلت قبل كده هيرجع 202 بنفس conversationId ومش هتتعالج مرتين، ونفس المفتاح مع body مختلف بيرجع 409. POST /chat مفيهوش حماية من التكرار: التكرار بيشغّل الذكاء الاصطناعي تاني، فاتأكد من النتيجة قبل ما تعيد المحاولة.

حدود الاستخدام

كل workspace يقدر يعمل 120 request في الدقيقة، ومشتركة بين كل مفاتيح الـ API والاتصالات بتاعته. الـ responses فيها RateLimit-Limit وRateLimit-Remaining وRateLimit-Reset (الثواني لحد ما النافذة تتصفّر). لو عدّيت الحد هتاخد 429 rate_limited ومعاه header اسمه Retry-After: استنى عدد الثواني ده وبعدين جرّب تاني. مسارات قناة الـ API القديمة مش بتتحسب في الحد ده.