ساعات العمل والردود التلقائية
إعدادان لمساحة العمل يغيّران كيف تجيب المنصّة نيابة عنك: متى تكون مفتوحًا، وماذا يُقال تلقائيًا حين يكتب إليك أحد. وكلاهما يُقيَّم على الخادم بالمنطقة الزمنية لمساحة العمل نفسها.
ما الموجود هنا
أربعة مسارات، ونطاقاتها غير متماثلة — اقرأها قبل ربط أي دور. والمنطقة الزمنية التي تُقيَّم بها تعود إلى مساحة العمل لا إلى متصفح المتصل.
| Endpoint | الصلاحية |
|---|---|
| GET /v1/settings/business-hours | workspace.read |
| PUT /v1/settings/business-hours | workspace.manage |
| GET /v1/settings/auto-replies | automations.manage |
| PUT /v1/settings/auto-replies | automations.manage |
الردود التلقائية تأخذ نطاق الأتمتة
تتطلب قراءة الردود التلقائية automations.manage لا تصريح قراءة، لأن كل مفتاح منها ينشئ أتمتة حقيقية. أما ساعات العمل فتنقسم على النحو المعتاد: workspace.read للقراءة وworkspace.manage للكتابة.
ساعات العمل
| الحقل | النوع | الوصف |
|---|---|---|
| enabled | boolean | هل يُطبَّق الأسبوع أصلًا. |
| timezone | string | الساعة الوحيدة المعنيّة. وكل ما هنا يُقيَّم بها. |
| days | object<day, {from,to}[]> | الأيام المفتوحة فقط، ولكل يوم نافذة from/to واحدة أو أكثر. |
| state | "open" | "closed" | مفتوح أو مغلق الآن، والخادم هو من يقرر. |
| suggested.days | object | أسبوع مبدئي تقترحه الواجهة حين لا يوجد إعداد بعد. |
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.
ردّا الترحيب والغياب
هما أتمتتان عاديتان في العمق: كل مفتاح مُفعَّل ينشئ واحدة، بسجل تشغيلها الخاص وبالحماية نفسها من الحلقات. والحقل automation_id هو طريقك إليها.
| الحقل | النوع | الوصف |
|---|---|---|
| welcome, away | object | الردّان. أرسل أحدهما أو كليهما. |
| *.enabled | boolean | هل هذا الرد مُفعَّل. |
| *.message | string | null | النص المُرسَل. ويكون null إن لم يُضبط قط. |
| *.automation_id | string | null | الأتمتة التي أنشأها هذا المفتاح، أو null حين يكون مطفأً. |
| *.last_run_at | string | null | متى عمل آخر مرة. |
| business_hours_configured | boolean | هل توجد ساعات عمل. ولا يمكن تفعيل رد الغياب من دونها. |
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_CONFIGURED | 409 | فُعِّل رد الغياب بلا ساعات عمل مضبوطة. عطّل عنصر التحكم للتفعيل فقط — فالمفتاح المجمَّد في وضع التشغيل فخّ — وعالج الـ 409 على أي حال، لأن تبويبًا آخر قد يمسح الساعات بين تحميل الصفحة ووصول الحفظ. |
| VALIDATION_ERROR | 422 | يوم مفتوح فارغ، أو تفعيل بلا يوم مفتوح، أو وقت بصيغة خاطئة. |
| FORBIDDEN | 403 | المتصل لا يملك نطاق القراءة ولا نطاق الإدارة. |
كل رمز وحالته في صفحة الأخطاء.