الرسائل والمحادثات #

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

جميع المسارات في هذه الصفحة نسبية إلى عنوان URL الأساسي https://api.youraiconnector.com/v1. يتطلب كل طلب مفتاح واجهة برمجة التطبيقات الخاص بك — راجع المصادقة للحصول على القائمة الكاملة لطرق إرساله. تستخدم الأمثلة أدناه ترويسة X-API-Key، مع مثال cURL واحد يوضح نموذج استعلام ?apiKey= أيضًا.

كيفية عمل التسليم: إرسال رسالة لا يعني انتظار وصولها. تقبل واجهة برمجة التطبيقات رسالتك، وتستجيب فوراً بمعرف الرسالة (message ID)، ثم تقوم بتسليمها في الخلفية عبر قناة جهة الاتصال (WhatsApp، SMS، Instagram، وما إلى ذلك). لتتبع ما إذا كانت الرسالة قد تم تسليمها أو قراءتها بالفعل، استمع إلى تحديثات الحالة عبر Webhooks — لا تستخدم الاستطلاع (polling). استجابة الإرسال تؤكد فقط قبول الرسالة.

إرسال رسالة #

هناك طريقتان للإرسال. اختر ما يناسب الطريقة التي تحدد بها جهة الاتصال حالياً:

• الإرسال بواسطة معرف جهة الاتصال (contact ID) — أنت تعرف بالفعل معرف جهة الاتصال (على سبيل المثال، قمت بإنشاء جهة الاتصال من خلال واجهة برمجة التطبيقات أو حصلت عليه من webhook). استخدم POST /contacts/{contactId}/send-message.
• الإرسال بواسطة هوية جهة الاتصال (contact identity) — أنت تعرف رقم هاتف جهة الاتصال، أو معرف Instagram، وما إلى ذلك، ولكن ليس معرفها الداخلي. استخدم POST /contacts/send ودع المنصة تعثر على جهة الاتصال الصحيحة.

كلاهما يضع الرسالة في قائمة الانتظار بنفس الطريقة ويسلمها عبر القناة التي تستخدمها جهة الاتصال. أنت لا تختار وسيلة النقل — تقوم المنصة بتوجيه جهات اتصال WhatsApp عبر WhatsApp، وجهات اتصال SMS عبر SMS، وهكذا.

كلاهما يعثر فقط على جهات الاتصال الموجودة بالفعل. لا يقوم أي من الاستدعاءين بإنشاء جهة اتصال: إذا لم يتم العثور على مطابقة للهوية أو المعرّف، فستعود النتيجة كـ 404، ولن يتم إنشاء جهة اتصال جديدة. لذا، إذا كنت تراسل شخصاً ما للمرة الأولى، فقم إما بإنشاء جهة الاتصال أولاً باستخدام POST /contacts، أو استخدم خيار الإرسال إلى رقم WhatsApp Web مباشرة أدناه في WhatsApp Web، والذي يقوم بإنشاء جهة الاتصال في نفس الاستدعاء.

الإرسال بواسطة معرف جهة الاتصال #

POST /contacts/{contactId}/send-message

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

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/send-message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi! Your appointment is confirmed for tomorrow at 10:00."
  }'

JavaScript

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

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/send-message",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"body": "Hi! Your appointment is confirmed for tomorrow at 10:00."},
)
print(res.json()["messageId"])

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

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

الإرسال بواسطة هوية جهة الاتصال #

POST /contacts/send

استخدم هذا عندما لا يكون لديك المعرف الداخلي لجهة الاتصال. قدم نص الرسالة body بالإضافة إلى إما contact_id، أو channel مع حقل الهوية الذي يطابق تلك القناة.

القنوات التي يمكن تحديدها عن طريق الهوية. ست قنوات فقط من أصل 14 تقبل حقل هوية بدلاً من contact_id: يتم البحث عن whatsapp و whatsapp_web و sms بواسطة phone_number، و instagram بواسطة instagram_id، و messenger بواسطة messenger_id، و telegram بواسطة telegram_user_id. القنوات الثماني الأخرى — instagram_private و chat-widget و custom و email و line و imessage و linkedin و viber — ليس لها هوية عامة يمكن البحث عنها، لذا فإن الإرسال عبر تلك القنوات يتطلب contact_id؛ تمرير channel بمفرده يُرجع 400 يخبرك بأن contact_id مطلوب.

cURL (باستخدام نموذج استعلام ?apiKey=)

curl -X POST "https://api.youraiconnector.com/v1/contacts/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number": "+31612345678",
    "body": "Hi! Your appointment is confirmed."
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel: "whatsapp",
    phone_number: "+31612345678",
    body: "Hi! Your appointment is confirmed.",
  }),
});
const data = await res.json();
console.log(data.message_id, data.channel);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/send",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "channel": "whatsapp",
        "phone_number": "+31612345678",
        "body": "Hi! Your appointment is confirmed.",
    },
)
data = res.json()
print(data["message_id"], data["channel"])

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

{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp"
}

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

الإرسال عبر WhatsApp Web: الاختلافات وحماية الدفعات #

ينطبق أمران على body عندما يكون جهة الاتصال على WhatsApp Web.

يتم توسيع أقواس Spintax لكل عملية إرسال. يتم إرسال body من {Hi|Hello|Hey} there, quick question كواحدة من التحيات الثلاث، ويتم اختيارها لتلك العملية — لا تصل الأقواس أبدًا إلى جهة الاتصال. استخدمها لمنح كل جهة اتصال رسالة افتتاحية مختلفة من نفس رمز التكامل. يتم إرسال النص بدون أقواس تمامًا كما هو مكتوب.

يتم رفض دفعات الرسائل الافتتاحية المتطابقة. إذا تم إرسال عشر رسائل افتتاحية متطابقة تقريبًا من رقم WhatsApp Web واحد خلال ساعة، إلى جهات اتصال لم تراسلك من قبل، فلن يتم تسليم الرسائل اللاحقة: يتم قبول الإرسال كالمعتاد (ستظل تحصل على messageId)، ثم تُترك الرسالة مع status: "failed" و error_code: "opener_burst"، مع وجود سبب يمكن للعميل قراءته عليها. إعادة محاولة إرسال نفس النص لا تساعد — قم بتغيير النص، وانتظر ساعة، ثم أرسل مرة أخرى. الردود داخل المحادثات الحالية لا تتأثر أبدًا. السبب موضح في المفتتحات المتطابقة تؤدي إلى تقييد الأرقام.

الإرسال إلى رقم WhatsApp Web مباشرة #

POST /whatsapp-web/send

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

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-web/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "message": "Hi Alex, your quote is ready."
  }'

الاستدعاء الناجح يجيب بـ 202:

{ "success": true, "queued": true, "contactId": "abc123" }

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

عندما لا تتم العملية:

الاستدعاء الثاني لنفس جهة الاتصال بينما لا يزال هناك إرسال معلق ينتظر، يجيب بـ 409، بحيث لا تتراكم قائمة انتظار خلف شخص واحد أبداً.

تسجيل ملاحظة في محادثة #

POST /contacts/notes

تضيف سطراً إلى محادثة جهة الاتصال دون إرساله. استخدمها للسياق الذي يجب أن يطلع عليه فريقك والذكاء الاصطناعي ولكن لا ينبغي لجهة الاتصال رؤيته: ملخص لمكالمة هاتفية أجراها وكيلك الصوتي للتو، أو ملاحظة من نظام إدارة علاقات العملاء (CRM) الخاص بك، أو ملاحظة من زميل. تعمل هذه الميزة على جميع القنوات (WhatsApp، وSMS، وInstagram، وMessenger، وTelegram، وعنصر واجهة الدردشة، والقنوات المخصصة، وما إلى ذلك).

ماذا يحدث للملاحظة:

• تظهر في الدردشة داخل صندوق الوارد كبطاقة ملاحظة صفراء، مع اسم كاتبها إذا قمت بتحديده.
• يقرأها الذكاء الاصطناعي كجزء من سجل المحادثة، ويتم تمييزها كملاحظة داخلية، لذا يأخذها في الاعتبار عند الرد التالي.
• لا يتم إرسالها أبداً إلى جهة الاتصال، ولا تستهلك رصيد رسائل، ولا تؤدي إلى أي إجراء: لا يوجد رد من الذكاء الاصطناعي، ولا أتمتة، ولا خطاف ويب (webhook)، ولا إشعار، ولا شارة غير مقروءة. كما أنها لا توقف الذكاء الاصطناعي مؤقتاً ولا تُحتسب كـ “رد” من فريقك.

اعثر على جهة الاتصال بنفس الطريقة المتبعة في الإرسال حسب هوية جهة الاتصال: إما عن طريق المعرف الخاص بها، أو باستخدام channel متبوعاً بالمُعرّف المطابق. لا تُرسل الملاحظة إلا إلى جهة اتصال موجودة بالفعل؛ أي شيء لا يطابق سيؤدي إلى 404.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/notes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number": "+31612345678",
    "author": "Voice agent",
    "body": "Voice call, 3:12. Asked about knee surgery waiting times, prefers a call back on Tuesday morning.",
    "external_id": "call_8f2k1"
  }'

الاستجابة (201، أو 200 مع duplicate: true عندما يكون قد تم تسجيل external_id مسبقاً)

{
  "success": true,
  "messageId": "note_4c1f0e...",
  "contactId": "contact123"
}

تظهر الملاحظة في سرد رسائل جهة الاتصال مع type: "note".

إنشاء مسودة رد باستخدام الذكاء الاصطناعي #

POST /contacts/{contactId}/draft-reply

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

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

جميع حقول النص اختيارية؛ النص الفارغ (أو عدم وجود نص) يقوم بصياغة الرد التالي.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/draft-reply" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instruction": "Offer Tuesday at 3pm for the consultation" }'

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

{
  "success": true,
  "contact_id": "contact123",
  "draft": "Hi Sara, Tuesday at 3pm works for the consultation. Shall I put you down for it?"
}

يعني 400 أن المحادثة لا تحتوي على رسائل بعد، أو أن رصيدك قد نفد، أو أن جهة الاتصال ليس لديها وكيل أو حملة للصياغة منها (يوضح error السبب). يعني 404 أن جهة الاتصال غير موجودة، أو أن مفتاح عضو الفريق مقيد بجهات اتصال لا يمكنه رؤيتها. يحتاج المفتاح أو عضو الفريق إلى إذن لتعديل الرسائل.

هل تستخدم عميل ذكاء اصطناعي عبر MCP؟ نفس الإجراء متاح كأداة generate_reply_draft.

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

GET /contacts/{contactId}/messages

يعيد رسائل جهة الاتصال، الأحدث أولاً، مع ترقيم صفحات يعتمد على المؤشر.

ملاحظة حول التصفية وترقيم الصفحات: يتم تطبيق عوامل التصفية filter و direction على كل صفحة بعد قراءتها، لذا قد تحتوي الصفحة المفلترة على عناصر أقل من limit. لا يزال next_cursor يتقدم عبر المحادثة الكاملة، لذا استمر في التنقل بين الصفحات حتى تصبح next_cursor مساوية لـ null.

cURL

curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&direction=inbound" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ limit: "50", direction: "inbound" });
const res = await fetch(
  `https://api.youraiconnector.com/v1/contacts/contact123/messages?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.messages, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"limit": 50, "direction": "inbound"},
)
data = res.json()
print(data["messages"], data["next_cursor"])

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

{
  "success": true,
  "contact_id": "contact123",
  "messages": [
    {
      "id": "aB3dE5fG7hI9jK1lM2nO",
      "body": "Hi! Thanks for reaching out.",
      "direction": "inbound",
      "channel": "whatsapp",
      "status": "delivered",
      "type": null,
      "timestamp": "2026-06-01T10:00:00.000Z",
      "media_url": null,
      "media_content_type": null,
      "bot_reply": false
    }
  ],
  "next_cursor": "cD4eF6gH8iJ0kL2mN3oP"
}

حقول الرسالة #

تنزيل مرفق رسالة #

POST /chat-exports/media/download-url

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

للعثور على الرسائل التي تحتوي على مرفقات، قم بسرد رسائل جهة الاتصال باستخدام filter=media. يشكل كل من id الخاص بالرسالة ومعرف جهة الاتصال الـ messagePath.

cURL

curl -X POST "https://api.youraiconnector.com/v1/chat-exports/media/download-url" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messagePath": "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO"}'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/chat-exports/media/download-url", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ messagePath: "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO" }),
});
const { data } = await res.json();
console.log(data.url); // download the file within the hour

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/chat-exports/media/download-url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"messagePath": "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO"},
)
file_url = res.json()["data"]["url"]

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

{
  "success": true,
  "data": {
    "url": "https://storage.googleapis.com/...",
    "expiresInMs": 3600000
  }
}

هل تستخدم عميل ذكاء اصطناعي عبر MCP؟ الإجراء نفسه متاح كأداة get_chat_media_download_url.

سرد جلسات المحادثة #

جلسة الدردشة هي نافذة محادثة واحدة مع جهة اتصال. تُفتح عند وصول أول رسالة واردة في حال عدم وجود جلسة مفتوحة، وتُغلق تلقائياً بعد 48 ساعة من آخر رسالة واردة من جهة الاتصال (كل رسالة واردة جديدة تؤخر موعد الإغلاق لمدة 48 ساعة أخرى). إن قيام الذكاء الاصطناعي بإنهاء الدردشة لا يؤدي إلى إغلاق الجلسة؛ بل يقوم فقط بتفعيل خطاف الويب الخاص بـ “الدردشة المنتهية” (Chat Concluded). تُعد الجلسات الطريقة التي يمكنك من خلالها تقسيم السجل الطويل إلى محادثات قابلة للقراءة بدلاً من قائمة واحدة لا تنتهي.

الجلسات الأخيرة عبر جميع جهات الاتصال #

GET /chat-sessions/recent

تُرجع الجلسات التي بدأت في آخر X ساعة، مرتبة من الأحدث، عبر كل جهة اتصال في الحساب.

cURL

curl "https://api.youraiconnector.com/v1/chat-sessions/recent?hours=24&status=ChatSessionClosed" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ hours: "24", status: "ChatSessionClosed" });
const res = await fetch(`https://api.youraiconnector.com/v1/chat-sessions/recent?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.data.total_sessions, data.data.sessions);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/chat-sessions/recent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"hours": 24, "status": "ChatSessionClosed"},
)
data = res.json()["data"]
print(data["total_sessions"], data["sessions"])

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

{
  "success": true,
  "data": {
    "hours_ago": 24,
    "total_sessions": 2,
    "sessions": [
      {
        "session_id": "session456",
        "contact_id": "contact123",
        "contact_name": "Jane Doe",
        "contact_phone": "+31612345678",
        "contact_email": "jane@example.com",
        "start_date_time": "2026-06-01T09:55:00.000Z",
        "end_date_time": "2026-06-01T10:20:00.000Z",
        "status": "ChatSessionClosed",
        "tag": "Booking enquiry"
      }
    ]
  }
}

جميع الجلسات لجهة اتصال واحدة #

GET /chat-sessions/{contactId}

تُرجع كل جلسة محادثة لجهة اتصال واحدة. تستخدم نفس معلمات status و limit و includeMessages المذكورة أعلاه — hours لا تنطبق هنا.

cURL

curl "https://api.youraiconnector.com/v1/chat-sessions/contact123?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

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

{
  "success": true,
  "data": {
    "contact_id": "contact123",
    "contact_name": "Jane Doe",
    "total_sessions": 2,
    "sessions": [
      {
        "id": "session456",
        "start_date_time": "2026-06-01T09:55:00.000Z",
        "end_date_time": "2026-06-01T10:20:00.000Z",
        "status": "ChatSessionClosed",
        "tag": "Booking enquiry"
      }
    ]
  }
}

تختلف أسماء حقول معرف الجلسة بين نقطتي النهاية. تسميها قائمة الجلسات الأخيرة session_id (كما أنها تحمل تفاصيل جهة الاتصال، نظرًا لأن الجلسات تأتي من جهات اتصال متعددة)؛ بينما تسميها قائمة كل جهة اتصال id. أي من القيمتين هي ما تمرره كـ {sessionId} عند جلب السلسلة الكاملة أدناه.

عند includeMessages=true، تكتسب كل جلسة مصفوفة messages تحتوي إدخالاتها على id، وbody، وdirection، وtimestamp، وtype، وchannel، وstatus.

جلب سلسلة محادثة #

GET /contacts/{contactId}/chat-sessions/{sessionId}/messages

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

cURL

curl "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.session, data.messages);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["session"], data["messages"])

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

{
  "success": true,
  "contact_id": "contact123",
  "session": {
    "id": "session456",
    "status": "ChatSessionClosed",
    "start_date_time": "2026-06-01T09:55:00.000Z",
    "end_date_time": "2026-06-01T10:20:00.000Z",
    "tag": "Booking enquiry"
  },
  "messages": [
    {
      "id": "aB3dE5fG7hI9jK1lM2nO",
      "body": "Hi! Thanks for reaching out.",
      "direction": "inbound",
      "channel": "whatsapp",
      "status": "delivered",
      "type": null,
      "timestamp": "2026-06-01T09:55:00.000Z",
      "media_url": null,
      "media_content_type": null,
      "bot_reply": false
    }
  ]
}

يُبلغ كائن session عن status (ChatSessionOpened أثناء النشاط، وChatSessionClosed بمجرد الانتهاء)، وstart_date_time، وend_date_time، وtag يمكن قراءته من قبل البشر. تستخدم مصفوفة messages نفس حقول الرسائل المستخدمة في نقطة نهاية القائمة.

تحرير وحذف والتفاعل مع الرسائل #

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

ما تسمح به كل قناة

في جميع القنوات الأخرى — واجهة برمجة تطبيقات WhatsApp Business، والرسائل القصيرة (SMS)، وInstagram، وMessenger، والبريد الإلكتروني، وLINE، والقنوات المخصصة — لا يزال الحذف يزيل الرسالة من صندوق الوارد الخاص بك، لكن جهة الاتصال تحتفظ بنسختها، كما أن التعديل أو التفاعل غير ممكن على الإطلاق.

تعديل رسالة #

POST /contacts/{contactId}/messages/{messageId}/edit

يعيد كتابة رسالة أرسلتها بالفعل، على جهاز جهة الاتصال وفي نسختك الخاصة.

على عكس الحذف، فإن هذا الإجراء يفشل بوضوح عندما ترفض القناة ذلك: ستحصل على 409 وستبقى نسختك كما هي تماماً لدى جهة الاتصال، لأن عرض تعديل لم يتلقوه أبداً سيؤدي إلى عدم التزامن بين الطرفين. يخبرك الحقل edit_reason بالسبب — إما أن نافذة التعديل الخاصة بالقناة قد أُغلقت، أو أن القناة غير متصلة، أو أن الرسالة تحتوي على مرفق لا يمكن للقناة تعديله (media_not_editable: على WhatsApp Web يمكن فقط تعديل الرسائل النصية، وليس النص الموجود أسفل صورة أو مقطع فيديو أو ملف)، أو حدث خطأ آخر.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Sorry - I meant Thursday at 3pm." }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ body: "Sorry - I meant Thursday at 3pm." }),
  }
);
const data = await res.json();
console.log(data.edited, data.edit_reason);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"body": "Sorry - I meant Thursday at 3pm."},
)
data = res.json()
print(data.get("edited"), data.get("edit_reason"))

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

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "edited": true,
  "edit_reason": "edit_dispatched"
}

إذا لم تقبل القناة التعديل، ستحصل على 409 بدلاً من ذلك، ولن يتم تغيير أي شيء:

{
  "success": false,
  "error": "The message could not be edited",
  "edit_reason": "channel_disconnected"
}

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

حذف رسالة واحدة #

DELETE /contacts/{contactId}/messages/{messageId}

يزيل الرسالة من محادثتك، وفي حال كانت القناة تسمح بذلك، يسحب نسخة جهة الاتصال أيضاً. لا يوجد نص للطلب (request body).

يستجيب هذا دائماً بـ 200 عندما تكون الرسالة موجودة، حتى لو تعذر سحب نسخة جهة الاتصال — نسختك قد حُذفت بالفعل، لذا فإن إظهار خطأ سيكون مضللاً. اقرأ الحقول الثلاثة في الاستجابة لتخبر المستخدم بما حدث فعلياً:

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.revoked, data.revoke_reason);

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["revoked"], data["revoke_reason"])

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

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "revoke_supported": true,
  "revoked": true,
  "revoke_reason": "revoke_dispatched"
}

لا تتم إزالة الرسائل المحذوفة من سجل المحادثة. بل تبقى في GET /contacts/{contactId}/messages مع is_deleted: true و body فارغ و media_url.

حذف عدة رسائل دفعة واحدة #

POST /contacts/{contactId}/messages/bulk-delete

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

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message_ids": ["msg_1", "msg_2"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message_ids: ["msg_1", "msg_2"] }),
  }
);
console.log((await res.json()).deleted);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"message_ids": ["msg_1", "msg_2"]},
)
print(res.json()["deleted"])

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

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

التفاعل مع رسالة #

POST /contacts/{contactId}/messages/{messageId}/react

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

مثل التعديل، يفشل هذا الإجراء بدلاً من إظهار تفاعل لم تصل لجهة الاتصال، ويخبرك الفشل ما إذا كانت إعادة المحاولة تستحق العناء:

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

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emoji": "👍" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ emoji: "👍" }),
  }
);
const data = await res.json();
console.log(data.reactions);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"emoji": "👍"},
)
print(res.json()["reactions"])

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

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "reaction_supported": true,
  "reaction_reason": "reaction_dispatched",
  "reactions": [
    {
      "emoji": "👍",
      "from_phone_number": "+31612345678",
      "from_me": true,
      "reacted_at": "2026-06-01T10:05:00.000Z"
    }
  ]
}

مصفوفة reactions هي المجموعة الكاملة للتفاعلات الموجودة حالياً على الرسالة، الخاصة بك والخاصة بجهة الاتصال. عند 409 أو 422 يتم إرجاعها دون تغيير، لذا فإن العميل الذي يعرض البيانات مباشرة منها لا يظهر أبداً تفاعلاً لم يتم تسليمه.

تقييم أو تمييز رسالة بنجمة #

PATCH /contacts/{contactId}/messages/{messageId}

يقيم رسالة بإبهام لأعلى أو لأسفل و/أو يضع عليها نجمة كرسالة مهمة. هذا مجرد تنظيم من جانبك فقط — لا يتم إرسال أي شيء إلى جهة الاتصال.

أرسل واحدة على الأقل من الاثنتين، وإلا ستحصل على 400. يتم كتابة ما ترسله فقط، لذا فإن تمييز رسالة بنجمة لا يؤدي أبداً إلى مسح تقييمها والعكس صحيح — كما أن الاستجابة تعيد فقط الحقول التي أرسلتها.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "score": 1, "is_important": true }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1", {
  method: "PATCH",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ score: 1, is_important: true }),
});

Python

import requests

requests.patch(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"score": 1, "is_important": True},
)

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

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "score": 1,
  "is_important": true
}

وضع علامة مقروء على الرسائل #

يمكنك مسح حالة غير مقروء إما لرسائل محددة أو للمحادثة بأكملها.

وضع علامة مقروء على رسائل محددة #

POST /contacts/{contactId}/messages/mark-read

قم بتمرير معرفات الرسائل لوضع علامة مقروء عليها.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_ids": ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message_ids: ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"],
    }),
  }
);
const data = await res.json();
console.log(data.marked_read);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"message_ids": ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"]},
)
print(res.json()["marked_read"])

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

{
  "success": true,
  "contact_id": "contact123",
  "marked_read": 2
}

وضع علامة مقروء على الدردشة بأكملها #

POST /contacts/{contactId}/mark-read

يمسح شارة غير مقروء لمحادثة جهة الاتصال بأكملها في صندوق الوارد. لا يلزم وجود نص طلب.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/mark-read" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/mark-read",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/mark-read",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])

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

{
  "success": true,
  "contact_id": "contact123"
}

وضع علامة غير مقروء على المحادثة بأكملها #

POST /contacts/{contactId}/mark-unread

يعيد شارة “غير مقروء” إلى المحادثة — مفيد عندما يفتح شخص ما في فريقك محادثة ولكنه يعيدها إليك. لا يلزم وجود نص طلب (request body).

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

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/mark-unread" \
  -H "X-API-Key: YOUR_API_KEY"

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

{
  "success": true,
  "contact_id": "contact123"
}

تصدير محادثة #

تمنحك عمليات التصدير محادثة كاملة كنص قابل للقراءة، بدلاً من التنقل بين صفحات الرسائل. تقبل كل نقطة نهاية للتصدير filter من نوع all (الافتراضي)، أو text، أو media، أو tool_use، بما يتطابق مع الفلتر الموجود في قائمة الرسائل.

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

GET /chat-exports/{contactId}

cURL

curl "https://api.youraiconnector.com/v1/chat-exports/contact123?format=json" \
  -H "X-API-Key: YOUR_API_KEY"

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/chat-exports/contact123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"format": "json"},
)
print(res.json()["data"]["messages"])

الاستجابة مع format=json (200 OK):

{
  "success": true,
  "data": {
    "contact": {
      "id": "contact123",
      "name": "Jane Doe",
      "phone": "+31612345678",
      "email": "jane@example.com"
    },
    "messages": [
      {
        "body": "Hi! I have a question about my order.",
        "direction": "inbound",
        "timestamp": "2026-06-01T09:55:00.000Z",
        "type": "text",
        "media_url": null,
        "media_content_type": null,
        "name": null,
        "args": null
      }
    ]
  }
}

مع format=txt (الافتراضي)، يكون data بدلاً من ذلك رابط تنزيل لملف النص الذي تم إنشاؤه:

{
  "success": true,
  "data": "https://storage.googleapis.com/.../chat-export-contact123-....txt"
}

رابط التنزيل قصير الأجل. قم بجلب الملف بمجرد حصولك على الرابط بدلاً من تخزينه — اطلب تصديراً جديداً عندما تحتاج إلى النص مرة أخرى.

تصدير كل المحادثات الأخيرة #

GET /chat-exports/recent

تصدير محادثات جميع جهات الاتصال التي كانت نشطة في آخر X ساعة، في طلب واحد.

cURL

curl "https://api.youraiconnector.com/v1/chat-exports/recent?hours=24&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

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

{
  "success": true,
  "data": {
    "hours_ago": 24,
    "total_contacts": 2,
    "exports": [
      {
        "contactId": "contact123",
        "contactName": "Jane Doe",
        "phoneNumber": "+31612345678",
        "email": "jane@example.com",
        "messageCount": 12,
        "chatExport": "Acme Export - Jane Doe\nPhone: +31612345678\n..."
      }
    ]
  }
}

مع format=txt تكون الاستجابة هي الملف النصي نفسه، ويتم إرساله كتنزيل بدلاً من JSON.

يقوم هذا الطلب الواحد بسحب السجل الكامل لكل جهة اتصال مطابقة، لذا اجعل hours و limit معتدلين في الحسابات المزدحمة.

إرسال نسخة من المحادثة بالبريد الإلكتروني إلى جهة الاتصال #

POST /chat-exports/{contactId}/email

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

cURL

curl -X POST "https://api.youraiconnector.com/v1/chat-exports/contact123/email" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Here is a copy of our chat, as promised." }'

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

{
  "success": true,
  "data": {
    "via": "transactional",
    "recipientEmail": "jane@example.com",
    "messageCount": 42,
    "omittedCount": 0
  }
}

يخبرك omittedCount بعدد الرسائل الأقدم التي تم استبعادها للحفاظ على طول معقول للبريد الإلكتروني. تعني 200 أن نسخة المحادثة قد تم إنشاؤها ووضعها في قائمة الانتظار للإرسال، وليس أنها وصلت إلى صندوق الوارد بعد.

إيقاف أو استئناف الذكاء الاصطناعي لجهة اتصال واحدة #

PUT /contacts/{contactId}

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

cURL

curl -X PUT "https://api.youraiconnector.com/v1/contacts/contact123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_bot_active": false }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/contacts/contact123", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ is_bot_active: false }),
});

Python

import requests

requests.put(
    "https://api.youraiconnector.com/v1/contacts/contact123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"is_bot_active": False},
)

الاستجابة

{
  "success": true,
  "contact_id": "contact123"
}

الإيقاف المؤقت كجزء من الرد

إذا كان هناك تدخل بشري عن طريق إرسال رد، يمكنك إيقاف البوت مؤقتاً في نفس الطلب بدلاً من إجراء استدعاء ثانٍ. يقبل POST /contacts/{contactId}/send-message هذه الأعلام الاختيارية:

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/send-message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi, Sarah here - taking over from the assistant.",
    "pauseBot": true,
    "clearIncompleteReply": true,
    "human_reply": true
  }'

يتضمن الرد "botPaused": true عند تطبيق الإيقاف المؤقت.

وضع علامة على جهة اتصال كخاصة باستخدام POST /contacts/bulk-flag يؤدي أيضاً إلى إيقاف البوت مؤقتاً لها. راجع جهات الاتصال للحصول على قائمة الحقول الكاملة.

بناء صندوق الوارد الخاص بك #

كل ما يحتاجه صندوق الوارد موجود في هذه الصفحة وفي جهات الاتصال:

للحصول على تحديثات مباشرة، اشترك في أحداث New Message و Replies و Human Alerted و Chat Concluded باستخدام Webhooks بدلاً من استطلاع هذه الـ API بشكل دوري.

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

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

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

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

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

• خطافات الويب (Webhooks) — احصل على تحديثات حالة التسليم بدلاً من الاستطلاع.
• جهات الاتصال — أنشئ وابحث عن جهات الاتصال التي تراسلها.
• المواعيد — احجز وأدر المواعيد لجهات اتصالك.