ضبط صناديق البريد

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

نشرح في هذا المقال كيفية ضبط صناديق البريد باستخدام واجهة زيتون البرمجية، ولتطبيق الأمثلة، سنفترض وجود مركز مساعدة على النطاق example.com، ومفتاح الواجهة البرمجية لزيتون مخزّن ضمن المتغير TOKEN$ لاستخدامه في الطلبات المختلفة.

export TOKEN="YOUR_API_KEY"

عرض صناديق البريد

لعرض كافة صناديق البريد في مركز المساعدة نرسل طلب GET إلى نقطة الوصول List all inboxes، ويمكن تصفية الصناديق المعروضة من خلال تمرير المعايير المطلوبة في معاملات الطلب.

كافة الصناديق

لعرض كافة صناديق البريد في مركز المساعدة نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/inboxes" \
     -H "Authorization: Bearer @TOKEN"    

صناديق محددة

لعرض صناديق البريد العائدة المنشأة قبل تاريخ محدد وليكن 2025/04/01، مع إظهارها بترتيب تنازلي تبعًا للقيمة sort نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/inboxes?before[created_at]=2025-04-01T00%3A00%3A00&sort=sort.desc" \
     -H "Authorization: Bearer @TOKEN" \
     --globoff

إضافة صندوق

يمكننا إنشاء صندوق بريد جديد لاستقبال المحادثات وضبط كافة خياراته من خلال إرسال طلب POST لنقطة الوصول Update or create an inbox.

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

صندوق واحد

لإنشاء صندوق بريد جديد باستخدام نقطة الوصول Create an inbox نكتب الطلب على النحو التالي:

curl "https://example.com/api/agent/v1/inboxes" \
     -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer @TOKEN" \
     -d '{
         "name": "your_inbox_name",
         "description": "your_inbox_description",
         "slug": "your-inbox-slug",
         "send_autoresponse": true,
         "autoresponse_text": "your_autoresponse_text",
         "send_rating_request": true,
         "rating_message": "your_rating_message"
     }'

ولإنشاء صندوق بريد جديد باستخدام نقطة الوصول Update or create an inbox نكتب الطلب على النحو التالي:

curl "https://example.com/api/agent/v1/inboxes/save" \
     -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer @TOKEN" \
     -d '{
         "name": "new_inbox_name",
         "description": "new_inbox_description",
         "slug": "new-inbox",
         "sort": 6,
         "send_autoresponse": true,
         "autoresponse_text": "your_autoresponse_text",
         "emails": [
             {"email": "support1@example.com", "status": "primary"},
             {"email": "support2@exampel.com", "status": "secondary"}
         ],
         "send_rating_request": true,
         "rating_message": "your_rating_message",
         "team_ids": [109, 1009],
         "agent_ids": [1008]
     }'

إضافة حالات لصندوق

عند إنشاء صندوق بريد جديد، ستكون حالات المحادثات ضمنه إما مفتوحة open أو مغلقة closed. ويمكن إنشاء حالات إضافية وتخصيصها بإرسال طلب POST لنقطة الوصول Create a conversation status.

حالة جديدة

لإنشاء حالة جديدة ضمن الصندوق رقم 1010 باسم "مؤجلة" نكتب الطلب على النحو التالي:

curl "https://example.com/api/agent/v1/conversation-statuses" \
     -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer @TOKEN" \
     -d '{
          "inbox_id": 1010,
          "name": "مؤجلة",
          "color": "#eeeeee",
          "sort": 4
     }'

إضافة بريد لصندوق

لإضافة بريد إلكتروني لصندوق، نرسل طلب POST لنقطة الوصول Add an inbox email مع تمرير الرقم التعريفي لصندوق البريد المطلوب ضمن عنوان الطلب.

بريد واحد

لإضافة بريد إلكتروني جديد new_email@example.com للصندوق رقم 1010 نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/inboxes/1010/emails" \
     -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer @TOKEN" \
     -d '{
          "email": "new_email@example.com",
          "status": "secondary"
     }'

إضافة وكيل لصندوق

يمكننا منح أحد الوكلاء صلاحيات الوصول لصندوق بريد معين من خلال إرسال طلب POST إلى نقطة الوصول Add an inbox agent ، مع تمرير الرقم التعريفي للصندوق كمعامل في عنوان الطلب، والرقم التعريفي للوكيل في جسم الطلب.

وكيل واحد

يضيف المثال التالي الوكيل رقم 1008 إلى صندوق البريد رقم 1010:

curl  "https://example.com/api/agent/v1/inboxes/1010/agents" \
     -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer @TOKEN" \
     -d '{
         "agent_id": "1008"
     }'

إضافة فريق عمل لصندوق

لإضافة فريق عمل لصندوق بريد معين نرسل طلب POST لنقطة الوصول Add an inbox team مع تمرير رقم الصندوق المطلوب في عنوان الطلب، ورقم الفريق في جسم الطلب.

فريق واحد

لإضافة فريق عمل رقم 1009 لصندوق بريد رقم 1010، نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/inboxes/1010/teams" \
     -X POST 
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer @TOKEN" \
     -d '{
         "team_id": 1009
     }'

تعديل الصندوق

يمكن تعديل أي صندوق بريد وتخصيصه بالطريقة التي تناسبنا باستخدام أكثر من نقطة وصول في الواجهة البرمجية، حيث يمكن إرسال طلب PUT إلى نقطة الوصول Update an inbox لتعديل الخصائص الأساسية لصندوق البريد في مركز المساعدة من خلال تمريرها في جسم الطلب.

كما يمكن إرسال طلب من نوع POST لنقطة الوصول Update or create an inbox لتعديل كافة خصائص صندوق البريد، مع تمرير الرقم التعريفي للصندوق في عنوان الطلب.

خصائص أساسية

لنفترض أن لدينا صندوق بريد له الرقم التعريفي 1010ونريد تعديل اسمه ليصبح new_inbox_name مع تعطيل ميزتي الرد التلقائي وتقييم المحادثات الواردة له، سنكتب الطلب كما يلي:

curl "https://example.com/api/agent/v1/inboxes/1010" \
     -X PUT \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer @TOKEN" \
     -d '{
         "name": "new_inbox_name",
         "slug": "new_inbox_slug",
         "sort": 6,
         "send_rating_request": false,
         "send_autoresponse": false
     }'

خصائص متقدمة

لتعديل بعض الخصائص المتقدمة لصندوق البريد رقم 1010 الذي أنشأناه سابقًا، كتعديل الاسم اللطيف slug، ونص الرد التلقائي، وإيقاف ميزة تقييم محادثاته، وإضافة فريق جديد له الرقم التعريفي 19 نكتب الطلب كما يلي:

curl -X POST "https://example.com/api/agent/v1/inboxes/save" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer @TOKEN" \
     -d '{
         "id": 1010,
         "name": "new_inbox_name",
         "slug": "new_inbox_slug",
         "send_autoresponse": true,
         "autoresponse_text": "your_new_text",
         "send_rating_request": false,
         "team_ids": [19, 109, 1009]
     }'

تعديل بريد صندوق

لتعديل البريد الإلكتروني المرتبط بصندوق بريد معين، سواء تعديل عنوانه أو حالته، نرسل طلب PUT لنقطة الوصول Update an inbox email.

بريد واحد

لنفترض أننا ارتكبنا خطأ املائي بكتابة عنوان البريد الإلكتروني رقم 1017 الخاص بالصندوق رقم 1010 ونريد تعديله، سنكتب الطلب كما يلي:

curl -X PUT "https://example.com/api/agent/v1/inboxes/1010/emails/1017" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer @TOKEN" \
     -d '{
         "email": "updated_email@example.com"
     }'

حذف صندوق

لحذف أي صندوق بريد من مركز المساعدة نرسل طلب من نوع DELETE إلى نقطة الوصول Delete an inbox مع تمرير الرقم التعريفي للصندوق المُراد حذفه ضمن عنوان الطلب. وننوه لأنه عند حذف صندوق بريد، لن يلغى الوصول إلى المحادثات الخاصة بالصندوق. حيث سيُحتَفظ بها لتوفير إمكانية تعديلها أو نقلها إلى صندوق آخر.

صندوق واحد

لحذف صندوق البريد رقم 1010 مع جميع رسائله من مركز المساعدة نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/inboxes/1010" \
     -X DELETE 
     -H "Authorization: Bearer @TOKEN"

حذف بريد من صندوق

لحذف البريد الإلكتروني المرتبطة بصندوق بريد معين، نرسل طلب DELETE لنقطة الوصول Delete an inbox email مع تمرير رقم البريد ورقم الصندوق كمعاملات ضمن عنوان الطلب.

بريد واحد

لنحذف عنوان البريد الإلكتروني رقم 1017 من صندوق البريد رقم 1010 نكتب الطلب التالي:

curl  "https://example.com/api/agent/v1/inboxes/1010/emails/1017"
     -X DELETE \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer @TOKEN' \

حذف وكيل من صندوق

لحذف أحد الوكلاء من صندوق البريد نرسل طلب من نوع DELETE إلى نقطة الوصول Delete an inbox agent مع تمرير كل من رقم صندوق البريد، ورقم الوكيل كمعاملات مسار ضمن عنوان الطلب.

وكيل واحد

يحذف الطلب التالي الوكيل رقم 1008 من صندوق البريد رقم 1010:

curl "https://example.com/api/agent/v1/inboxes/1010/agents/1008" \
     -X DELETE \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer @TOKEN"

حذف فريق عمل من صندوق

لحذف فريق العمل من صندوق بريد، أو سحب الصلاحية منه نرسل طلب DELETE لنقطة الوصول Delete an inbox team مع تمرير كل من رقم الصندوق، ورقم فريق العمل في عنوان الطلب.

فريق واحد

لحذف فريق العمل رقم 1009 من صندوق البريد رقم 1010، نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/inboxes/1010/teams/1009" \
     -X DELETE \
     -H "Authorization: Bearer @TOKEN"