واجهة برمجة تطبيقات جهات الاتصال #

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

جميع المسارات في هذه الصفحة نسبية إلى عنوان URL الأساسي:

https://api.youraiconnector.com/v1

لذا فإن /contacts تعني https://api.youraiconnector.com/v1/contacts.

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

حول معرفات جهات الاتصال #

لكل جهة اتصال معرف فريد. المعرف الذي تحصل عليه عند إنشاء جهة اتصال (في data.contactId) هو نفس المعرف الذي تستخدمه في أي مكان آخر — لجلب جهة الاتصال هذه، أو تحديثها، أو إضافة وسم لها، أو إرسال رسالة إليها، أو حذفها. احفظه مرة واحدة وأعد استخدامه.

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

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

POST /contacts

يضيف جهة اتصال جديدة إلى حسابك. رقم الهاتف مع رمز الدولة مطلوب — البريد الإلكتروني وحده لا يكفي. كل شيء آخر اختياري.

يمكنك اختيارياً إضافة جهة الاتصال الجديدة مباشرة إلى قائمة واحدة أو أكثر باستخدام listId (قائمة واحدة) أو listIds (مصفوفة). إذا تم إرسال كليهما، فإن listIds هي التي يتم اعتمادها.

أي حقل ترسله ولا يعد من حقول الإنشاء القياسية المدرجة في جدول حقول إنشاء جهة اتصال أدناه (phoneNumber، firstName، lastName، email، channel، is_bot_active، is_private، lead_profile، listId، listIds، custom_fields) يتم تخزينه تلقائياً كـ حقل مخصص — لذا فإن الحمولة المسطحة (flat payload) من أداة مثل Make أو Zapier تعمل دون الحاجة إلى تداخل (nesting). يمكنك أيضاً تمرير كائن custom_fields صريح.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+15551234567",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "is_bot_active": true,
    "listIds": ["list123", "list456"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+15551234567",
    firstName: "Jane",
    lastName: "Smith",
    email: "jane@example.com",
    is_bot_active: true,
    listIds: ["list123", "list456"],
  }),
});
const data = await res.json();
console.log(data.data.contactId);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+15551234567",
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "jane@example.com",
        "is_bot_active": True,
        "listIds": ["list123", "list456"],
    },
)
print(res.json()["data"]["contactId"])

الاستجابة

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

معرّف جهة الاتصال الجديدة موجود في data.contactId. القوائم التي تمت إضافتها إليها تظهر في data.listsAdded.

لا يتم إنشاء نسخ مكررة. إذا كانت جهة الاتصال التي تحمل نفس رقم الهاتف موجودة بالفعل، فإن طلب الإنشاء لا يقوم بإنشائها أو إرجاعها. يتم إرجاع الاستجابة بحالة HTTP 200 و error_code بقيمة 409 في النص البرمجي، لذا قم بالتفرع بناءً على error_code بدلاً من حالة HTTP:

{ "success": false, "error_code": 409, "error": "A contact with this phone number already exists for the current user." }

للتعامل مع جهة اتصال موجودة بعد الحصول على error_code بقيمة 409، ابحث عنها باستخدام الحصول على جهة اتصال عن طريق الهاتف أو البريد الإلكتروني — GET /contacts?phoneNumber=... — وأعد استخدام المعرف (ID) الذي يتم إرجاعه.

تُحتسب طرق كتابة WhatsApp المتكافئة كرقم واحد. تحتوي بعض البلدان على طريقتين صحيحتين لكتابة نفس رقم الهاتف المحمول، وقد يبلغ WhatsApp عن أي منهما: المكسيك (+52… والطريقة القديمة +521…)، والبرازيل (مع أو بدون الرقم التاسع)، والأرجنتين (مع أو بدون 9 بعد +54). يتطابق فحص التكرار عند الإنشاء وGET /contacts?phoneNumber= عبر كلتا طريقتي الكتابة، لذا ستحصل على جهة الاتصال الموجودة بغض النظر عن الصيغة التي ترسلها. لا يتم أبداً إعادة كتابة phone_number المخزن في جهة الاتصال.

الحصول على جهة اتصال عن طريق الهاتف أو البريد الإلكتروني #

GET /contacts?phoneNumber=... أو GET /contacts?email=...

يبحث عن جهة اتصال واحدة ويعيد كائن جهة الاتصال الكامل والمُثرى — بما في ذلك قوائمها، وعلاماتها، وحملاتها التي تم حلها إلى أزواج { id, name }، بالإضافة إلى آخر رسالة تم تبادلها.

مرر إما phoneNumber (بالتنسيق الدولي) أو email. إذا لم تمرر أياً منهما، فسيتحول هذا المسار نفسه إلى وضع سرد جهات الاتصال بدلاً من ذلك.

cURL

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?phoneNumber=%2B15551234567&apiKey=YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551234567");
const res = await fetch(`https://api.youraiconnector.com/v1/contacts?phoneNumber=${phone}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.contact);

Python

import requests

res = requests.get(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"phoneNumber": "+15551234567"},
)
print(res.json()["contact"])

الاستجابة

{
  "success": true,
  "contactId": "contact_abc123",
  "contact": {
    "id": "contact_abc123",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phoneNumber": "+15551234567",
    "channel": "whatsapp",
    "isBotActive": true,
    "isPrivate": false,
    "doNotDisturb": false,
    "lead_profile": null,
    "avatarUrl": "https://example.com/photo.jpg",
    "customFields": {},
    "lists": [{ "id": "list123", "name": "VIP customers" }],
    "tags": [{ "id": "tagHotLead", "name": "Hot lead" }],
    "campaigns": [{ "id": "campaign789", "name": "Spring promo" }],
    "currentCampaign": { "id": "campaign789", "name": "Spring promo" },
    "lastMessage": {
      "direction": "inbound",
      "body": "Sounds good, thanks!",
      "status": "received",
      "timestamp": "2026-06-09T10:21:00.000Z"
    }
  }
}

يتم إرجاع معرّف جهة الاتصال في المستوى الأعلى (contactId) وداخل الكائن (contact.id). إذا لم يتم العثور على أي تطابق، ستحصل على 404 مع { "success": false, "message": "Contact not found" }.

avatarUrl هي صورة الملف الشخصي لجهة الاتصال، والتي يتم الحصول عليها من WhatsApp أو Meta عندما يرسلون إليك رسالة. هذه الخاصية للقراءة فقط: لا يمكنك تعيينها، وتكون null لجهات الاتصال التي ليس لديها صورة أو التي تتواصل معك عبر قناة لا تشارك الصور. تعامل مع الرابط كعنصر مؤقت بدلاً من تخزينه، حيث أن بعض روابط الصور هذه تنتهي صلاحيتها ويتم تحديثها تلقائياً. (في نقطة نهاية القائمة أدناه، تسمى القيمة نفسها avatar_url.)

أرقام الهواتف في عناوين URL. يجب ترميز علامة + في سلسلة الاستعلام كـ %2B، وإلا فسيتم قراءتها كمسافة. الأمثلة أعلاه تقوم بذلك نيابة عنك.

الحصول على جهة اتصال بواسطة المعرف (ID) #

GET /contacts/{contactId}

عندما يكون لديك بالفعل معرف (ID) لجهة اتصال، يمكنك جلبه مباشرة. شكل الاستجابة مطابق لعملية البحث أعلاه.

cURL

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.contact);

Python

import requests

res = requests.get(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["contact"])

معرف جهة اتصال غير موجود في حسابك يُرجع 404.

الحصول على إحصائيات جهة الاتصال #

GET /contacts/{contactId}/stats

إرجاع إحصائيات الرسائل المجمعة لجهة اتصال واحدة: الإجماليات، والردود بواسطة الذكاء الاصطناعي مقابل الردود البشرية، والرصيد المستهلك، والطوابع الزمنية لأول وآخر رسالة.

cURL

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/stats?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/stats", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.totalMessages, data.creditsUsed);

Python

import requests

res = requests.get(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/stats",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["totalMessages"], data["creditsUsed"])

الاستجابة

{
  "success": true,
  "totalMessages": 48,
  "sent": 21,
  "received": 27,
  "aiReplies": 18,
  "humanReplies": 3,
  "creditsUsed": 34,
  "botMessageCount": 18,
  "firstMessageAt": "2026-05-01T09:00:00.000Z",
  "lastMessageAt": "2026-06-09T10:21:00.000Z"
}

botMessageCount هو نفس عداد رسائل الذكاء الاصطناعي الذي يقوم زر “إعادة التعيين” داخل التطبيق لجهة الاتصال بتصفيره. creditsUsed هو إجمالي الرصيد الجاري لجهة الاتصال هذه، وليس فقط أرقام هذا الرد. معرف جهة اتصال غير موجود في حسابك يُرجع 404.

سرد جهات الاتصال #

GET /contacts

استدعِ GET /contacts بدون phoneNumber أو email للتنقل عبر جميع جهات الاتصال الخاصة بك، بدءاً بالأحدث. تُرجع كل صفحة ملخصات مدمجة لجهات الاتصال (تظهر القوائم، والوسوم، والحملات كمصفوفات معرفات بدلاً من كائنات كاملة) و next_cursor.

للتنقل عبر كل صفحة: قم بإجراء الاستدعاء الأول بدون مؤشر (cursor)، ثم استمر في تمرير next_cursor المُرجع كـ cursor. توقف عندما تكون قيمة next_cursor هي null — فهذا يعني عدم وجود المزيد من النتائج.

cURL

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?limit=50&apiKey=YOUR_API_KEY"

# next page:
curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?limit=50&cursor=contact_abc123&apiKey=YOUR_API_KEY"

JavaScript

async function listAllContacts() {
  const all = [];
  let cursor = null;
  do {
    const url = new URL("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);
    const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
    const data = await res.json();
    all.push(...data.contacts);
    cursor = data.next_cursor;
  } while (cursor);
  return all;
}

Python

import requests

def list_all_contacts():
    all_contacts = []
    cursor = None
    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor
        res = requests.get(
            "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts",
            headers={"X-API-Key": "YOUR_API_KEY"},
            params=params,
        )
        data = res.json()
        all_contacts.extend(data["contacts"])
        cursor = data["next_cursor"]
        if not cursor:
            break
    return all_contacts

الاستجابة

{
  "success": true,
  "contacts": [
    {
      "id": "contact_abc123",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "phone_number": "+15551234567",
      "channel": "whatsapp",
      "is_bot_active": true,
      "is_private": false,
      "do_not_disturb": false,
      "avatar_url": "https://example.com/photo.jpg",
      "custom_fields": {},
      "created_at": "2026-06-01T09:00:00.000Z",
      "list_ids": ["list123"],
      "tag_ids": ["tagHotLead"],
      "campaign_ids": ["campaign789"],
      "current_campaign_id": "campaign789"
    }
  ],
  "next_cursor": "contact_abc123"
}

عدّ جهات الاتصال #

GET /contacts/count

يعيد عدد جهات الاتصال التي تطابق عامل تصفية معين، بالإضافة إلى تقسيم حسب القناة، دون الحاجة إلى التصفح عبر الصفحات. هذا هو الاستدعاء المناسب لأي سؤال يبدأ بـ “كم عدد” — سواء كان ذلك لعنصر في لوحة التحكم، أو لأتمتة، أو لسؤال Champ. جميع عوامل التصفية اختيارية، ويؤدي دمج عدة عوامل إلى تضييق نطاق العد (يجب أن تطابق جهة الاتصال كل عامل تصفية ترسله).

إذا لم ترسل أي عامل تصفية، فستحصل على إجمالي عدد جهات الاتصال في حسابك.

cURL

# everything
curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/count?apiKey=YOUR_API_KEY"

# only the contacts one agent handles on Messenger
curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/count?agentId=agent_xyz789&channel=messenger&apiKey=YOUR_API_KEY"

JavaScript

const url = new URL("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/count");
url.searchParams.set("agentId", "agent_xyz789");
url.searchParams.set("channel", "messenger");

const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const data = await res.json();
console.log(data.total);

Python

import requests

res = requests.get(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/count",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"agentId": "agent_xyz789", "channel": "messenger"},
)
data = res.json()
print(data["total"])

الاستجابة

{
  "success": true,
  "total": 3423,
  "by_channel": { "messenger": 2744, "instagram": 667, "none": 12 },
  "filters": { "agentId": "agent_xyz789" }
}

by_channel يقسم نفس الإجمالي حسب القناة؛ يتم احتساب جهات الاتصال غير الموجودة على أي قناة تحت none. يعيد filters صدى عوامل التصفية التي تم تطبيقها، حتى تتمكن من التحقق من أن الاستدعاء قام بما كنت تقصده.

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

PUT /contacts/{contactId}

يُحدِّث جهة اتصال موجودة. يتم تغيير الحقول التي تدرجها فقط — اترك أي شيء لا ترغب في تعديله. يجب عليك إرسال حقل واحد على الأقل، وإلا ستحصل على 400 (“لا توجد حقول للتحديث”).

cURL

curl -X PUT "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "firstName": "Jane", "do_not_disturb": true }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ firstName: "Jane", do_not_disturb: true }),
});
const data = await res.json();
console.log(data.message);

Python

import requests

res = requests.put(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"firstName": "Jane", "do_not_disturb": True},
)
print(res.json()["message"])

الاستجابة

{
  "success": true,
  "message": "Contact updated successfully"
}

يتم دمج الحقول المخصصة، وليس استبدالها. إرسال { "custom_fields": { "tier": "gold" } } يضبط فقط tier — أي حقول مخصصة أخرى على جهة الاتصال تبقى كما هي تمامًا. لإزالة حقل مخصص تمامًا من جميع جهات الاتصال، استخدم حذف حقل مخصص.

إضافة أو إزالة الوسوم #

POST /contacts/{contactId}/tags

يضيف و/أو يزيل الوسوم من جهة اتصال واحدة في طلب واحد. مرر معرفات الوسوم في addTagIds و removeTagIds. يجب أن يكون واحد منهما على الأقل غير فارغ.

يجب أن تكون الوسوم موجودة بالفعل في حسابك — قم بإنشائها أولاً من خلال نقطة نهاية الوسوم. إذا لم تكن جهة الاتصال أو أي وسم مشار إليه موجودًا، فستحصل على 404.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "addTagIds": ["tagHotLead"], "removeTagIds": ["tagColdLead"] }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/tags", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    addTagIds: ["tagHotLead"],
    removeTagIds: ["tagColdLead"],
  }),
});
const data = await res.json();
console.log(data.added, data.removed);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/tags",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"addTagIds": ["tagHotLead"], "removeTagIds": ["tagColdLead"]},
)
data = res.json()
print(data["added"], data["removed"])

الاستجابة

{
  "success": true,
  "contact_id": "contact_abc123",
  "added": 1,
  "removed": 1
}

إدارة مكتبة الوسوم الخاصة بك #

تدير نقاط النهاية هذه الوسم نفسه — إعادة تسميته أو حذفه من حسابك — على عكس تطبيق وسم أو إزالته من جهة اتصال واحدة (انظر إضافة أو إزالة الوسوم أعلاه). كل وسم في حسابك له معرف (tagId): وهو المعرف المعروض في مدير الوسوم بلوحة التحكم الخاصة بك، والمعرف الذي يتم إرجاعه كـ data.tag_id عند إنشاء وسم باستخدام POST /tags وجسم JSON يحتوي على { "name": "..." } (بدون phoneNumber أو email أو contactId).

تحديث وسم #

PUT /tags/{tagId}

أرسل فقط الحقول التي تقوم بتغييرها.

curl -X PUT "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/tags/tagHotLead?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Hot lead (Q3)" }'

الاستجابة

{ "success": true, "tag_id": "tagHotLead" }

معرف tagId غير موجود في حسابك يُرجع 404.

حذف وسم #

DELETE /tags/{tagId}

يحذف وسماً واحداً حسب المعرف. لا يمكن التراجع عن هذا الإجراء — ستفقد جهات الاتصال التي تحمل الوسم هذا الوسم ببساطة. حذف وسم محذوف بالفعل (أو لم يكن موجوداً من قبل) يُرجع 200 مع deleted: 0 بدلاً من 404، نظراً لعدم وجود شيء ليتم تعداده.

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/tags/tagColdLead?apiKey=YOUR_API_KEY"

الاستجابة

{ "success": true, "deleted": 1 }

حذف عدة وسوم دفعة واحدة #

DELETE /tags

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tagIds": ["tagColdLead", "tagUnsubscribed"] }'

الاستجابة

{ "success": true, "deleted": 2 }

يتم تجاهل المعرفات غير الموجودة أو التي تنتمي إلى حساب آخر بصمت ولا يتم احتسابها ضمن deleted.

تعيين علامة بشكل جماعي #

POST /contacts/bulk-flag

يُعين علامة منطقية واحدة على العديد من جهات الاتصال في وقت واحد. بحد أقصى 500 معرف جهة اتصال لكل طلب. يتم تخطي المعرفات غير الموجودة في حسابك ويتم احتسابها في skipped.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-flag?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["contactId1", "contactId2"],
    "field": "bot_active",
    "value": false
  }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-flag", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contactIds: ["contactId1", "contactId2"],
    field: "bot_active",
    value: false,
  }),
});
const data = await res.json();
console.log(data.updated, data.skipped);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-flag",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contactIds": ["contactId1", "contactId2"],
        "field": "bot_active",
        "value": False,
    },
)
data = res.json()
print(data["updated"], data["skipped"])

الاستجابة

{
  "success": true,
  "updated": 2,
  "skipped": 0
}

استيراد جهات الاتصال بشكل جماعي #

POST /contacts/import

ينشئ ما يصل إلى 500 جهة اتصال في طلب واحد من مصفوفة JSON. يحتاج كل سجل إلى phone_number بالتنسيق الدولي؛ وكل شيء آخر اختياري. يتم تخطي السجلات التي تحتوي على أرقام هواتف غير صالحة أو قنوات غير مدعومة (لا يتم إنشاؤها)، ويتم الإبلاغ عن كل سجل تم تخطيه مع فهرسه وسببه — حتى تتمكن من إصلاح الإخفاقات فقط وإعادة المحاولة.

يتم تخطي أرقام الهواتف الموجودة بالفعل في حسابك كـ duplicate افتراضياً. أرسل updateExisting: true لـ تحديث جهات الاتصال تلك بدلاً من ذلك: الحقول الموجودة في السجل تقوم بالكتابة فوق حقول جهة الاتصال (first_name، وlast_name، وemail، وlead_profile، وcustom_fields يتم دمجها مفتاحاً بمفتاح)، وتتم إضافة tags، كما تتم إضافة جهة الاتصال إلى listId. لا يتم تغيير القناة ورقم الهاتف وعلامات البوت أبداً في جهة اتصال موجودة.

يمكنك اختيارياً إضافة كل جهة اتصال مستوردة (أو محدثة) إلى قائمة باستخدام listId، وتعيين defaultChannel للسجلات التي لا تحدد واحداً، ووسم السجلات بـ tags (أسماء الوسوم — يتم إنشاء الوسوم المفقودة، بينما تتم مطابقة الوسوم الموجودة دون مراعاة حالة الأحرف).

الحقول ذات المستوى الأعلى

حقول كل سجل

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee", "tags": ["vip", "newsletter"] },
      { "phone_number": "+12025551235", "first_name": "Bob" }
    ],
    "listId": "list123",
    "defaultChannel": "whatsapp_web",
    "updateExisting": true
  }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contacts: [
      { phone_number: "+12025551234", first_name: "Ann", last_name: "Lee", tags: ["vip", "newsletter"] },
      { phone_number: "+12025551235", first_name: "Bob" },
    ],
    listId: "list123",
    defaultChannel: "whatsapp_web",
    updateExisting: true,
  }),
});
const data = await res.json();
console.log(`Imported ${data.imported}, updated ${data.updated}, skipped ${data.skipped.length}`);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contacts": [
            {"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee", "tags": ["vip", "newsletter"]},
            {"phone_number": "+12025551235", "first_name": "Bob"},
        ],
        "listId": "list123",
        "defaultChannel": "whatsapp_web",
        "updateExisting": True,
    },
)
data = res.json()
print(f"Imported {data['imported']}, updated {data['updated']}, skipped {len(data['skipped'])}")

الاستجابة

{
  "success": true,
  "imported": 2,
  "contact_ids": ["contact_abc123", "contact_def456"],
  "updated": 0,
  "updated_contact_ids": [],
  "skipped": []
}

إذا تعذر إنشاء بعض السجلات، فإنها تظهر في skipped مع السبب (هنا بدون updateExisting، لذا يتم تخطي الرقم الموجود):

{
  "success": true,
  "imported": 1,
  "contact_ids": ["contact_abc123"],
  "updated": 0,
  "updated_contact_ids": [],
  "skipped": [
    { "index": 1, "phone_number": "+12025551235", "reason": "duplicate" }
  ]
}

مع updateExisting: true، يقوم نفس الطلب بالإبلاغ عن جهة الاتصال الموجودة تحت updated / updated_contact_ids بدلاً من ذلك.

أسباب التخطي المحتملة: invalid_record، missing_phone_number، invalid_phone_number، invalid_channel، duplicate_in_request، duplicate، contact_limit_reached، create_failed.

حدود الخطة. إذا كان حد جهات الاتصال في خطتك لا يسمح بهذا العدد الكبير من جهات الاتصال الجديدة، فسيتم رفض الطلب بالكامل مسبقاً مع 403. إذا تم الوصول إلى الحد في منتصف العملية، فستعود السجلات المتبقية كـ “تم تخطيها” مع السبب contact_limit_reached.

استيراد جهات الاتصال من ملف CSV #

بالنسبة لعمليات الاستيراد الأكبر مما يدعمه الاستيراد المجمع (حتى 50,000 صف تقريبًا)، قم بجدولة مهمة استيراد غير متزامنة لملف CSV موجود بالفعل في مساحة تخزين حسابك، ثم استعلم عن حالتها حتى تكتمل.

بدء الاستيراد #

POST /contacts/import-csv

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import-csv?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "csvStoragePath": "users/abc123/imports/leads.csv",
    "listName": "Webinar signups"
  }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import-csv", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    csvStoragePath: "users/abc123/imports/leads.csv",
    listName: "Webinar signups",
  }),
});
const data = await res.json();
console.log(data.job_id);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import-csv",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "csvStoragePath": "users/abc123/imports/leads.csv",
        "listName": "Webinar signups",
    },
)
job_id = res.json()["job_id"]

الاستجابة (202 — عملية الاستيراد في قائمة الانتظار، ولم تنتهِ بعد)

{
  "success": true,
  "job_id": "csvimp_abc123",
  "status": "queued"
}

نقل الملف إلى مساحة التخزين. تبدأ نقطة النهاية هذه مهمة الاستيراد وتتتبعها؛ وهي لا تقبل الرفع مباشرة. يجب أن يكون ملف CSV موجودًا بالفعل في csvStoragePath قبل استدعائها — حيث يقوم مستورد CSV الخاص بلوحة التحكم بهذه الخطوة كخطوة أولى.

الاستعلام عن حالة مهمة الاستيراد #

GET /contacts/import-csv/{jobId}

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import-csv/csvimp_abc123?apiKey=YOUR_API_KEY"

الاستجابة

{
  "success": true,
  "job_id": "csvimp_abc123",
  "status": "completed",
  "imported": 812,
  "updated": 0,
  "skipped": 14,
  "errors": [],
  "error_message": null
}

تنتقل status عبر queued ← processing ← completed، أو failed مع ذكر السبب في error_message. إذا لم تكن jobId موجودة في حسابك، فسيتم إرجاع 404.

تصدير جهات الاتصال #

تبدأ عملية تصدير غير متزامنة لجهات الاتصال الخاصة بك بصيغة CSV وتُرجع مهمة يمكنك الاستعلام عنها لمعرفة حالة اكتمالها.

بدء التصدير #

POST /contacts/export

ترك كلا الحقلين فارغين سيؤدي إلى تصدير كل جهة اتصال في حسابك.

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/export?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "listId": "list123" }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/export", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ listId: "list123" }),
});
const data = await res.json();
console.log(data.job_id);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/export",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"listId": "list123"},
)
job_id = res.json()["job_id"]

الاستجابة (202 — تم وضع التصدير في قائمة الانتظار)

{
  "success": true,
  "job_id": "export_abc123",
  "status": "queued"
}

استطلاع حالة مهمة التصدير #

GET /contacts/export/{jobId}

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/export/export_abc123?apiKey=YOUR_API_KEY"

الاستجابة

{
  "success": true,
  "job_id": "export_abc123",
  "status": "completed",
  "export_id": "exp_xyz789",
  "contact_count": 812,
  "error_message": null
}

بمجرد أن تصبح status في حالة "completed"، ستحصل على export_id و contact_count. يتم تنزيل ملف CSV الذي تم إنشاؤه من صفحة الصادرات في لوحة التحكم الخاصة بك.

إرسال رسالة إلى جهة اتصال #

POST /contacts/{contactId}/send-message

يرسل رسالة إلى جهة اتصال موجودة عبر القناة التي يستخدمونها حالياً. يتم وضع الرسالة في قائمة الانتظار وإرسالها في الخلفية — يؤكد الرد أنه تم قبول الرسالة، وليس أنه قد تم تسليمها بعد.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/send-message?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Hi! Your appointment is confirmed." }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/send-message", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ body: "Hi! Your appointment is confirmed." }),
});
const data = await res.json();
console.log(data.messageId);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/send-message",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"body": "Hi! Your appointment is confirmed."},
)
print(res.json()["messageId"])

الاستجابة

{
  "success": true,
  "messageId": "aB3dE5fG7hI9jK1lM2nO",
  "contactId": "contact_abc123",
  "channel": "whatsapp",
  "message": "Message created successfully. Delivery is being processed."
}

لا يمكنك الإرسال الآن؟ إذا كانت جهة الاتصال قد فعّلت وضع “عدم الإزعاج” أو الوضع الخاص، أو لم تكن على قناة يمكنها تلقي رسائل صادرة، فسيتم رفض الطلب مع 422 و error توضيحي.

للإرسال عبر رقم الهاتف، أو معرف Instagram، أو أي هوية قناة أخرى بدلاً من معرف جهة الاتصال — ولمزيد من المعلومات حول المراسلة بشكل عام — راجع Messages API.

تعيين وكيل ذكاء اصطناعي لجهة اتصال #

POST /contacts/{contactId}/assign-agent

ينقل محادثة موجودة إلى وكيل ذكاء اصطناعي مختلف، بدءاً من الرسالة التالية فصاعداً. هذا الإجراء هو نفسه تعيين وكيل ذكاء اصطناعي في قائمة المحادثة، وهو نفس الخطوة التي يستخدمها إجراء تعيين وكيل ذكاء اصطناعي أو حملة في الأتمتة (Automations).

كن حذراً مع triggerAIResponse: true — فهو يرسل رسالة إلى جهة الاتصال في تلك اللحظة، لذا استخدمه فقط عندما تريد مراسلتهم الآن. على Messenger وInstagram، تفشل هذه الرسالة إذا كانت آخر مراسلة من جهة الاتصال لك قد تمت قبل أكثر من 24 ساعة.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/assign-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "agent_xyz789" }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/assign-agent", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ agentId: "agent_xyz789" }),
});
const data = await res.json();
console.log(data.data.agentId);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/assign-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"agentId": "agent_xyz789"},
)
print(res.json()["data"]["agentId"])

الاستجابة

{
  "success": true,
  "data": {
    "contactId": "contact_abc123",
    "agentId": "agent_xyz789",
    "aiResponseTriggered": false
  }
}

يجب أن ينتمي الوكيل إلى نفس حساب جهة الاتصال؛ وإلا سيتم رفض الطلب بـ 404 أو 403. يمكنك العثور على معرفات الوكلاء في صفحة وكلاء الذكاء الاصطناعي (ينتهي رابط URL الخاص بكل وكيل بمعرفه).

تعيين وكيل ذكي لجهات اتصال متعددة #

POST /contacts/bulk-assign-agent

ينقل العديد من المحادثات إلى وكيل ذكي مختلف في استدعاء واحد — أو يمسح التعيين للجميع باستخدام null. هذا تغيير في التوجيه فقط: لا يتم إرسال أي رسالة ولا يرد الوكيل على أي شخص. تحصل كل جهة اتصال ببساطة على الوكيل الجديد في المرة التالية التي تراسلك فيها. (لهذا السبب لا يوجد triggerAIResponse هنا.)

أرسل واحداً فقط من contactIds أو filter أو rules.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-assign-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_xyz789",
    "filter": { "agentId": "agent_abc123", "channel": "messenger" }
  }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-assign-agent", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agentId: "agent_xyz789",
    filter: { agentId: "agent_abc123", channel: "messenger" },
  }),
});
const data = await res.json();
console.log(data.updated, data.remaining);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-assign-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "agentId": "agent_xyz789",
        "filter": {"agentId": "agent_abc123", "channel": "messenger"},
    },
)
data = res.json()
print(data["updated"], data["remaining"])

الاستجابة

{
  "success": true,
  "agentId": "agent_xyz789",
  "matched": 3415,
  "updated": 500,
  "skipped": 0,
  "remaining": 2915,
  "filters": { "agentId": "agent_abc123" }
}

matched هو عدد جهات الاتصال التي وجدها الاختيار إجمالاً، وupdated هو عدد جهات الاتصال التي تم نقلها بواسطة هذا الاستدعاء، وskipped هو عدد المعرفات التي أرسلتها ولم يتم العثور عليها في حسابك، وremaining هو عدد جهات الاتصال التي لا تزال تطابق المعايير بعد انتهاء هذا الاستدعاء.

نقل الجميع. نظراً لأن الاستدعاء ينقل 500 جهة اتصال كحد أقصى، فإن المجموعة الكبيرة تتطلب بضعة استدعاءات. استخدم عامل تصفية يتوقف عن مطابقة جهة الاتصال بمجرد نقلها — على سبيل المثال filter: { "agentId": "agent_abc123" } أثناء التعيين إلى agent_xyz789 — وكرر نفس الاستدعاء بالضبط حتى يعود remaining كـ 0. عندما تمرر contactIds بدلاً من ذلك، يكون remaining دائماً 0.

تعيين جهة اتصال إلى قسم #

POST /contacts/{contactId}/department

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

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/department?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "department_id": "dept_sales" }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/department", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ department_id: "dept_sales" }),
});
const data = await res.json();
console.log(data.assigned_to);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/department",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"department_id": "dept_sales"},
)
print(res.json()["assigned_to"])

الاستجابة

{
  "success": true,
  "department_id": "dept_sales",
  "assigned_to": "member_uid_123"
}

assigned_to تكون null عندما تكون جهة الاتصال مملوكة بالفعل لشخص ما، أو إذا قمت بتمرير hand_to_member: false.

ربط جهة اتصال عبر القنوات #

“المتابعة عبر واتساب” (أو الرسائل القصيرة SMS) تعثر على جهة اتصال هذا الشخص أو تنشئها على قناة أخرى تعتمد على الهاتف وتربط الاثنين معاً، بحيث يتعرف عليهما باقي التطبيق كشخص واحد.

رابط بقناة أخرى #

POST /contacts/{contactId}/link-channel

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/link-channel?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "sms" }'

الاستجابة

{
  "success": true,
  "data": {
    "contact_id": "contact_def456",
    "person_id": "person_xyz789",
    "created": true
  }
}

تخبرك created ما إذا تم إنشاء جهة اتصال جديدة للقناة المستهدفة أو إذا تم العثور على جهة اتصال موجودة وربطها. استدعاء هذا للمرة الثانية آمن — فهو يعيد نفس contact_id مع created: false بدلاً من إنشاء نسخة مكررة.

تعني 422 أن الحساب لا يمكنه إجراء هذا الربط في الوقت الحالي: جهة الاتصال موجودة بالفعل في عائلة القناة تلك، أو لا يوجد رقم هاتف لاستخدامه، أو لا يوجد مرسل متصل للقناة المستهدفة. تعني 409 أن جهتي الاتصال مرتبطتان بالفعل بشخصين مختلفين — قم بإلغاء ربط أحدهما أولاً.

سرد المحادثات المرتبطة بجهة اتصال #

GET /contacts/{contactId}/linked

يعيد المحادثات الأخرى التي تعود لنفس الشخص مثل جهة الاتصال هذه. جهة الاتصال غير المرتبطة تعيد مصفوفة فارغة، وليس 404 — فعبارة “هذا الشخص ليس لديه قنوات أخرى” هي حالة طبيعية.

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/linked?apiKey=YOUR_API_KEY"

الاستجابة

{
  "success": true,
  "data": [
    {
      "contact_id": "contact_def456",
      "channel": "sms",
      "custom_channel": null,
      "first_name": "Jane",
      "last_name": "Smith",
      "phone_number": "+15551234567",
      "last_message": "Sounds good, thanks!",
      "last_message_timestamp": "2026-06-09T10:21:00.000Z",
      "linked_from": {
        "contact_id": "contact_abc123",
        "channel": "whatsapp",
        "linked_at": "2026-06-01T09:00:00.000Z",
        "reason": "continue_on_channel"
      }
    }
  ]
}

إلغاء ربط جهة اتصال #

DELETE /contacts/{contactId}/link

يزيل جهة الاتصال هذه من شخصها، من جانب واحد — أي جهات اتصال أخرى لا تزال مرتبطة بذلك الشخص تحتفظ برابطها، لذا فإن إلغاء ربط واحدة من أصل ثلاث لا يحل المجموعة.

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/link?apiKey=YOUR_API_KEY"

الاستجابة

{ "success": true }

جلب صورة الملف الشخصي لجهة اتصال #

POST /contacts/{contactId}/profile-pic

يجلب (ويخزن مؤقتاً) صورة الملف الشخصي لجهة الاتصال على WhatsApp أو Meta عند الطلب — وهي نفس الصورة التي يتم إرجاعها كـ avatarUrl في الحصول على جهة اتصال، ولكنها محدثة.

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/profile-pic?apiKey=YOUR_API_KEY"

الاستجابة

{
  "success": true,
  "avatar_url": "https://example.com/photo.jpg",
  "cached": false
}

تعني cached: true أن الرابط جاء من عملية جلب حديثة بدلاً من بحث جديد لدى المزود — يتم تخزين الصور مؤقتاً لمدة 7 أيام، ويتم تخزين جهة الاتصال التي يبلغ المزود عن عدم وجود صورة متاحة لها مؤقتاً كغير متاحة لمدة 24 ساعة. عندما لا توجد صورة لجلبها، يتم حذف avatar_url ويوضح message السبب.

تصنيف جهات الاتصال تلقائياً باستخدام الذكاء الاصطناعي #

يقوم بتشغيل قواعد التصنيف الخاصة بحسابك على سجل المحادثات الكامل لجهة اتصال واحدة أو أكثر، ويقوم بإضافة (أو إزالة) التصنيفات تماماً مثل التصنيف الفوري الذي يتم أثناء الدردشة المباشرة — نفس القواعد، ونفس تكلفة الرصيد لكل تصنيف.

بدء عملية تشغيل #

POST /contacts/auto-tag

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/auto-tag?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "contacts", "contact_ids": ["contact_abc123", "contact_def456"] }'

يتم تشغيل جهة اتصال واحدة بشكل مباشر (inline) وتظهر النتيجة على الفور:

{ "success": true, "result": { "tags_applied": 2, "tags_removed": 0 } }

يتم تشغيل اثنتين أو أكثر من جهات الاتصال (أو scope: "agent") كمهمة في الخلفية وتُرجع 202 فوراً:

{ "success": true, "run_id": "m1x2y3-a1b2c3d4", "total": 214 }

استطلاع حالة عملية تشغيل #

GET /contacts/auto-tag/run

تُرجع عملية التشغيل الحالية (أو الأحدث) للحساب، بحيث يمكنك استطلاع التقدم دون الحاجة إلى تتبع run_id بنفسك.

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/auto-tag/run?apiKey=YOUR_API_KEY"

الاستجابة

{
  "success": true,
  "run": {
    "run_id": "m1x2y3-a1b2c3d4",
    "status": "running",
    "total": 214,
    "processed": 58,
    "tagged_contacts": 12,
    "tags_applied": 15,
    "tags_removed": 2,
    "credits_charged": 15
  }
}

يكون run هو null عندما لا يبدأ الحساب أي عملية تشغيل من قبل. ينتقل status من "running" إلى "completed" أو "failed".

يمكن تشغيل عملية جماعية واحدة فقط لكل حساب في المرة الواحدة — بدء عملية ثانية بينما لا تزال أخرى قيد التشغيل يُرجع 409 مع error_code: "auto_tag_run_in_progress". نفاد الرصيد في عملية تشغيل لجهة اتصال واحدة يُرجع 402 مع error_code: "insufficient_credits"؛ أما العملية الجماعية فتتوقف تلقائياً قبل اكتمالها وتُبلغ عن مدى التقدم الذي وصلت إليه في run.

حذف جهة اتصال #

DELETE /contacts/{contactId}

يحذف جهة اتصال واحدة نهائياً عن طريق المعرف، مع سجل رسائلها. لا يمكن التراجع عن هذا الإجراء. لحذف عدة جهات اتصال في طلب واحد، استخدم حذف جهات الاتصال أدناه.

cURL

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.delete(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])

الاستجابة

{
  "success": true
}

معرف جهة اتصال غير موجود في حسابك، أو ينتمي إلى حساب مختلف، يؤدي إلى إرجاع 404.

حذف جهات الاتصال #

DELETE /contacts

يحذف بشكل دائم جهة اتصال واحدة أو أكثر حسب المعرف في استدعاء واحد (حتى 500 معرف). يتم تخطي المعرفات غير الموجودة في حسابك ويتم احتسابها في skipped. لا يمكن التراجع عن هذا الإجراء.

cURL

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contactId1", "contactId2"] }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts", {
  method: "DELETE",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ contactIds: ["contactId1", "contactId2"] }),
});
const data = await res.json();
console.log(`Deleted ${data.deleted}, skipped ${data.skipped}`);

Python

import requests

res = requests.delete(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contactId1", "contactId2"]},
)
data = res.json()
print(f"Deleted {data['deleted']}, skipped {data['skipped']}")

الاستجابة

{
  "success": true,
  "deleted": 2,
  "skipped": 0
}

حذف حقل مخصص #

DELETE /contacts/custom-fields/{fieldKey}

يزيل مفتاح حقل مخصص واحد من كل جهة اتصال في حسابك. استخدم هذا لتنظيف البيانات بعد إعادة تسمية أو إيقاف حقل مخصص. يمكن أن يحتوي المفتاح على أحرف وأرقام وشرطات سفلية وشرطات فقط. يُرجع عدد جهات الاتصال التي تم تحديثها. لا يمكن التراجع عن هذا الإجراء.

cURL

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/custom-fields/webinar_date_nh?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/custom-fields/webinar_date_nh", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(`Removed from ${data.updated} contacts`);

Python

import requests

res = requests.delete(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/custom-fields/webinar_date_nh",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(f"Removed from {res.json()['updated']} contacts")

الاستجابة

{
  "success": true,
  "updated": 42
}

القوائم #

تُستخدم القوائم لتجميع جهات الاتصال. تكون القائمة إما ثابتة (أنت من يقرر من بداخلها) أو ذكية (يتم حساب العضوية بناءً على قواعد وتُحدَّث تلقائياً — راجع تنظيم القوائم وجهات الاتصال).

إنشاء قائمة #

POST /lists

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/lists?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Hot leads (active)",
        "type": "smart",
        "smart_rules": {
          "match": "all",
          "conditions": [
            { "field": "tags", "op": "has_any", "value": ["tagHotLead"] },
            { "field": "last_activity_at", "op": "within_last", "value": { "amount": 90, "unit": "days" } }
          ]
        }
      }'

الاستجابة

{
  "success": true,
  "list_id": "list_abc123",
  "evaluation": { "added": 3, "removed": 0, "total": 3 }
}

يتم تقييم القائمة الذكية مباشرة (inline) في نفس الطلب، لذا يخبرك evaluation بالضبط بمن انتهى به المطاف في القائمة. في القائمة الثابتة، تكون قيمة evaluation هي null.

تحديث قائمة #

PUT /lists/{listId}

أرسل فقط الحقول التي تقوم بتغييرها. يؤدي تغيير smart_rules إلى إعادة تقييم القائمة فوراً وإرجاع نفس كائن evaluation.

curl -X PUT "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/lists/list_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "smart_rules": { "match": "any", "conditions": [ { "field": "tags", "op": "has_any", "value": ["tagHotLead", "tagWebinar"] } ] } }'

يمكنك تبديل القائمة بين النوعين:

• ثابتة ← ذكية: أرسل { "type": "smart", "smart_rules": { … } }. ستتولى القواعد المهمة على الفور.
• ذكية ← ثابتة: أرسل { "type": "static" }. سيتم حذف القواعد وسيبقى من في القائمة كما هو.

هيكل smart_rules #

{
  "match": "all",
  "conditions": [
    { "field": "tags", "op": "has_any", "value": ["tagHotLead"] },
    { "field": "channel", "op": "is_any", "value": ["whatsapp", "sms"] },
    { "field": "last_incoming_message_at", "op": "not_within_last", "value": { "amount": 7, "unit": "days" } },
    { "field": "created_at", "op": "after", "value": "2026-01-01" },
    { "field": "is_bot_active", "op": "is", "value": true },
    { "field": "email", "op": "is_set" },
    { "field": "custom_field", "key": "Plan", "op": "eq", "value": "pro" }
  ]
}

• match — all (يجب أن تكون كل الشروط صحيحة) أو any (شرط واحد على الأقل).
• conditions — من 1 إلى 20 شرطاً، كل شرط بحد أقصى 100 قيمة، وسلاسل نصية تصل إلى 200 حرف.

يطابق not_within_last أيضاً جهات الاتصال التي لم يتم تعيين التاريخ لها مطلقاً (“منذ أكثر من N، أو لم يتم تعيينه أبداً”)، كما أن مقارنات النصوص تتجاهل حالة الأحرف (كبيرة/صغيرة).

تفاعل الذكاء الاصطناعي. has_interacted_with_ai هو علامة مدى الحياة: true لكل جهة اتصال أرسل إليها الذكاء الاصطناعي رسالة واحدة على الأقل، و false لأي شخص آخر (بما في ذلك جهات الاتصال التي رد عليها فريقك فقط). يتم ختمها عند أول رسالة يرسلها الذكاء الاصطناعي إلى جهة الاتصال ولا يتم مسحها أبداً، لذا فإن إيقاف ردود الذكاء الاصطناعي لجهة الاتصال أو نقلها إلى حملة أخرى لا يؤدي إلى إعادة تعيينها. بالنسبة لـ فترة زمنية — “جهات الاتصال التي تعامل معها الذكاء الاصطناعي هذا الشهر”، وهو سؤال الفوترة المعتاد — استخدم النطاق عبر last_ai_interaction_at بدلاً من ذلك:

{ "field": "last_ai_interaction_at", "op": "within_last", "value": { "amount": 30, "unit": "days" } }

لا تخلط بين أي منهما وبين is_bot_active (الذكاء الاصطناعي مسموح له بالرد، وليس أنه قد فعل ذلك بالفعل) أو has_ever_responded (رد جهة الاتصال، على أي شخص). يتم إرجاع نفس الختمين على كل جهة اتصال كـ first_ai_interaction_at / last_ai_interaction_at، وتعمل مجموعة القواعد بأكملها على GET /contacts?rules= أيضاً، لذا يمكنك حساب المطابقات دون إنشاء قائمة.

معاينة مجموعة قواعد #

POST /lists/preview

يتم حساب وعرض عينات من جهات الاتصال التي ستطابقها مجموعة القواعد، دون إنشاء أو تغيير أي شيء. استخدم هذه الميزة للتحقق من سلامة القواعد قبل حفظها.

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/lists/preview?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "smart_rules": { "match": "all", "conditions": [ { "field": "tags", "op": "has_any", "value": ["tagHotLead"] } ] } }'

الاستجابة

{
  "success": true,
  "count": 3,
  "sample": [
    {
      "id": "contact_abc123",
      "first_name": "Sofia",
      "last_name": "Martinez",
      "phone_number": "+31600000000",
      "email": "sofia@example.com",
      "channel": "whatsapp"
    }
  ]
}

تحتفظ sample بما يصل إلى 10 جهات اتصال، مع عرض الأكثر نشاطاً أولاً.

إعادة تشغيل قائمة ذكية الآن #

POST /lists/{listId}/evaluate

تفرض إعادة تقييم فورية (وهي نفس وظيفة تحديث الآن في لوحة التحكم). يتم تحديث القوائم الذكية تلقائياً عند تغيير جهة اتصال، وكل 15 دقيقة للقواعد القائمة على الوقت، لذا لا تحتاج إلى هذا الإجراء إلا عندما تريد الحصول على النتيجة الآن.

الاستجابة

{
  "success": true,
  "list_id": "list_abc123",
  "evaluation": { "added": 2, "removed": 1, "total": 4 }
}

تعني evaluation.skipped: true أن عملية تقييم أخرى لنفس القائمة كانت قيد التشغيل بالفعل، وبالتالي لم يقم هذا الطلب بأي إجراء.

القوائم الذكية ترفض الأعضاء المختارين يدوياً #

تُرجع نقاط نهاية العضوية 409 مع "This is a smart list — its members are computed from its rules. Edit the rules instead." عندما تكون القائمة المستهدفة ذكية. وهذا يشمل POST /contacts/lists، وDELETE /contacts/lists، وPOST /contacts/lists/batch، وcontact_ids في POST /lists وPUT /lists/{listId}، واختيار قائمة ذكية كوجهة لاستيراد ملف CSV. قم بتغيير القواعد بدلاً من ذلك.

استدعاء POST /lists/{listId}/evaluate على قائمة ثابتة يؤدي أيضاً إلى 409 — حيث لا توجد قواعد لتشغيلها.

أخطاء واجهة برمجة تطبيقات جهات الاتصال #

تُرجع نقاط نهاية جهات الاتصال غلاف الخطأ القياسي:

{
  "success": false,
  "error": "Contact not found"
}

تتضمن بعض نقاط النهاية أيضاً error_code، والتي تطابق عادةً حالة HTTP — الاستثناء الوحيد هو حالة جهة الاتصال المكررة أدناه، حيث تكون حالة HTTP هي 200 و error_code فقط هي التي تحمل 409. الرموز الخاصة بنقاط نهاية جهات الاتصال هي:

يمكن أن يعني 403 في نقطة نهاية جهة الاتصال أيضاً مشكلة في حد جهات الاتصال أو إذن القائمة بدلاً من الوصول إلى الخطة. الرموز المشتركة التي يمكن أن ترجعها أي نقطة نهاية — 401، 403 (خطتك لا تتضمن الوصول إلى واجهة برمجة التطبيقات)، 429 (حد المعدل) و 500 — مدرجة مع إرشادات إعادة المحاولة في الأخطاء والترقيم.

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

• واجهة برمجة تطبيقات الرسائل — إرسال الرسائل حسب هوية القناة وإدارة المحادثات.
• مرجع واجهة برمجة التطبيقات — قائمة كاملة بنقاط النهاية، بما في ذلك الوسوم والقوائم.
• الوصول إلى واجهة برمجة التطبيقات — المصادقة، وحدود المعدل، ومعالجة الأخطاء.