تخطَّ إلى المحتوى
المحتويات
بيانات مساحة العمل

ساعات العمل والردود التلقائية

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

ما الموجود هنا

أربعة مسارات، ونطاقاتها غير متماثلة — اقرأها قبل ربط أي دور. والمنطقة الزمنية التي تُقيَّم بها تعود إلى مساحة العمل لا إلى متصفح المتصل.

Endpointالصلاحية
GET /v1/settings/business-hoursworkspace.read
PUT /v1/settings/business-hoursworkspace.manage
GET /v1/settings/auto-repliesautomations.manage
PUT /v1/settings/auto-repliesautomations.manage

الردود التلقائية تأخذ نطاق الأتمتة

تتطلب قراءة الردود التلقائية automations.manage لا تصريح قراءة، لأن كل مفتاح منها ينشئ أتمتة حقيقية. أما ساعات العمل فتنقسم على النحو المعتاد: workspace.read للقراءة وworkspace.manage للكتابة.

ساعات العمل

GET/v1/settings/business-hoursPUT/v1/settings/business-hours
الحقلالنوعالوصف
enabledbooleanهل يُطبَّق الأسبوع أصلًا.
timezonestringالساعة الوحيدة المعنيّة. وكل ما هنا يُقيَّم بها.
daysobject<day, {from,to}[]>الأيام المفتوحة فقط، ولكل يوم نافذة from/to واحدة أو أكثر.
state"open" | "closed"مفتوح أو مغلق الآن، والخادم هو من يقرر.
suggested.daysobjectأسبوع مبدئي تقترحه الواجهة حين لا يوجد إعداد بعد.
curl
curl -X PUT https://whats.azzamkh.sa/api/v1/settings/business-hours \
  -H "Authorization: Bearer $WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "timezone": "Asia/Riyadh",
    "days": {
      "sun": [{ "from": "09:00", "to": "17:00" }],
      "mon": [{ "from": "09:00", "to": "17:00" }],
      "tue": [{ "from": "09:00", "to": "13:00" },
              { "from": "16:00", "to": "19:00" }]
    }
  }'

# 200 OK — "state" is the SERVER's answer, in the workspace timezone.
# {
#   "enabled": true,
#   "timezone": "Asia/Riyadh",
#   "days": { "sun": [...], "mon": [...], "tue": [...] },
#   "state": "open",
#   "suggested": { "days": { ... } }
# }

اليوم المغلق يوم محذوف

إرسال يوم بمصفوفة فارغة يعطي 422. أرسل الأيام المفتوحة فقط. وإطفاء enabled يبقي الأسبوع ولا يمحوه، كما أن enabled: true بلا يوم مفتوح واحد يعطي 422 أيضًا.

  • لا تعد حساب state في المتصفح أبدًا. فالمتصفح يقيّم الأسبوع بمنطقته الزمنية، وهو الخطأ نفسه الذي وُجد هذا الإعداد لمنعه — كما أن أتمتة الغياب تقرأ الساعات نفسها على الخادم، فشارة محسوبة محليًا ستخالفها.
  • يجوز تكرار النوافذ داخل اليوم، فالمناوبة المقسومة عنصران في اليوم نفسه لا إعدادان.
  • الحقل suggested.days تسهيل لا قيمة حالية. ولا يُطبَّق شيء حتى ترسله بـ PUT.

ردّا الترحيب والغياب

GET/v1/settings/auto-repliesPUT/v1/settings/auto-replies

هما أتمتتان عاديتان في العمق: كل مفتاح مُفعَّل ينشئ واحدة، بسجل تشغيلها الخاص وبالحماية نفسها من الحلقات. والحقل automation_id هو طريقك إليها.

الحقلالنوعالوصف
welcome, awayobjectالردّان. أرسل أحدهما أو كليهما.
*.enabledbooleanهل هذا الرد مُفعَّل.
*.messagestring | nullالنص المُرسَل. ويكون null إن لم يُضبط قط.
*.automation_idstring | nullالأتمتة التي أنشأها هذا المفتاح، أو null حين يكون مطفأً.
*.last_run_atstring | nullمتى عمل آخر مرة.
business_hours_configuredbooleanهل توجد ساعات عمل. ولا يمكن تفعيل رد الغياب من دونها.
curl
curl -X PUT https://whats.azzamkh.sa/api/v1/settings/auto-replies \
  -H "Authorization: Bearer $WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "away": { "enabled": true, "message": "We are closed — back at 9am." }
  }'

# 200 OK
# {
#   "welcome": {
#     "enabled": false, "message": null,
#     "automation_id": null, "last_run_at": null
#   },
#   "away": {
#     "enabled": true, "message": "We are closed — back at 9am.",
#     "automation_id": "atm_...", "last_run_at": null
#   },
#   "business_hours_configured": true
# }

# Without business hours, turning "away" on is:
# 409 { "error": { "code": "BUSINESS_HOURS_NOT_CONFIGURED", ... } }

الأخطاء المهمة هنا

الرمزHTTPمتى يحدث
BUSINESS_HOURS_NOT_CONFIGURED409فُعِّل رد الغياب بلا ساعات عمل مضبوطة. عطّل عنصر التحكم للتفعيل فقط — فالمفتاح المجمَّد في وضع التشغيل فخّ — وعالج الـ 409 على أي حال، لأن تبويبًا آخر قد يمسح الساعات بين تحميل الصفحة ووصول الحفظ.
VALIDATION_ERROR422يوم مفتوح فارغ، أو تفعيل بلا يوم مفتوح، أو وقت بصيغة خاطئة.
FORBIDDEN403المتصل لا يملك نطاق القراءة ولا نطاق الإدارة.

كل رمز وحالته في صفحة الأخطاء.