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

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

كل دردشة يجريها وكيلك مع عميل، على واتساب أو فيسبوك أو إنستجرام أو موقعك، هي محادثة. عبر الواجهة البرمجية العامة تستطيع أنظمتك قراءة المحادثات ورسائلها، والرد باسم فريقك، وإغلاقها أو أرشفتها، وإيقاف الذكاء الاصطناعي في محادثة واحدة، وتعليمها عاجلة أو محلولة، وإسنادها إلى عضو في الفريق. كل ذلك تحت `/v1/agents/{agentId}/conversations`.

## كيف أعرض محادثات الوكيل؟

اجلبها بـ `GET`، الأحدث نشاطًا أولًا. صفِّها بـ `status` أو `channel` أو `is_read` أو `urgent` أو `assigned_to` أو `contact_id`، أو بوقت آخر رسالة عبر `active_since` و`active_before`:

```bash
curl "https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/conversations?is_read=false&channel=whatsapp" \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"
```

تحمل كل محادثة آخر رسالة فيها، ومن كتبها ومتى، وهل قرأها فريقك، وعلامات الانتباه، وحالة الذكاء الاصطناعي، والمُسنَد إليه، فتعرف أيها يحتاجك دون أن تفتحها. ويجد `search` اسم العميل أو كلمة في آخر رسالة. والقائمة المصفّاة بالحالة أو القناة أو القراءة أو العجلة أو المُسنَد إليه لا تشمل إلا مدة محدودة من النشاط تنتهي عند `active_before` أو الآن، ما لم ترسل `active_since`، كي تبقى القائمة سريعة في صندوق وارد كبير؛ أما محادثات جهة اتصال فتعود كاملة دائمًا. ولا تظهر في القائمة محادثة لم تصلها رسالة بعد. راجع [مرجع عرض المحادثات](../api-reference/list-conversations) لمعرفة المدة.

## كيف أتابع الرسائل الجديدة؟

استطلع القائمة، لا كل محادثة على حدة. كل دقيقة تقريبًا، اعرض القائمة مع `active_since` قبل أحدث `last_message_at` رأيته ببضع دقائق، وتابع الصفحات ما دام `has_more` صحيحًا. لا يعود إلا ما وصلته رسالة جديدة من المحادثات. ولكل منها اقرأ رسائلها مع `after` برسالة أقدم ببضع دقائق من أحدث رسالة لديك:

```bash
curl "https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/conversations/CONVERSATION_ID/messages?after=MESSAGE_ID" \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"
```

مع `after` تأتي الرسائل الأقدم أولًا. وما دام `has_more` صحيحًا، أعد الاستدعاء مع `after` بآخر رسالة وصلتك. أبقِ القراءتين متداخلتين وتجاهل ما لديك حسب `id`: الرسالة التي يرسلها فريقك من تطبيقات واتساب أو ميتا تحمل وقت المنصة، وقد يسبق قليلًا وقت تسجيل مجيب لها، فقد تقع قبل رسائل قرأتها. والصورة أو الرسالة الصوتية أو الملصق أو الملف الذي يرسله العميل دون تعليق لا يحرّك `last_message_at`، فلا تعود المحادثة إلا حين تحرّكه رسالة لاحقة، مثل رد الذكاء الاصطناعي. ولا يعيد تغييرُ الحالة أو القراءة أو العلامات أو المُسنَد إليه المحادثةَ إلى القائمة كذلك؛ اقرأها بـ `GET` ([جلب محادثة](../api-reference/get-conversation)) حين تحتاج حالتها.

## كيف أقرأ رسائل محادثة؟

دون `after` تأتي أحدث الرسائل أولًا، ويقرأ `next_cursor` ما قبلها. وتذكر كل رسالة مرسلها: العميل، أو الذكاء الاصطناعي، أو مستخدم (عضو في الفريق، أو مفتاح يكتب باسم منشئه)، أو مجيب نيابةً عنك (رسالة جماعية، أو إرسال عبر `/v1/whatsapp`). وتحمل الرسائل المرسلة إلى العميل `status` تسليمها. وتنتهي صلاحية روابط المرفقات؛ اقرأ الرسالة مرة أخرى لرابط جديد. راجع [مرجع عرض الرسائل](../api-reference/list-conversation-messages) لمعرفة مدتها.

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

## كيف أرد على عميل؟

أرسل النص بـ `POST` إلى رسائل المحادثة:

```bash
curl -X POST https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/conversations/CONVERSATION_ID/messages \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-7f3a9c" \
  -d '{ "text": "Yes, we are open on Friday from 2 pm to 10 pm." }'
```

يصل الرد عبر قناة المحادثة باسم فريقك، ويظهر في لوحة التحكم كأن منشئ المفتاح كتبه. وحين تكون `ai_handoff_enabled` مفعّلة للوكيل، يُوقف الردُّ الذكاءَ الاصطناعي في تلك المحادثة طوال مدة الإيقاف، مثل أي رد من عضو في الفريق؛ وحين تكون متوقفة يستمر الذكاء الاصطناعي في الرد. راجع [إعدادات الوكيل](./agent-settings). وحين ينتهي الإيقاف، قد يكتب الذكاء الاصطناعي مرة أخرى إن كانت المتابعات مفعّلة لتلك القناة؛ ولمنع ذلك أوقف الذكاء الاصطناعي في المحادثة أو استأنفه. ولا يُسند الرد المحادثةَ إلى أحد أبدًا.

يكون الجواب `201` مع الرسالة بحالة `queued`، ثم تُرسَل فورًا وتتغيّر `status` تسليمها بعد ذلك؛ تابعها بقراءة الرسالة مرة أخرى بـ `GET` على `id` الخاص بها، ويذكر [مرجع جلب رسالة](../api-reference/get-conversation-message) كل الحالات. أرسل `Idempotency-Key` كي لا تُرسِل إعادةُ المحاولة بعد انقضاء المهلة الردَّ مرتين؛ راجع [الإعادة الآمنة](../idempotency). وللردود حد معدّل خاص بها؛ راجع [حدود المعدّل](../rate-limits) و[مرجع الرد](../api-reference/send-conversation-message).

## لماذا رُفض ردي؟

قبل حفظ أي شيء، يتحقق مجيب من أن الرد يستطيع الوصول إلى العميل:

- `422 messaging_window_closed`: لم يكتب العميل خلال آخر 24 ساعة. لا يوصل واتساب وفيسبوك وإنستجرام رسالتك الحرة إلا خلال 24 ساعة من آخر رسالة للعميل. وعلى واتساب أرسل قالبًا معتمدًا بدلًا منها؛ راجع [إرسال قالب واتساب](../whatsapp/send-template).
- `422 channel_not_supported`: لا يستطيع مجيب الإرسال على هذه القناة بعد (TikTok).

لا تُخزَّن استجابة الرد المرفوض مقابل `Idempotency-Key` الخاص به، ويُجيب المفتاح نفسه بـ `409 idempotency_key_in_progress` لفترة قصيرة؛ فحين يزول السبب أرسل الرد مرة أخرى بمفتاح جديد. راجع [الإعادة الآمنة](../idempotency).

ولا نافذة لدردشة الموقع: يُحفظ الرد بحالة `sent` ويظهر في الدردشة المفتوحة لدى العميل.

## كيف أوقف الذكاء الاصطناعي في محادثة واحدة؟

أرسل `PATCH` إلى المحادثة بـ `ai_enabled`:

```bash
curl -X PATCH https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/conversations/CONVERSATION_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "ai_enabled": false }'
```

يبقى الذكاء الاصطناعي متوقفًا في تلك المحادثة حتى ترسل `"ai_enabled": true`، وهو المفتاح نفسه الذي في لوحة التحكم. أما رد عضو في الفريق فيوقفه مؤقتًا فقط، ويظهر ذلك في `ai_paused_until`؛ ولإنهاء هذا الإيقاف الآن أرسل `POST` إلى `resume-ai` الخاص بالمحادثة ([مرجع استئناف الذكاء الاصطناعي](../api-reference/resume-conversation-ai)). ولإيقاف الذكاء الاصطناعي على قناة كاملة راجع [القنوات والمتابعات](./channels-and-follow-ups).

## كيف أعلّم محادثة عاجلة أو محلولة؟

أرسل `PATCH` بـ `urgent`. القيمة `true` هي **وضع علامة عاجل** في لوحة التحكم، و`false` هي **تمت المعالجة**. وكلاهما يُلغي `needs_attention`، ويجعل الحلُّ قيمةَ `sentiment` غير الراضية محايدة، فلا تعود المحادثة تظهر كأنها تحتاج انتباهًا. ويقرأ الذكاء الاصطناعي العلامتين من جديد مع كل رد له، فتبقى العلامة حتى يجيب الذكاء الاصطناعي في تلك المحادثة مرة أخرى. راجع [مرجع تحديث محادثة](../api-reference/update-conversation).

## كيف أغلق محادثة أو أؤرشفها أو أعلّمها مقروءة؟

أرسل `PATCH` بـ `status` (`open` أو `closed` أو `archived`) أو `is_read`، منفردًا أو مع حقول أخرى في الاستدعاء نفسه. و`is_read` لفريقك فقط: تعليم المحادثة مقروءة لا يرسل للعميل إشعار قراءة أبدًا. والتغيير إلى ما هو قائم أصلًا لا يكتب شيئًا. راجع [مرجع تحديث محادثة](../api-reference/update-conversation).

## كيف أُسند محادثة؟

أرسل `user_id` عضو الفريق في الحقل `assigned_to` بـ `POST` إلى `assign` الخاص بالمحادثة، أو `"assigned_to": null` لإلغاء الإسناد. يجب أن يستطيع العضو فتح الوكيل؛ اعثر عليه عبر [فريقك](./team). ويُسند العميل المحتمل المرتبط بالمحادثة معها، ويسجّل مجيب الإسناد باسم منشئ المفتاح. راجع [مرجع إسناد محادثة](../api-reference/assign-conversation).

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

### هل أستطيع البحث داخل الرسائل؟

لا. البحث في سجل الرسائل يقرأ كل رسالة لدى الوكيل، لذا يبقى في لوحة التحكم حيث يبدؤه شخص عن قصد. أما عبر الواجهة فلا يطابق `search` إلا اسم العميل وآخر رسالة. وللعثور على شخص، ابحث عنه في [جهات الاتصال](./contacts-and-leads) وصفِّ المحادثات بـ `contact_id`.

### هل أستطيع إرسال صور أو ملفات؟

ليس بعد: الردود عبر الواجهة نصية، ويذكر [مرجع الرد](../api-reference/send-conversation-message) طولها وكيف يصل الرد الطويل على كل قناة. وعلى واتساب يستطيع القالب أن يحمل صورة أو فيديو أو مستندًا في رأسه.

### هل تُحسب الردود عبر الواجهة ضمن حد الرسائل؟

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

### هل أستطيع بدء محادثة؟

ليس بهذه الاستدعاءات: لا يوجد استدعاء ينشئ محادثة. وعلى واتساب تستطيع التواصل مع العميل أولًا بقالب (راجع [إرسال قالب واتساب](../whatsapp/send-template))؛ فيصل إلى محادثته، ويبدأ محادثة جديدة إن لم تكن له محادثة بعد.

### ما النطاقات التي تحتاجها هذه الاستدعاءات؟

`conversations:read` لعرض المحادثات وقراءة الرسائل، و`conversations:write` للتغيير والإسناد والرد. ويحملها كل مفتاح اليوم؛ راجع [التوثيق](../authentication).