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

قناة API

وصّل Entagl بتطبيقك أو بـ Make: ابعت الرسائل، استقبل الردود، وادير workspace بتاعك.

نظرة عامة

قناة الـ API بتخليك تشغّل نفس الـ AI agent اللي بيشغّل الـ DMs بتاعتك من chat بتاع موقعك، أو mobile app، أو backend. إنت بتبعت رسالة، والـ agent بيفكر (بنفس الـ buffering وردود متعددة شبه الإنسان زي الـ DM الحقيقي)، والرد بيوصل لك بعد شوية، من خلال webhook callback أو polling. فعّلها من القنوات → API: اعمل API key، شغّل القناة، وبعدها اختار callback أو polling. نفس الـ API كمان بيسمح لمطورك، أو Make، يتعامل مع contacts, conversations, bookings, orders والمزيد. شوف تبويب Workspace API.

للمطوّرين: مرجع الـ API
كل endpoint وfield وحدث webhook، مع أمثلة كود.

التبويبات في الصفحة دي

الـ API مش للـ chat بس. مطورك، أو أداة زي Make، يقدر يستخدمه لقراءة وتحديث معظم الـ workspace بتاعك.

تقدر تعمل بيه إيه

غير إرسال الرسائل، الـ API بيغطي:

  • Contacts: إنشاء، تحديث، بحث، دمج، إضافة ملاحظات، وتحديد do-not-contact
  • Tags و lifecycle stages: إضافة أو إزالة tags، ونقل contact لمرحلة تانية
  • Conversations: assignment لزميل، إغلاق بـ closing note، إيقاف أو استئناف الـ AI، إضافة team comments، وإرسال رسالة باسم البزنس بتاعك
  • Bookings و reminders: فحص الأوقات الفاضية، الحجز، إعادة الجدولة، الإلغاء، وإنشاء وإغلاق reminders
  • Orders و products: إنشاء وتحديث orders وعناصرها، وإدارة الكتالوج بتاعك
  • Calls: بدء AI phone call أو إضافتها في queue، وقراءة النتيجة
  • Campaigns: تشوف campaigns بتاعتك وتبعت واحدة

لما حاجة بتتغير، Entagl يقدر يبلغ أدواتك فورًا عن طريق webhooks.

طريقتين للـ sign in

Make. لما توصل Make، بتسجّل دخول بحساب Entagl بتاعك. بعد كده Make بيتصرف كأنك إنت، بنفس صلاحياتك بالضبط: الـ owner أو admin يقدر يعمل كل حاجة، و team member يقدر يعمل بس اللي صلاحياته تسمح بيه. لو الـ login بتاعك فيه أكتر من workspace، إنت بتختار أنهي واحد تستخدمه.

API key. لسيرفرك بتاعك، اعمل key من القنوات → API أو الإعدادات → API keys وابعتُه كـ Authorization: Bearer <your key>. الـ key بيبقى تابع لـ workspace واحدة وبيكون عنده full owner access ليها، فاعتبره زي password.

آمن مع الإعادة: header الـ Idempotency-Key

أحيانًا الـ request بتوصل لكن الرد بيضيع في الرجوع. لو السيستم بتاعك مش متأكد إن الطلب اشتغل، يقدر يبعتُه تاني بنفس Idempotency-Key header. خلال 24 ساعة Entagl بيتعرف على الـ key، بيتخطى الشغل، ويرجع أول answer، فمش هتطلع لك orderين أو contactين. استخدام نفس الـ key لـ request مختلفة بيترفض بخطأ.

قد إيه request تقدر تبعت

لحد 120 request في الدقيقة لكل workspace. لو زودت عن كده، Entagl بيرد بـ error 429 (rate_limited). استنى شوية وجرّب تاني. أغلب الـ automations عمرها ما بتقرب من الحد ده.

مرجع الـ API الكامل

كل endpoint، field، و error code موجودين في Entagl API reference. لو مطورك معهوش لسه، ابعت email إلى support@entagl.com واطلب API reference.

API key بيدي full owner access للـ workspace بتاعه. خليه على السيرفر بتاعك، ومتخزنوش أبدًا جوه website أو app العملاء يقدروا يفتحوه، واعمله revoke أول ما تشك إنه اتسرّب.
التغييرات اللي بتتعمل من خلال الـ API بتتعلّم في webhook events إنها جاية من الـ API، فـ scenario في Make يقدر يتجاهل تغييره هو بدل ما يدخل في loop.

الميزات

الإعداد والمصادقة

أنشئ مفتاح API من Channels → API، فعّل مفتاح القناة، ثم استدعِ الـ API على https://api.entagl.com باستخدام الترويسة Authorization: Bearer <مفتاحك>. المفاتيح مقيدة بمساحة العمل.

إرسال رسالة

ابعت POST /api/v1/messages مع { message, externalUserId }. هتاخد 202 و conversationId فورًا. استخدم نفس conversationId علشان تكمل المحادثة. رد الـ agent هييجي بعدين، مش في الـ response ده.

Webhook (callback) (موصى به)

أضِف عنوان callback عام بـ HTTPS وسيقوم Entagl بإرسال كل رد للوكيل إليه عبر POST، موقّعًا بترويسة X-Entagl-Signature (HMAC-SHA256). تحقّق من التوقيع وردّ بـ 2xx خلال نحو 5 ثوانٍ. لا توجد إعادة محاولة تلقائية.

الاستقصاء (Polling)

إذا لم تستطع استضافة عنوان callback، استدعِ GET /api/v1/conversations/:id/messages?since=<cursor> لجلب الردود الجديدة. مرّر قيمة cursor من كل استجابة كـ ?since= حتى تستقبل الرسائل الجديدة فقط.

الأمان والعزل

API keys بتتخزن بشكل hashed، و signing secret بيتشفّر (الاتنين بيظهروا مرة واحدة بس). وكل lookup مربوط بـ workspace: أي conversation ID من workspace تاني بيرجع 404، ومش ينفع تبعت user ID (لأنه بيتستنتج من الـ key).

مهام شائعة

إعداد قناة API

حوالي 3 دقيقة
  1. روح إلى Channels → API واضغط Generate API Key. انسخه دلوقتي، لأنه بيظهر مرة واحدة بس.
  2. شغّل مفتاح القناة في رأس بطاقة API.
  3. موصى به: وسّع البطاقة، الصق عنوان callback عام بـ HTTPS، احفظ، وانسخ مفتاح التوقيع.
  4. من تطبيقك، أرسل الرسائل عبر POST إلى https://api.entagl.com/api/v1/messages واستقبل الردود عبر callback أو الاستقصاء.

نصائح

الردود بتكون asynchronous. الـ POST بيرجع 202، ورد الـ agent بييجي عن طريق الـ callback أو polling، مش في الـ response.
قد تُنتج رسالة واحدة عدة ردود بعد تأخير تجميع قصير (نحو 8 ثوانٍ، قابل للضبط حتى ~5 دقائق). اعرضها كلها بالترتيب.
الـ 202 مش معناه إن الرد هييجي أكيد. ممكن الـ agent يسكت لو automation متوقفة، أو guardrail منعت الرسالة، أو الـ workspace خلص credits.
لا توجد إعادة محاولة تلقائية في الـ callbacks. احتفظ بالاستقصاء كنسخة احتياطية، وتحقّق دائمًا من ترويسة X-Entagl-Signature قبل الوثوق بأي تسليم.
أعد استخدام conversationId لمتابعة محادثة؛ أما externalUserId فهو مجرد تسمية خاصة بك للمستخدم النهائي.
Text بس في الوقت الحالي. حافظ على API key و signing secret بتوعك: الاتنين بيظهروا مرة واحدة بس.

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

هل الصفحة دي مفيدة؟