واجهة برمجة تطبيقات المهام (Tasks API)

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

عنوان URL الأساسي — https://api.youraiconnector.com/v1
المصادقة — مفتاح واجهة برمجة التطبيقات الخاص بك (راجع المصادقة)
الأخطاء والترقيم — راجع الأخطاء والترقيم

توضح جميع الأمثلة أدناه نموذج الاستعلام ?apiKey= في cURL ورأس X-API-Key في JavaScript وPython — كلاهما يعمل على كل نقطة نهاية.

كائن المهمة

{
  "id": "tsk_abc123",
  "title": "Call Jane about her quote",
  "description": "She asked for pricing on the annual plan.",
  "type": "to_do",
  "priority": "high",
  "stage": "stage-1",
  "due_date": "2026-06-15T09:00:00.000Z",
  "remind_before_minutes": 15,
  "contact": "contacts/uid_whatsapp_15551234567",
  "campaign": "campaigns/abc123",
  "tags": ["sales"],
  "notes": "",
  "source": "api"
}

type — to_do، faq_update، أو أنواع المهام التي قمت بتكوينها (راجع قائمة أنواع المهام).
priority — none، أو low، أو normal، أو high، أو urgent.
stage — معرف المرحلة في لوحة المهام الخاصة بك (راجع قائمة مراحل المهام). عند حذفه أثناء الإنشاء، يتم وضع المهمة في مرحلتك الأولى.
remind_before_minutes — عدد الدقائق قبل due_date لإرسال تذكير. 0 تعني في وقت الاستحقاق؛ احذفه أو أرسل null لعدم وجود تذكير. يجب أن يكون رقماً صحيحاً من 0 إلى 1440 (يوم واحد) — سيتم رفض أي قيمة أكبر. يحتاج التذكير إلى due_date ليتم إطلاقه، وتؤدي إعادة جدولة المهمة إلى نقل التذكير معها.

إنشاء مهمة

POST /tasks — الحقل title فقط هو المطلوب.

ملاحظة: يقبل due_date طابعاً زمنياً بتنسيق ISO 8601، بما في ذلك وقت اليوم. قم بإقرانه بـ remind_before_minutes ليتم تسليم التذكير وفقاً لإعدادات إشعارات المهام الخاصة بك. تربط contact_id و deal_id و campaign_id المهمة بتلك السجلات. assigned_to هو معرف المستخدم الخاص بعضو الفريق.

ضبط assigned_to بشكل صحيح. يجب أن يكون هذا هو معرف المستخدم (user id) الخاص بمالك الحساب أو أحد أعضاء الفريق النشطين في نفس الحساب. لا تتحقق نقطة النهاية هذه حاليًا من ذلك، لذا يتم قبول المعرف الذي لا ينتمي لأحد وتخزينه تمامًا كما أرسلته — وستظل تحصل على 201. انسخ المعرف بدلاً من إعادة كتابته: فهذه المعرفات تخلط بين l و L وبين الحرف O والرقم 0، ويكفي حرف واحد خاطئ لإفساد الأمر. للتحقق مما أرسلته فعليًا، افتح المهمة في لوحة التحكم: يعود حقل المسؤول (Assignee) في سجل المهمة إلى عرض المعرف الخام عندما لا يطابق أي شخص، ويظهر منتقي المسؤول في تحرير المهمة (Edit task) الحالة غير معين (Unassigned).

cURL

curl -X POST "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Call Jane about her quote",
    "priority": "high",
    "due_date": "2026-06-15T09:00:00.000Z",
    "contact_id": "uid_whatsapp_15551234567",
    "tags": ["sales"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/tasks", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Call Jane about her quote",
    priority: "high",
    due_date: "2026-06-15T09:00:00.000Z",
    contact_id: "uid_whatsapp_15551234567",
    tags: ["sales"],
  }),
});
const data = await res.json();
console.log(data.task_id);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "title": "Call Jane about her quote",
        "priority": "high",
        "due_date": "2026-06-15T09:00:00.000Z",
        "contact_id": "uid_whatsapp_15551234567",
        "tags": ["sales"],
    },
)
print(res.json()["task_id"])

الاستجابة (201)

{ "success": true, "task_id": "tsk_abc123", "task": { "title": "Call Jane about her quote", "...": "..." } }

سرد المهام

GET /tasks — تُرجع المهام الخاصة بحسابك، مع فلاتر اختيارية.

معلمات الاستعلام (جميعها اختيارية): stage، priority، contact_id، deal_id، assigned_to، due_before، due_after (طوابع زمنية بتنسيق ISO)، status، include.

المفتوحة أو المنتهية فقط. أضف status=open للحصول فقط على المهام التي ليست في مرحلة “تم” (المهمة التي ليس لها مرحلة، أو مرحلة قمت بإزالتها منذ ذلك الحين، تُعتبر مفتوحة)، أو status=completed للمهام الموجودة فقط في مرحلة “تم”. اتركها فارغة للحصول على كل المهام. أي قيمة أخرى ستُرجع 400.

تسمية جهة الاتصال المرتبطة. تحمل المهمة جهة اتصالها كمرجع، لذا كان سرد لوحة وعرض من تتعلق به كل مهمة يعني جلب كل جهة اتصال على حدة. أضف include=contact وستعود كل مهمة مع ملء contact_name و contact_phone و contact_email و contact_channel من جهة الاتصال المرتبطة. المهام التي ليس لها جهة اتصال، أو التي تم حذف جهة اتصالها، لا تحمل هذه الحقول ببساطة.

cURL

curl "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY&stage=stage-1&priority=high"

# with the linked contact resolved
curl "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY&include=contact"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/tasks?stage=stage-1&priority=high", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { tasks } = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-1", "priority": "high"},
)
tasks = res.json()["tasks"]

الاستجابة (200)

{ "success": true, "tasks": [{ "id": "tsk_abc123", "title": "Call Jane about her quote", "...": "..." }] }

البحث عن المهام

POST /tasks/search — مطابقة النص الكامل في العنوان والوصف، مع نفس عوامل التصفية الاختيارية الموجودة في السرد. تعمل "include": "contact" في النص الأساسي هنا أيضاً، وتقوم بملء اسم جهة الاتصال المرتبطة، ورقم الهاتف، والبريد الإلكتروني، والقناة في كل مطابقة.

curl -X POST "https://api.youraiconnector.com/v1/tasks/search?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "quote", "priority": "high" }'

const res = await fetch("https://api.youraiconnector.com/v1/tasks/search", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ query: "quote", priority: "high" }),
});

res = requests.post(
    "https://api.youraiconnector.com/v1/tasks/search",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"query": "quote", "priority": "high"},
)

الحصول على مهمة

GET /tasks/{taskId}

curl "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY"

const res = await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", { headers: { "X-API-Key": "YOUR_API_KEY" } });

res = requests.get("https://api.youraiconnector.com/v1/tasks/tsk_abc123", headers={"X-API-Key": "YOUR_API_KEY"})

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

تحديث مهمة

PUT /tasks/{taskId} — أرسل فقط الحقول التي تريد تغييرها (title، description، type، priority، stage، due_date، remind_before_minutes، contact_id، deal_id، assigned_to، tags، notes).

curl -X PUT "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "urgent", "notes": "Left a voicemail." }'

await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ priority: "urgent", notes: "Left a voicemail." }),
});

requests.put(
    "https://api.youraiconnector.com/v1/tasks/tsk_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"priority": "urgent", "notes": "Left a voicemail."},
)

إكمال مهمة

POST /tasks/{taskId}/complete — تنقل المهمة إلى مرحلة المهام المكتملة في لوحتك. حقل اختياري notes يسجل ملاحظة ختامية.

curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Closed — customer signed up." }'

await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ notes: "Closed — customer signed up." }),
});

requests.post(
    "https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"notes": "Closed — customer signed up."},
)

النقل وإعادة الترتيب (كانبان)

نقل مهمة إلى مرحلة أخرى — POST /tasks/{taskId}/move مع new_stage_id (المرحلة الوجهة) و new_position (الموضع المعتمد على الصفر داخل تلك المرحلة؛ مطلوب، يجب أن يكون عدداً صحيحاً غير سالب):

curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_abc123/move?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "new_stage_id": "stage-2", "new_position": 0 }'

إعادة ترتيب المهام داخل مرحلة — POST /tasks/reorder مع stage_id ومعرفات المهام بترتيبها الجديد:

curl -X POST "https://api.youraiconnector.com/v1/tasks/reorder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "stage-1", "ordered_task_ids": ["tsk_3", "tsk_1", "tsk_2"] }'

await fetch("https://api.youraiconnector.com/v1/tasks/reorder", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ stage_id: "stage-1", ordered_task_ids: ["tsk_3", "tsk_1", "tsk_2"] }),
});

requests.post(
    "https://api.youraiconnector.com/v1/tasks/reorder",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"stage_id": "stage-1", "ordered_task_ids": ["tsk_3", "tsk_1", "tsk_2"]},
)

مهام جهة اتصال

GET /tasks/contact/{contactId} — كل مهمة مرتبطة بجهة اتصال واحدة.

curl "https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567?apiKey=YOUR_API_KEY"

const res = await fetch("https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567", { headers: { "X-API-Key": "YOUR_API_KEY" } });

res = requests.get("https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567", headers={"X-API-Key": "YOUR_API_KEY"})

إعداد لوحة المهام

سرد مراحل المهام

GET /tasks/stages — أعمدة لوحتك، بالترتيب. استخدم id المرحلة كحقل stage عند إنشاء المهام أو نقلها.

curl "https://api.youraiconnector.com/v1/tasks/stages?apiKey=YOUR_API_KEY"

{ "success": true, "stages": [{ "id": "stage-1", "name": "To Do", "is_completed_stage": false }, { "id": "stage-done", "name": "Done", "is_completed_stage": true }] }

تحديث مراحل المهمة

PUT /tasks/stages — استبدل إعدادات مراحل لوحتك. أرسل مصفوفة stages المرتبة بالكامل.

curl -X PUT "https://api.youraiconnector.com/v1/tasks/stages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stages": [
    { "id": "stage-1", "name": "To Do", "is_completed_stage": false },
    { "id": "stage-2", "name": "In Progress", "is_completed_stage": false },
    { "id": "stage-done", "name": "Done", "is_completed_stage": true }
  ] }'

سرد أنواع المهام

GET /tasks/types — أنواع المهام المكونة في حسابك (تُستخدم كحقل type).

curl "https://api.youraiconnector.com/v1/tasks/types?apiKey=YOUR_API_KEY"

الموافقة على اقتراح الأسئلة الشائعة

عندما يقترح روبوت الذكاء الاصطناعي سؤالاً شائعاً (FAQ) جديداً، فإنه ينشئ مهمة من النوع faq_update. تقوم POST /tasks/{taskId}/approve-faq بتحويل هذا الاقتراح إلى سؤال شائع حقيقي في قاعدة معارف وكيل الذكاء الاصطناعي الذي طرحه وتكمل المهمة. يمكنك تجاوز السؤال/الإجابة في النص الأساسي.

أضف "send_follow_up": true لكي يقوم الذكاء الاصطناعي أيضاً بإرسال الإجابة إلى جهة الاتصال المرتبطة بالمهمة على الفور، كرسالة طبيعية في تلك المحادثة (وهو نفس ما يفعله مفتاح التبديل إرسال الإجابة إلى جهة الاتصال الآن في التطبيق). يتم إرسال الرد من خلال وكيل الذكاء الاصطناعي الذي يتعامل مع جهة الاتصال تلك. يتم ترك إعداد البوت الخاص بجهة الاتصال كما كان: في جهة اتصال يكون فيها الذكاء الاصطناعي متوقفاً مؤقتاً، يتم إرسال هذا الرد الواحد ويبقى الذكاء الاصطناعي متوقفاً مؤقتاً.

curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_faq99/approve-faq?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Do you offer refunds?", "answer": "Yes, within 30 days.", "send_follow_up": true }'

{ "success": true, "faq_id": "faq_xyz", "task_id": "tsk_faq99", "follow_up_status": "published" }

follow_up_status يخبرك بما حدث للرسالة: not_requested (العلامة غير محددة)، published (تم الإرسال)، queued (كان الروبوت في منتصف الرد على جهة الاتصال تلك، وسيتم إرسال الإجابة بمجرد انتهائه)، skipped_no_contact (المهمة ليس لديها جهة اتصال مرتبطة)، skipped_no_campaign (لا يمكن لأي وكيل أو حملة الرد على جهة الاتصال تلك) أو skipped_error. يتم إنشاء السؤال الشائع (FAQ) في كل حالة.

راجع واجهة برمجة تطبيقات الأسئلة الشائعة لإدارة الأسئلة الشائعة الناتجة.

حذف مهمة

DELETE /tasks/{taskId}

curl -X DELETE "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY"

await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } });

requests.delete("https://api.youraiconnector.com/v1/tasks/tsk_abc123", headers={"X-API-Key": "YOUR_API_KEY"})

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

واجهة برمجة تطبيقات جهات الاتصال — ربط المهام بجهة الاتصال الصحيحة
واجهة برمجة تطبيقات خطافات الويب — تلقي إشعارات حول Task Created و Task Updated و Task Completed
مرجع واجهة برمجة التطبيقات — مستكشف نقاط النهاية التفاعلي الكامل

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

كائن المهمة #

إنشاء مهمة #

سرد المهام #

البحث عن المهام #

الحصول على مهمة #

تحديث مهمة #

إكمال مهمة #

النقل وإعادة الترتيب (كانبان) #

مهام جهة اتصال #

إعداد لوحة المهام #

سرد مراحل المهام #

تحديث مراحل المهمة #

سرد أنواع المهام #

الموافقة على اقتراح الأسئلة الشائعة #

حذف مهمة #

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

واجهة برمجة تطبيقات المهام (Tasks API)

كائن المهمة

إنشاء مهمة

سرد المهام

البحث عن المهام

الحصول على مهمة

تحديث مهمة

إكمال مهمة

النقل وإعادة الترتيب (كانبان)

مهام جهة اتصال

إعداد لوحة المهام

سرد مراحل المهام

تحديث مراحل المهمة

سرد أنواع المهام

الموافقة على اقتراح الأسئلة الشائعة

حذف مهمة

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