إنتقل إلى المحتوى الرئيسي

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

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

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

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

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، كي تبقى القائمة سريعة في صندوق وارد كبير؛ أما محادثات جهة اتصال فتعود كاملة دائمًا. ولا تظهر في القائمة محادثة لم تصلها رسالة بعد. راجع مرجع عرض المحادثات لمعرفة المدة.

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

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

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 (جلب محادثة) حين تحتاج حالتها.

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

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

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

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

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

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 مفعّلة للوكيل، يُوقف الردُّ الذكاءَ الاصطناعي في تلك المحادثة طوال مدة الإيقاف، مثل أي رد من عضو في الفريق؛ وحين تكون متوقفة يستمر الذكاء الاصطناعي في الرد. راجع إعدادات الوكيل. وحين ينتهي الإيقاف، قد يكتب الذكاء الاصطناعي مرة أخرى إن كانت المتابعات مفعّلة لتلك القناة؛ ولمنع ذلك أوقف الذكاء الاصطناعي في المحادثة أو استأنفه. ولا يُسند الرد المحادثةَ إلى أحد أبدًا.

يكون الجواب 201 مع الرسالة بحالة queued، ثم تُرسَل فورًا وتتغيّر status تسليمها بعد ذلك؛ تابعها بقراءة الرسالة مرة أخرى بـ GET على id الخاص بها، ويذكر مرجع جلب رسالة كل الحالات. أرسل Idempotency-Key كي لا تُرسِل إعادةُ المحاولة بعد انقضاء المهلة الردَّ مرتين؛ راجع الإعادة الآمنة. وللردود حد معدّل خاص بها؛ راجع حدود المعدّل ومرجع الرد.

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

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

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

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

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

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

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

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 الخاص بالمحادثة (مرجع استئناف الذكاء الاصطناعي). ولإيقاف الذكاء الاصطناعي على قناة كاملة راجع القنوات والمتابعات.

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

أرسل PATCH بـ urgent. القيمة true هي وضع علامة عاجل في لوحة التحكم، وfalse هي تمت المعالجة. وكلاهما يُلغي needs_attention، ويجعل الحلُّ قيمةَ sentiment غير الراضية محايدة، فلا تعود المحادثة تظهر كأنها تحتاج انتباهًا. ويقرأ الذكاء الاصطناعي العلامتين من جديد مع كل رد له، فتبقى العلامة حتى يجيب الذكاء الاصطناعي في تلك المحادثة مرة أخرى. راجع مرجع تحديث محادثة.

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

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

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

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

أسئلة شائعة​

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

لا. البحث في سجل الرسائل يقرأ كل رسالة لدى الوكيل، لذا يبقى في لوحة التحكم حيث يبدؤه شخص عن قصد. أما عبر الواجهة فلا يطابق search إلا اسم العميل وآخر رسالة. وللعثور على شخص، ابحث عنه في جهات الاتصال وصفِّ المحادثات بـ contact_id.

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

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

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

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

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

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

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

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