المحادثات
صندوق الوارد المشترك: اقرأ المحادثات وأسندها وأغلقها وأعد فتحها.
يضم صندوق الوارد المشترك محادثة واحدة لكل عميل وقناة. عبر الواجهة البرمجية يمكنك توجيه المحادثات من أنظمتك (نظام الدعم، أو CRM، أو جدول المناوبات)، وقراءة المحادثات وإغلاقها، بينما يواصل فريقك العمل في المنصة.
كيف يعمل: صندوق الوارد والمحادثاتدورة حياة المحادثة · وجّه المحادثات إلى الشخص المناسب · اقرأ المحادثة · الرد والإغلاق · الأحداث
دورة حياة المحادثة#
| الحالة | المعنى |
|---|---|
bot | يرد تدفق أو روبوت ذكاء اصطناعي |
needs_agent | تنتظر موظفًا: حوّلها الروبوت، أو طلب العميل التحدث مع شخص |
assigned | أُسندت لعضو في الفريق لم يرد بعد |
human | يتولاها شخص |
snoozed | مؤجلة حتى snoozed_until |
resolved | مغلقة، وتُفتح تلقائيًا إن كتب العميل من جديد |
تكون open بقيمة true في كل الحالات عدا resolved، ويوضح unread هل كتب العميل منذ آخر مرة قرأ فيها أحدٌ المحادثة.
وجّه المحادثات إلى الشخص المناسب#
تكامل شائع: عندما تحتاج محادثة إلى موظف، اختر من يتولاها في نظامك ثم أسندها.
- اشترك بنقطة استقبال في
conversation.needs_agent. - اختر عضوًا من
GET /members(لا يُسند للمشاهدين). - أسند المحادثة عبر
POST /conversations/{id}/assign:
{ "member_id": "usr_41" }يجب أن يملك العضو صلاحية على رقم المحادثة أو حسابها، وإلا فالرد هو assignee_invalid بدل محادثة لا يستطيع أحد فتحها.
اقرأ المحادثة#
- يبني
GET /conversationsمع عوامل التصفية أي طابور تريده:open=true&assignee=noneتعني كل ما ينتظر من يتولاه، وcustomer=0501234567تجد محادثة عميل واحد. - يُرجع
GET /conversations/{id}/messagesالرسائل في الاتجاهين، الأحدث أولًا. لا تُضمَّن الملاحظات الداخلية بين الموظفين أبدًا.
الرد والإغلاق#
رد عبر POST /messages بإرسال to إلى customer.address للمحادثة (ومعه channel لإنستغرام أو ماسنجر). يظهر الرد في المحادثة داخل المنصة كأي رد آخر.
أغلق عبر POST /conversations/{id}/resolve، وأعد الفتح عبر POST /conversations/{id}/reopen (دون إسناد، أو إلى member_id). يُسجَّل كل إجراء تتخذه في سجل المحادثة باسم الواجهة البرمجية مع المفتاح الذي نفذه.
الأحداث#
| الحدث | متى |
|---|---|
conversation.created | بدأ عميل محادثة جديدة |
conversation.needs_agent | تنتظر موظفًا |
conversation.assigned | أُسندت (من شخص أو قاعدة أو عبر الواجهة) |
conversation.resolved | أُغلقت |
conversation.reopened | عادت محادثة مغلقة إلى النشاط |
يستمر وصول message.received مع كل رسالة من العميل، فتستطيع عكس المحادثة في أداتك.
نقاط الواجهة
عرض المحادثات
https://api.saei.automize.sa/v1/conversations- الصلاحية:
conversations:read - لمفاتيح التشغيل فقط
محادثات صندوق الوارد المشترك، الأحدث أولًا، على واتساب وإنستغرام وماسنجر. استخدم عوامل التصفية لبناء طابورك: open=true&assignee=none تعني كل ما ينتظر من يتولاه.
معاملات الاستعلام
limitintegerاختياريعدد العناصر المطلوبة، من 1 إلى 100.
cursorstringاختياريقيمة
next_cursorمن الصفحة السابقة.openbooleanاختياريtrueللمحادثات غير المغلقة، وfalseللمغلقة.statestringاختياريإحدى القيم
botneeds_agentassignedhumanresolvedsnoozedchannelstringاختياريإحدى القيم
whatsappinstagrammessengerassigneestringاختياريمعرّف عضو (
usr_…)، أوnoneلغير المُسندة.customerstringاختياريهاتف العميل (بأي صيغة) أو معرّفه في إنستغرام أو ماسنجر.
unreadbooleanاختياري
حقول الاستجابة200· صفحة من المحادثات.
object"list"مطلوبdataarray<Conversation>مطلوبالحقول الفرعية (17)
idstringمطلوبobject"conversation"مطلوبchannelstringمطلوبإحدى القيم
whatsappinstagrammessengercustomerobjectمطلوبالحقول الفرعية (3)
contact_idstring | nullاختياريaddressstringاختياريالهاتف (E.164) في واتساب، ومعرّف العميل في إنستغرام وماسنجر. أرسل الردود إلى هذا العنوان عبر
to.namestring | nullاختياري
number_idstring | nullاختياريstatestringمطلوبbotتتولاها الأتمتة،needs_agentتنتظر موظفًا،assignedأُسندت لشخص لم يرد بعد،humanيتولاها شخص،snoozedمؤجلة حتىsnoozed_until،resolvedمغلقة.إحدى القيم
botneeds_agentassignedhumanresolvedsnoozedopenbooleanمطلوبassigneeobject | nullاختياريالحقول الفرعية (2)
idstringاختياريnamestring | nullاختياري
unreadbooleanاختياريlabelstring | nullاختياريlast_customer_message_atstring | nullاختياريlast_agent_message_atstring | nullاختياريreply_window_expires_atstring | nullاختياريبعد هذا الوقت لا يصل العميل إلا قالب معتمد (واتساب)، أو لا شيء حتى يكتب هو (إنستغرام وماسنجر).
resolved_atstring | nullاختياريsnoozed_untilstring | nullاختياريcreated_atstring | nullاختياريupdated_atstring | nullاختياري
has_morebooleanمطلوبnext_cursorstring | nullمطلوب
الأخطاء المحتملة3
- 403test_mode_unsupportedغير متاح في وضع الاختبار
- 422parameter_invalidحقل غير صالح
- 429rate_limitedطلبات كثيرة
جرّبها
curl -X GET https://api.saei.automize.sa/v1/conversations \
-H "Authorization: Bearer $API_KEY"صفحة من المحادثات.
{
"object": "list",
"data": [
{
"id": "conv_311",
"object": "conversation",
"channel": "whatsapp",
"customer": {
"contact_id": "string",
"address": "string",
"name": "string"
},
"number_id": "string",
"state": "bot",
"open": false,
"assignee": {
"id": "string",
"name": "string"
},
"unread": false,
"label": "string",
"last_customer_message_at": "2026-10-01T09:30:00Z",
"last_agent_message_at": "2026-10-01T09:30:00Z",
"reply_window_expires_at": "2026-10-01T09:30:00Z",
"resolved_at": "2026-10-01T09:30:00Z",
"snoozed_until": "2026-10-01T09:30:00Z",
"created_at": "2026-10-01T09:30:00Z",
"updated_at": "2026-10-01T09:30:00Z"
}
],
"has_more": false,
"next_cursor": "string"
}جلب محادثة
https://api.saei.automize.sa/v1/conversations/{id}- الصلاحية:
conversations:read - لمفاتيح التشغيل فقط
معاملات المسار
idstringمطلوبمعرّف العنصر.
حقول الاستجابة200· المحادثة.
idstringمطلوبobject"conversation"مطلوبchannelstringمطلوبإحدى القيم
whatsappinstagrammessengercustomerobjectمطلوبالحقول الفرعية (3)
contact_idstring | nullاختياريaddressstringاختياريالهاتف (E.164) في واتساب، ومعرّف العميل في إنستغرام وماسنجر. أرسل الردود إلى هذا العنوان عبر
to.namestring | nullاختياري
number_idstring | nullاختياريstatestringمطلوبbotتتولاها الأتمتة،needs_agentتنتظر موظفًا،assignedأُسندت لشخص لم يرد بعد،humanيتولاها شخص،snoozedمؤجلة حتىsnoozed_until،resolvedمغلقة.إحدى القيم
botneeds_agentassignedhumanresolvedsnoozedopenbooleanمطلوبassigneeobject | nullاختياريالحقول الفرعية (2)
idstringاختياريnamestring | nullاختياري
unreadbooleanاختياريlabelstring | nullاختياريlast_customer_message_atstring | nullاختياريlast_agent_message_atstring | nullاختياريreply_window_expires_atstring | nullاختياريبعد هذا الوقت لا يصل العميل إلا قالب معتمد (واتساب)، أو لا شيء حتى يكتب هو (إنستغرام وماسنجر).
resolved_atstring | nullاختياريsnoozed_untilstring | nullاختياريcreated_atstring | nullاختياريupdated_atstring | nullاختياري
الأخطاء المحتملة3
- 403test_mode_unsupportedغير متاح في وضع الاختبار
- 404resource_missingغير موجود
- 429rate_limitedطلبات كثيرة
جرّبها
curl -X GET https://api.saei.automize.sa/v1/conversations/conv_311 \
-H "Authorization: Bearer $API_KEY"المحادثة.
{
"id": "conv_311",
"object": "conversation",
"channel": "whatsapp",
"customer": {
"contact_id": "ct_1052",
"address": "+966501234567",
"name": "سارة القحطاني"
},
"number_id": "num_3",
"state": "assigned",
"open": true,
"assignee": {
"id": "usr_41",
"name": "نورة العتيبي"
},
"unread": true,
"label": "شكوى",
"last_customer_message_at": "2026-10-01T09:29:10Z",
"last_agent_message_at": "2026-10-01T09:20:00Z",
"reply_window_expires_at": "2026-10-02T09:29:10Z",
"resolved_at": null,
"snoozed_until": null,
"created_at": "2026-09-28T14:00:00Z",
"updated_at": "2026-10-01T09:29:10Z"
}إسناد محادثة
https://api.saei.automize.sa/v1/conversations/{id}/assign- الصلاحية:
conversations:write - لمفاتيح التشغيل فقط
يسند المحادثة إلى عضو في الفريق. يجب أن يملك صلاحية على رقمها أو حسابها، ولا يُسند للمشاهدين.
معاملات المسار
idstringمطلوبمعرّف العنصر.
جسم الطلب
member_idstringمطلوبمن
GET /v1/members.
حقول الاستجابة200· المحادثة بعد الإسناد.
idstringمطلوبobject"conversation"مطلوبchannelstringمطلوبإحدى القيم
whatsappinstagrammessengercustomerobjectمطلوبالحقول الفرعية (3)
contact_idstring | nullاختياريaddressstringاختياريالهاتف (E.164) في واتساب، ومعرّف العميل في إنستغرام وماسنجر. أرسل الردود إلى هذا العنوان عبر
to.namestring | nullاختياري
number_idstring | nullاختياريstatestringمطلوبbotتتولاها الأتمتة،needs_agentتنتظر موظفًا،assignedأُسندت لشخص لم يرد بعد،humanيتولاها شخص،snoozedمؤجلة حتىsnoozed_until،resolvedمغلقة.إحدى القيم
botneeds_agentassignedhumanresolvedsnoozedopenbooleanمطلوبassigneeobject | nullاختياريالحقول الفرعية (2)
idstringاختياريnamestring | nullاختياري
unreadbooleanاختياريlabelstring | nullاختياريlast_customer_message_atstring | nullاختياريlast_agent_message_atstring | nullاختياريreply_window_expires_atstring | nullاختياريبعد هذا الوقت لا يصل العميل إلا قالب معتمد (واتساب)، أو لا شيء حتى يكتب هو (إنستغرام وماسنجر).
resolved_atstring | nullاختياريsnoozed_untilstring | nullاختياريcreated_atstring | nullاختياريupdated_atstring | nullاختياري
الأخطاء المحتملة6
- 403test_mode_unsupportedغير متاح في وضع الاختبار
- 422parameter_missingحقل مفقود
- 404resource_missingغير موجود
- 409state_conflictغير مسموح في الحالة الحالية
- 422assignee_invalidلا يمكن إسناد المحادثة لهذا العضو
- 429rate_limitedطلبات كثيرة
جرّبها
curl -X POST https://api.saei.automize.sa/v1/conversations/conv_311/assign \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"member_id": "usr_41"
}'المحادثة بعد الإسناد.
{
"id": "conv_311",
"object": "conversation",
"channel": "whatsapp",
"customer": {
"contact_id": "string",
"address": "string",
"name": "string"
},
"number_id": "string",
"state": "bot",
"open": false,
"assignee": {
"id": "string",
"name": "string"
},
"unread": false,
"label": "string",
"last_customer_message_at": "2026-10-01T09:30:00Z",
"last_agent_message_at": "2026-10-01T09:30:00Z",
"reply_window_expires_at": "2026-10-01T09:30:00Z",
"resolved_at": "2026-10-01T09:30:00Z",
"snoozed_until": "2026-10-01T09:30:00Z",
"created_at": "2026-10-01T09:30:00Z",
"updated_at": "2026-10-01T09:30:00Z"
}عرض رسائل محادثة
https://api.saei.automize.sa/v1/conversations/{id}/messages- الصلاحية:
conversations:read - لمفاتيح التشغيل فقط
كل رسائل المحادثة في الاتجاهين، الأحدث أولًا. لا تُضمَّن الملاحظات الداخلية بين الموظفين أبدًا.
معاملات المسار
idstringمطلوبمعرّف العنصر.
معاملات الاستعلام
limitintegerاختياريعدد العناصر المطلوبة، من 1 إلى 100.
cursorstringاختياريقيمة
next_cursorمن الصفحة السابقة.
حقول الاستجابة200· صفحة من الرسائل.
object"list"مطلوبdataarray<Message>مطلوبالحقول الفرعية (28)
idstringمطلوبمعرّف فريد. عامله كنص معتم وخزّنه كنص حتى 64 حرفًا.
object"message"مطلوبlivemodebooleanمطلوبdirectionstringمطلوبoutboundللرسائل التي ترسلها، وinboundلرسائل العملاء.إحدى القيم
outboundinboundchannelstringمطلوبإحدى القيم
whatsappinstagrammessengerfromstring | nullاختياريالمُرسِل، بصيغة E.164 في واتساب.
tostring | nullاختياريالمُستلِم، بصيغة E.164 في واتساب.
typestringمطلوبنوع محتوى الرسالة.
textobjectاختياريالحقول الفرعية (1)
bodystringاختياري
templateobjectاختياريالحقول الفرعية (4)
namestringاختياريlanguagestringاختياريvariablesobjectاختياريbodystringاختياري
imageobjectاختياريرسائل الوسائط تحمل
link(أوmedia_id) وcaptionوfilenameوmime_typeعند توفرها.videoobjectاختياريaudioobjectاختياريdocumentobjectاختياريstickerobjectاختياريlocationobjectاختياريcontactsarrayاختياريinteractiveobjectاختياريما أرسلته (
typeوbodyوbuttons…)، أو عند ضغط العميل:reply: {id, title}.reactionobjectاختياريstatusstringمطلوبaccepted←sent←delivered←read، أوfailed. رسائل العملاء حالتهاreceived. تصلك تغيّرات الحالة كأحداث ويب هوك.إحدى القيم
acceptedsentdeliveredreadfailedreceivederrorobject | nullاختياريسبب فشل التسليم، عندما تكون
statusهيfailed.الحقول الفرعية (3)
codestring | nullاختياريtitlestring | nullاختياريmessagestring | nullاختياري
referencestring | nullاختياريمرجعك الخاص، يُعاد كما أرسلته في طلب الإرسال وفي كل حدث.
conversation_idstring | nullاختياريprovider_message_idstring | nullاختياريمعرّف الرسالة لدى واتساب (wamid).
contactobject | nullاختياريالحقول الفرعية (1)
namestring | nullاختياري
contextobject | nullاختياريفي الرد، الرسالة التي يُرَد عليها.
الحقول الفرعية (1)
provider_message_idstringاختياري
created_atstring | nullمطلوبupdated_atstring | nullاختياري
has_morebooleanمطلوبnext_cursorstring | nullمطلوب
الأخطاء المحتملة3
- 403test_mode_unsupportedغير متاح في وضع الاختبار
- 404resource_missingغير موجود
- 429rate_limitedطلبات كثيرة
جرّبها
curl -X GET https://api.saei.automize.sa/v1/conversations/conv_311/messages \
-H "Authorization: Bearer $API_KEY"صفحة من الرسائل.
{
"object": "list",
"data": [
{
"id": "msg_48213",
"object": "message",
"livemode": false,
"direction": "outbound",
"channel": "whatsapp",
"from": "+966112345678",
"to": "+966501234567",
"type": "text",
"text": {
"body": "string"
},
"template": {
"name": "string",
"language": "string",
"variables": {},
"body": "string"
},
"image": {},
"video": {},
"audio": {},
"document": {},
"sticker": {},
"location": {},
"contacts": [],
"interactive": {},
"reaction": {},
"status": "accepted",
"error": {
"code": "string",
"title": "string",
"message": "string"
},
"reference": "string",
"conversation_id": "string",
"provider_message_id": "string",
"contact": {
"name": "string"
},
"context": {
"provider_message_id": "string"
},
"created_at": "2026-10-01T09:30:00Z",
"updated_at": "2026-10-01T09:30:00Z"
}
],
"has_more": false,
"next_cursor": "string"
}إعادة فتح محادثة
https://api.saei.automize.sa/v1/conversations/{id}/reopen- الصلاحية:
conversations:write - لمفاتيح التشغيل فقط
يعيد فتح محادثة مغلقة، غير مُسندة في طابور الفريق، أو مُسندة إلى member_id.
معاملات المسار
idstringمطلوبمعرّف العنصر.
جسم الطلب
member_idstring | nullاختياري
حقول الاستجابة200· المحادثة بعد إعادة الفتح.
idstringمطلوبobject"conversation"مطلوبchannelstringمطلوبإحدى القيم
whatsappinstagrammessengercustomerobjectمطلوبالحقول الفرعية (3)
contact_idstring | nullاختياريaddressstringاختياريالهاتف (E.164) في واتساب، ومعرّف العميل في إنستغرام وماسنجر. أرسل الردود إلى هذا العنوان عبر
to.namestring | nullاختياري
number_idstring | nullاختياريstatestringمطلوبbotتتولاها الأتمتة،needs_agentتنتظر موظفًا،assignedأُسندت لشخص لم يرد بعد،humanيتولاها شخص،snoozedمؤجلة حتىsnoozed_until،resolvedمغلقة.إحدى القيم
botneeds_agentassignedhumanresolvedsnoozedopenbooleanمطلوبassigneeobject | nullاختياريالحقول الفرعية (2)
idstringاختياريnamestring | nullاختياري
unreadbooleanاختياريlabelstring | nullاختياريlast_customer_message_atstring | nullاختياريlast_agent_message_atstring | nullاختياريreply_window_expires_atstring | nullاختياريبعد هذا الوقت لا يصل العميل إلا قالب معتمد (واتساب)، أو لا شيء حتى يكتب هو (إنستغرام وماسنجر).
resolved_atstring | nullاختياريsnoozed_untilstring | nullاختياريcreated_atstring | nullاختياريupdated_atstring | nullاختياري
الأخطاء المحتملة4
- 403test_mode_unsupportedغير متاح في وضع الاختبار
- 404resource_missingغير موجود
- 409state_conflictغير مسموح في الحالة الحالية
- 429rate_limitedطلبات كثيرة
جرّبها
curl -X POST https://api.saei.automize.sa/v1/conversations/conv_311/reopen \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"member_id": "usr_41"
}'المحادثة بعد إعادة الفتح.
{
"id": "conv_311",
"object": "conversation",
"channel": "whatsapp",
"customer": {
"contact_id": "string",
"address": "string",
"name": "string"
},
"number_id": "string",
"state": "bot",
"open": false,
"assignee": {
"id": "string",
"name": "string"
},
"unread": false,
"label": "string",
"last_customer_message_at": "2026-10-01T09:30:00Z",
"last_agent_message_at": "2026-10-01T09:30:00Z",
"reply_window_expires_at": "2026-10-01T09:30:00Z",
"resolved_at": "2026-10-01T09:30:00Z",
"snoozed_until": "2026-10-01T09:30:00Z",
"created_at": "2026-10-01T09:30:00Z",
"updated_at": "2026-10-01T09:30:00Z"
}إغلاق محادثة
https://api.saei.automize.sa/v1/conversations/{id}/resolve- الصلاحية:
conversations:write - لمفاتيح التشغيل فقط
يغلق المحادثة. إن كتب العميل مرة أخرى تُفتح تلقائيًا ويصلك حدث conversation.reopened.
معاملات المسار
idstringمطلوبمعرّف العنصر.
حقول الاستجابة200· المحادثة بعد الإغلاق.
idstringمطلوبobject"conversation"مطلوبchannelstringمطلوبإحدى القيم
whatsappinstagrammessengercustomerobjectمطلوبالحقول الفرعية (3)
contact_idstring | nullاختياريaddressstringاختياريالهاتف (E.164) في واتساب، ومعرّف العميل في إنستغرام وماسنجر. أرسل الردود إلى هذا العنوان عبر
to.namestring | nullاختياري
number_idstring | nullاختياريstatestringمطلوبbotتتولاها الأتمتة،needs_agentتنتظر موظفًا،assignedأُسندت لشخص لم يرد بعد،humanيتولاها شخص،snoozedمؤجلة حتىsnoozed_until،resolvedمغلقة.إحدى القيم
botneeds_agentassignedhumanresolvedsnoozedopenbooleanمطلوبassigneeobject | nullاختياريالحقول الفرعية (2)
idstringاختياريnamestring | nullاختياري
unreadbooleanاختياريlabelstring | nullاختياريlast_customer_message_atstring | nullاختياريlast_agent_message_atstring | nullاختياريreply_window_expires_atstring | nullاختياريبعد هذا الوقت لا يصل العميل إلا قالب معتمد (واتساب)، أو لا شيء حتى يكتب هو (إنستغرام وماسنجر).
resolved_atstring | nullاختياريsnoozed_untilstring | nullاختياريcreated_atstring | nullاختياريupdated_atstring | nullاختياري
الأخطاء المحتملة4
- 403test_mode_unsupportedغير متاح في وضع الاختبار
- 404resource_missingغير موجود
- 409state_conflictغير مسموح في الحالة الحالية
- 429rate_limitedطلبات كثيرة
جرّبها
curl -X POST https://api.saei.automize.sa/v1/conversations/conv_311/resolve \
-H "Authorization: Bearer $API_KEY"المحادثة بعد الإغلاق.
{
"id": "conv_311",
"object": "conversation",
"channel": "whatsapp",
"customer": {
"contact_id": "string",
"address": "string",
"name": "string"
},
"number_id": "string",
"state": "bot",
"open": false,
"assignee": {
"id": "string",
"name": "string"
},
"unread": false,
"label": "string",
"last_customer_message_at": "2026-10-01T09:30:00Z",
"last_agent_message_at": "2026-10-01T09:30:00Z",
"reply_window_expires_at": "2026-10-01T09:30:00Z",
"resolved_at": "2026-10-01T09:30:00Z",
"snoozed_until": "2026-10-01T09:30:00Z",
"created_at": "2026-10-01T09:30:00Z",
"updated_at": "2026-10-01T09:30:00Z"
}عرض أعضاء الفريق
https://api.saei.automize.sa/v1/members- الصلاحية:
conversations:read - يعمل في وضع الاختبار
أعضاء مساحة العمل لإسناد المحادثات إليهم. المشاهدون يطّلعون على صندوق الوارد لكن لا تُسند إليهم محادثات.
معاملات الاستعلام
rolestringاختياريإحدى القيم
owneradmineditorviewercustomer_service
حقول الاستجابة200· كل الأعضاء.
object"list"مطلوبdataarray<Member>مطلوبالحقول الفرعية (5)
idstringمطلوبobject"member"مطلوبnamestring | nullاختياريemailstring | nullاختياريrolestringمطلوبإحدى القيم
owneradmineditorviewercustomer_service
has_morebooleanمطلوبnext_cursorstring | nullمطلوب
الأخطاء المحتملة2
- 422parameter_invalidحقل غير صالح
- 429rate_limitedطلبات كثيرة
جرّبها
curl -X GET https://api.saei.automize.sa/v1/members \
-H "Authorization: Bearer $API_KEY"كل الأعضاء.
{
"object": "list",
"data": [
{
"id": "usr_41",
"object": "member",
"name": "نورة العتيبي",
"email": "noura@example.com",
"role": "customer_service"
}
],
"has_more": false,
"next_cursor": null
}