الوصول إلى واجهة برمجة التطبيقات (API) #

واجهة برمجة التطبيقات (API) هي وسيلة تتيح لأنظمة البرمجيات المختلفة التواصل مع بعضها البعض. تتيح لك واجهة برمجة تطبيقات Your AI Connector (أو لمطورك) إنشاء جهات اتصال، وإرسال رسائل، وإدارة قوائم، واستقبال رسائل واردة من قنوات مخصصة تلقائياً — كل ذلك دون الحاجة لاستخدام لوحة التحكم.

لماذا تستخدم واجهة برمجة التطبيقات (API)؟ إذا كنت ترغب في ربط التطبيق بأداة لا تحتوي على تكامل مدمج، أو كنت بحاجة إلى أتمتة المهام المتكررة على نطاق واسع، فإن واجهة برمجة التطبيقات هي الطريقة المثلى للقيام بذلك.

إنشاء مفتاح واجهة برمجة التطبيقات (API Key) الخاص بك #

1. في الشريط الجانبي الأيسر، انقر على الإعدادات (أيقونة الترس).
2. في الشريط الجانبي للإعدادات، ضمن مجموعة التكاملات (Integrations)، انقر على مفتاح واجهة برمجة التطبيقات (API Key).

3. إذا لم يكن لديك مفتاح بعد، انقر على Generate API key.
4. إذا كان لديك مفتاح بالفعل، فسيظهر مخفياً تحت Your key. إذا كان مفتاحك يدعم ذلك، انقر على Show لإظهاره، ثم Copy لنسخه — ستظهر لك رسالة تأكيد.
5. احفظ المفتاح في مكان آمن — ستحتاج إليه في كل طلب API.

أعضاء الفريق: ينتمي مفتاح واجهة برمجة التطبيقات (API key) إلى مالك الحساب، لذا إذا قمت بتسجيل الدخول كعضو فريق مدعو (بما في ذلك المسؤول)، فسيظهر القسم ملاحظة بدلاً من المفتاح. قم بتسجيل الدخول كمالك للحساب لعرضه أو نسخه أو إعادة إنشائه — وينطبق ذلك أيضاً على المفاتيح ذات النطاق المحدد.

أين تجده: مفتاح واجهة برمجة التطبيقات (API Key) هو قسم خاص به ضمن الإعدادات ← التكاملات، منفصل عن خطافات الويب (Webhooks). إذا أخبرك دليل أو زميل بالبحث عن المفتاح ضمن “خطافات الويب”، فابحث في القسم المجاور بدلاً من ذلك.

المفاتيح ذات النطاق المحدود: مفاتيح إضافية لمهمة واحدة #

يمكن لمفتاحك الرئيسي القيام بكل شيء، لذا فهو ليس المفتاح المناسب لتقديمه لتقرير، أو لوحة تحكم عميل، أو إعداد منفصل لبيئة الاختبار والتطوير. لهذا الغرض، قم بإنشاء مفاتيح ذات نطاق محدود في بطاقة المفاتيح ذات النطاق المحدود (Scoped keys)، في نفس قسم مفتاح API أسفل مفتاحك:

1. انقر على مفتاح جديد.
2. امنحه اسماً يمكنك التعرف عليه لاحقاً، على سبيل المثال “Sandbox” أو “لوحة تحكم عميل Acme”.
3. ضمن ما يمكنه رؤيته، حدد فقط المناطق التي يحتاجها.
4. ضمن ما يمكنه فعله، اترك خيار للقراءة فقط مفعلاً ما لم تكن الأداة بحاجة إلى إجراء تغييرات. فالمفتاح الذي يمكنه إجراء تغييرات يمكنه إرسال رسائل وتعديل إعداداتك.
5. يمكنك اختيارياً تعيين الطلبات في الدقيقة (حد خاص به، حتى لا يبطئ عمليات التكامل الأخرى الخاصة بك) وتاريخ انتهاء الصلاحية.
6. انقر على إنشاء مفتاح وانسخه على الفور. يتم عرض المفاتيح ذات النطاق المحدود مرة واحدة فقط؛ إذا فقدت أحدها، فقم بإلغائه وأنشئ مفتاحاً آخر.

يمكنك إنشاء العدد الذي تحتاجه. يوضح كل مفتاح في القائمة متى تم استخدامه آخر مرة، ويؤدي خيار إلغاء المفتاح إلى إيقاف عمله فوراً. إنشاء أو إلغاء مفتاح ذي نطاق محدود لا يؤثر أبداً على مفتاحك الرئيسي. تتوفر الخيارات الكاملة، بما في ذلك المفاتيح المقتصرة على حسابات فرعية محددة، في صفحة مفاتيح API ضمن مرجع API.

عنوان URL الأساسي #

تستخدم جميع طلبات واجهة برمجة التطبيقات عنوان الويب الأساسي التالي:

https://api.youraiconnector.com/v1/

المصادقة #

يجب أن يتضمن كل طلب مفتاح واجهة برمجة التطبيقات الخاص بك حتى تعرف المنصة أنك أنت. الطريقة الأبسط هي إضافته إلى نهاية عنوان الويب:

https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY

يمكنك أيضاً إرسال المفتاح كترويسة طلب (request header) بدلاً من وضعه في رابط URL (يُنصح بهذا في بيئة الإنتاج، حتى لا يظهر المفتاح في سجلات الخادم):

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

يجب أن تستخدم جميع الطلبات اتصالاً آمناً (HTTPS). يتم رفض الطلبات غير الآمنة (HTTP).

هل تبحث عن أدلة المطورين الكاملة؟ هذه الصفحة عبارة عن مقدمة سريعة تغطي العمليات الأكثر شيوعاً. للحصول على أدلة كاملة خطوة بخطوة — لكل مورد، مع أمثلة بـ cURL و JavaScript و Python — راجع بدء استخدام API و مرجع API.

عمليات واجهة برمجة التطبيقات الشائعة #

إنشاء جهة اتصال #

الطلب:

POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}

الحقول المطلوبة: phoneNumber (مع رمز البلد) مطلوب دائماً لإنشاء جهة اتصال. عنوان البريد الإلكتروني وحده لا يكفي — سيتم رفض أي طلب بدون رقم هاتف صالح. البريد الإلكتروني اختياري.

الاستجابة:

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}

احفظ data.contactId — ستحتاج إليه لطلب “إضافة جهة اتصال إلى قائمة”.

إضافة جهة اتصال إلى قائمة #

POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}

يمكنك العثور على معرف القائمة (ID) في التطبيق ضمن جهات الاتصال ← القوائم، من قائمة صف القائمة (نسخ معرف القائمة).

تحديث جهة اتصال #

PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}

يتم تغيير الحقول التي تدرجها فقط. هذه هي الطريقة أيضاً لتحميل قيم الحقول المخصصة بشكل مجمع بعد الاستيراد — راجع الحقول المخصصة، ملف تعريف العميل والملاحظات. التفاصيل الكاملة موجودة في API جهات الاتصال.

إرسال رسالة (قناة مخصصة) #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}

تلقي الرسائل الواردة (قناة مخصصة) #

استقبل الرسائل من أنظمة خارجية كقناة مخصصة. هذه هي الطريقة التي ترسل بها عمليات التكامل مثل GoHighLevel الرسائل إلى Your AI Connector. راجع القنوات المخصصة للحصول على التفاصيل الكاملة.

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}

نظرة عامة على العمليات المتاحة #

تحديد معدل الطلبات #

تفرض واجهة برمجة التطبيقات (API) حدوداً للمعدل لضمان استقرار المنصة. تجاوز الحد الخاص بك يؤدي إلى إرجاع 429 Too Many Requests — توقف عن الإرسال وحاول مجدداً بعد الوقت المشار إليه في ترويسات الاستجابة. لحالات الاستخدام ذات الحجم الكبير (عمليات الاستيراد المجمعة)، استخدم ميزة الاستيراد المدمجة أو أرسل بريداً إلكترونياً إلى hi@youraiconnector.com للحصول على التوجيه.

أفضل الممارسات #

• احفظ مفتاح واجهة برمجة التطبيقات (API) الخاص بك بشكل آمن — استخدم مدير كلمات مرور أو إعدادات من جانب الخادم، ولا تضعه أبداً في كود من جانب العميل يمكن لزائر المتصفح قراءته.
• قم دائماً بتضمين رمز الدولة في أرقام الهواتف (+1 للولايات المتحدة، +44 للمملكة المتحدة، +31 لهولندا).
• تعامل مع الأخطاء بلباقة — تحقق من رموز الحالة واقرأ أي رسائل خطأ يتم إرجاعها.
• تعامل مع التكرارات — يؤدي تكرار رقم الهاتف إلى إرجاع { "success": false, "error_code": 409 } بدلاً من جهة اتصال جديدة، مع وجود معرف جهة الاتصال الموجودة في contactId.
• اختبر باستخدام مجموعة بيانات صغيرة قبل إجراء عمليات مجمعة.

استجابات الخطأ #

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}

الخطوات التالية #

• خطافات الويب (Webhooks) — تلقي إشعارات في الوقت الفعلي من التطبيق (قسم منفصل عن مفتاح واجهة برمجة التطبيقات الخاص بك).
• ربط مساعدي الذكاء الاصطناعي (MCP) — استخدم نفس مفتاح واجهة برمجة التطبيقات للسماح لـ Claude بإدارة حسابك.
• نماذج عملاء فيسبوك — استخدم واجهة برمجة التطبيقات مع منصات الأتمتة لجذب العملاء المحتملين.
• تكامل GoHighLevel — مثال كامل لتكامل واجهة برمجة التطبيقات ثنائي الاتجاه.