قائمة العملاء عبر API بالطلب GET /api/v1/contacts

قائمة العملاء عبر API يعيدها الطلب GET /api/v1/contacts: عملاء نشاطك من واتساب وماسنجر وإنستغرام، ومن أضافهم فريقك، الأحدث أولًا، 50 عميلًا في الصفحة. يحتاج الطلب إلى مفتاح بصلاحية contacts.read.

ما الذي يعيده طلب قائمة العملاء؟

يعيد الطلب صفحة من العملاء في data، مرتّبة من الأحدث ظهورًا إلى الأقدم، ومعها nextCursor للصفحة التالية، أو null إذا كانت هذه آخر صفحة. يقرأ المفتاح عملاء نشاطه فقط.

ما المعاملات التي يقبلها الطلب؟

كل المعاملات اختيارية، وأي معامل غيرها يعود بالخطأ 400:

المعامل	النوع	الافتراضي	معناه
limit	عدد صحيح	50	عدد العملاء في الصفحة، حتى 100
cursor	نص		nextCursor من الصفحة السابقة. انظر التقسيم إلى صفحات
since	لحظة بصيغة ISO		العملاء الذين ظهروا أول مرة في هذه اللحظة أو بعدها

يحتاج since إلى تاريخ ووقت معًا، بحرف Z أو بفرق توقيت، مثل 2026-10-01T00:00:00Z. التاريخ وحده يُرفض. وإذا كتبت فرق توقيت بعلامة + في الرابط بنفسك فاكتبها %2B، لأن + في الرابط تُقرأ مسافة.

كيف أرسل الطلب؟

curl "https://api.mujib.ai/api/v1/contacts?limit=50&since=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $MUJIB_API_KEY"

const url = new URL('https://api.mujib.ai/api/v1/contacts');
url.searchParams.set('limit', '50');
url.searchParams.set('since', '2026-10-01T00:00:00Z');

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.MUJIB_API_KEY}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
console.log(body.data.length, body.nextCursor);

import os
import requests

res = requests.get(
    "https://api.mujib.ai/api/v1/contacts",
    params={"limit": 50, "since": "2026-10-01T00:00:00Z"},
    headers={"Authorization": f"Bearer {os.environ['MUJIB_API_KEY']}"},
    timeout=30,
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {body['error']['code']}: {body['error']['message']}")
print(len(body["data"]), body["nextCursor"])

لقراءة كل الصفحات حتى النهاية، استخدم الدالة في التقسيم إلى صفحات.

كيف يبدو الرد؟

رد ناجح بالرمز 200. البيانات هنا مثال مختلَق:

{
  "data": [
    {
      "id": "5d8f2a61-0c4e-4b7a-9f13-6e2b8c0d4a57",
      "name": "سارة",
      "phone": "962790000000",
      "channel": "whatsapp",
      "stage": "qualified",
      "tags": ["استشارة"],
      "createdAt": "2026-11-02T09:14:37.205Z",
      "lastActiveAt": "2026-11-03T16:40:02.918Z"
    },
    {
      "id": "9b1e3c74-2a5d-4f08-8e6b-1c7d0a3f5e92",
      "name": null,
      "phone": null,
      "channel": "instagram",
      "stage": "new",
      "tags": [],
      "createdAt": "2026-10-28T14:05:12.481Z",
      "lastActiveAt": "2026-10-28T14:07:55.030Z"
    }
  ],
  "nextCursor": "MjAyNi0xMC0yOFQxNDowNToxMi40ODFafDliMWUzYzc0LTJhNWQtNGYwOC04ZTZiLTFjN2QwYTNmNWU5Mg"
}

كل عميل فيه هذه الحقول دائمًا، والحقل الذي لا قيمة له يأتي null ولا يُحذف:

الحقل	النوع	معناه
id	نص	معرّف العميل الثابت، تستخدمه في قراءة عميل واحد
name	نص أو null	اسم العميل، أو null إذا لم يُعرف
phone	نص أو null	الرقم كما هو محفوظ، وغالبًا بالصيغة الدولية دون + مثل 962790000000، أو null إذا لم يُعرف
channel	نص	من أين جاء العميل (انظر الجدول التالي)
stage	نص	مرحلة العميل (انظر الجدول التالي)
tags	قائمة نصوص	وسوم العميل، وقائمة فارغة إذا لم تكن له وسوم
createdAt	لحظة UTC	أول مرة ظهر فيها العميل
lastActiveAt	لحظة UTC	آخر نشاط للعميل

قيم channel:

القيمة	معناها
whatsapp	راسلك على واتساب
facebook	راسلك على ماسنجر
instagram	راسلك على إنستغرام
manual	أضافه فريقك من لوحة التحكم
import	استُورد من ملف

قيم stage، وما يقابلها في لوحة التحكم:

القيمة	في لوحة التحكم
new	«جديد»
engaged	«متفاعل»
qualified	«مؤهّل»
won	«كسب»
lost	«خسارة»

ما الأخطاء المحتملة؟

HTTP	code	السبب
400	VALIDATION_ERROR	معامل غير معروف، أو limit خارج المسموح، أو since ليس لحظة صحيحة، أو مؤشر لا يُقرأ
401	UNAUTHORIZED	لا مفتاح، أو مفتاح غير صالح
403	FORBIDDEN	المفتاح لا يحمل contacts.read
429	RATE_LIMITED	تجاوزت حدود الطلبات
500	INTERNAL	خطأ غير متوقع في الخادم

التفاصيل وما تفعله عند كل خطأ في الأخطاء وحدود الطلبات.

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

هل تشمل القائمة العملاء من ماسنجر وإنستغرام؟

نعم. تشمل عملاء واتساب وماسنجر وإنستغرام، ومن أضافهم فريقك يدويًا، ومن استوردتهم من ملف. الحقل channel يقول من أين جاء كل عميل.

لماذا يأتي phone فارغًا لبعض العملاء؟

لأن مُجيب لا يأخذ رقم هاتف مع رسائل ماسنجر وإنستغرام. يظهر الرقم إذا ذكره العميل في المحادثة أو أضافه فريقك.

هل أستطيع البحث باسم أو رقم؟

لا. القائمة تقبل limit وcursor وsince فقط، وأي معامل آخر يعود بالخطأ 400.

هل تخرج ملاحظات فريقي عن العميل؟

لا. ملاحظات الفريق والحقول المخصّصة وما يتذكّره الوكيل لا تخرج من الواجهة.

صفحات ذات صلة

• قراءة عميل واحد بمعرّفه، الطلب GET /api/v1/contacts/{id}
• التقسيم إلى صفحات في واجهة مُجيب بالمؤشر nextCursor
• مفتاح API في مُجيب، إنشاؤه وإرساله وإلغاؤه
• العملاء المحتملين في مُجيب، تقييمهم ومراحلهم ومتابعتهم