تصفّح الأقسام

مرجع الـ API

أهم نقاط الـ API التي تحتاجها أنظمتك، مع الترقيم والأخطاء ومثال curl جاهز لكل منها.

في هذا المقال

تجمع هذه الصفحة النقاط التي يحتاجها أغلب الربط البرمجي. كل مسار هنا يبدأ بـ https://app.hadir.chat/api/v1/accounts/{account_id}، وكل طلب يرسل رمزك في الترويسة api_access_token. لتعرف الاثنين راجع رمز الوصول وعنوان الـ API. الأمثلة تضبطهما مرة واحدة:

BASE="https://app.hadir.chat/api/v1/accounts/acc_7Hk2mPq9RtWx"
TOKEN="YOUR_ACCESS_TOKEN"

الأساسيات

  • المعرّفات: المحادثة تُطلب بالرقم الذي يظهر في صندوق الوارد (#123)، لا بمعرّف داخلي. جهات الاتصال والوسوم والفرق والموظفون والقنوات تُطلب بقيمة id التي تأتي في القوائم.
  • الصفحات: جهات الاتصال تأتي 15 في الصفحة، والمحادثات 25 في الصفحة؛ أرسل ?page=2 وهكذا. رسائل المحادثة تأتي 20 رسالة، الأحدث في الأخير؛ أرسل ?before= مع معرّف أقدم رسالة عندك لتصلك العشرون التي قبلها.
  • الصلاحيات: الطلب يعمل باسم صاحب الرمز. إنشاء الوسوم والفرق والموظفين والقنوات والسمات المخصّصة والـ Webhooks أو تعديلها يحتاج دور المدير.

الأخطاء

  • 401: الرمز خطأ، أو لست عضواً في هذه المساحة، أو دورك لا يسمح بالإجراء. المحتوى: {"error": "…"}.
  • 402: الباقة لا تشمل الميزة، أو وصلت إلى حدّ الباقة. فيه error_code بقيمة feature_not_in_plan أو limit_reached.
  • 404: {"error": "Resource could not be found"}.
  • 422: بيانات غير صحيحة. المحتوى: {"message": "…", "attributes": [...]} أو {"error": "…"}.
  • 429: طلبات كثيرة. انتظر عدد الثواني في الترويسة Retry-After ثم أعد المحاولة.

جهات الاتصال

# القائمة والبحث والعرض
curl "$BASE/contacts?page=1" -H "api_access_token: $TOKEN"
curl "$BASE/contacts/search?q=0500000000" -H "api_access_token: $TOKEN"
curl "$BASE/contacts/42" -H "api_access_token: $TOKEN"

# الإنشاء (والتعديل PATCH /contacts/42 بالحقول نفسها)
curl -X POST "$BASE/contacts" -H "api_access_token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sara", "phone_number": "+966500000000", "email": "[email protected]",
       "identifier": "cust-1001", "custom_attributes": {"city": "Riyadh"}}'

محادثات جهة الاتصال: GET /contacts/42/conversations. وسومها: GET أو POST /contacts/42/labels مع {"labels": [...]}.

المحادثات

# القائمة: status = open | resolved | pending | snoozed | all
#          assignee_type = me | assigned | unassigned | all
curl "$BASE/conversations?status=open&assignee_type=all&page=1" -H "api_access_token: $TOKEN"
curl "$BASE/conversations/123" -H "api_access_token: $TOKEN"

# تغيير الحالة
curl -X POST "$BASE/conversations/123/toggle_status" -H "api_access_token: $TOKEN" \
  -H "Content-Type: application/json" -d '{"status": "resolved"}'

# الإسناد إلى موظف (أو {"team_id": 3} لفريق)
curl -X POST "$BASE/conversations/123/assignments" -H "api_access_token: $TOKEN" \
  -H "Content-Type: application/json" -d '{"assignee_id": 7}'

لبدء محادثة: POST /conversations مع inbox_id وcontact_id، واختيارياً "message": {"content": "…"}. على واتساب، العميل الذي لم يكتب خلال آخر 24 ساعة لا تصله إلا رسالة بقالب معتمد؛ راجع قوالب واتساب.

الرسائل

curl "$BASE/conversations/123/messages" -H "api_access_token: $TOKEN"

# الرد على العميل
curl -X POST "$BASE/conversations/123/messages" -H "api_access_token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "تم شحن طلبك.", "message_type": "outgoing", "private": false}'

أرسل "private": true لملاحظة خاصة لا يراها العميل أبداً.

الوسوم

curl "$BASE/labels" -H "api_access_token: $TOKEN"
curl -X POST "$BASE/labels" -H "api_access_token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"label": {"title": "vip", "description": "Top customers", "color": "#087D77", "show_on_sidebar": true}}'

# ضبط وسوم المحادثة (تستبدل القائمة كاملة)
curl -X POST "$BASE/conversations/123/labels" -H "api_access_token: $TOKEN" \
  -H "Content-Type: application/json" -d '{"labels": ["vip", "order"]}'

القنوات والفرق والموظفون

curl "$BASE/inboxes" -H "api_access_token: $TOKEN"
curl "$BASE/teams" -H "api_access_token: $TOKEN"
curl "$BASE/agents" -H "api_access_token: $TOKEN"

curl -X POST "$BASE/teams" -H "api_access_token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"team": {"name": "Sales", "description": "Pre-sales questions", "allow_auto_assign": true}}'
curl -X POST "$BASE/agents" -H "api_access_token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"agent": {"name": "Khalid", "email": "[email protected]", "role": "agent"}}'

أعضاء الفريق: GET /teams/3/team_members، وPOST مع {"user_ids": [7, 8]} للإضافة. إضافة موظف فوق حدّ باقتك ترجع 402.

الردود الجاهزة

curl "$BASE/canned_responses" -H "api_access_token: $TOKEN"
curl -X POST "$BASE/canned_responses" -H "api_access_token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"canned_response": {"short_code": "hours", "content": "نستقبلكم من 9 صباحاً إلى 11 مساءً."}}'

السمات المخصّصة

curl "$BASE/custom_attribute_definitions?attribute_model=contact_attribute" -H "api_access_token: $TOKEN"
curl -X POST "$BASE/custom_attribute_definitions" -H "api_access_token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"custom_attribute_definition": {"attribute_display_name": "City", "attribute_key": "city",
       "attribute_display_type": "text", "attribute_model": "contact_attribute"}}'

قيمة attribute_model: contact_attribute أو conversation_attribute. وقيمة attribute_display_type واحدة من: text وnumber وcurrency وpercent وlink وdate وlist وcheckbox. التفاصيل في السمات المخصّصة.

الـ Webhooks

curl "$BASE/webhooks" -H "api_access_token: $TOKEN"
curl -X POST "$BASE/webhooks" -H "api_access_token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"webhook": {"name": "Orders system", "url": "https://example.com/hadir/events",
       "subscriptions": ["conversation_created", "message_created"]}}'

الرد يحمل secret الخاص بالـ Webhook للتحقّق من التواقيع. للتعديل PATCH /webhooks/5، وللحذف DELETE /webhooks/5. الأحداث وشكل البيانات في الـ Webhooks.

ملاحظة: كل تغيير عبر الـ API حقيقي وفوري، والرسائل تصل إلى العميل فعلاً. جرّب أولاً على رقمك أو على جهة اتصال للتجربة.

هل أفادك المقال؟

شكراً لملاحظتك ✓

لا تكتب بيانات شخصية

وصلتنا ملاحظتك، وسنراجع المقال على ضوئها.

لمعرفة كيف يستخدم هذا الموقع ملفات تعريف الارتباط، راجع سياسة الخصوصية