​

ساعات الصمت: بوابات القنوات على مستوى المؤسسة مقابل نافذة الحملة الاحتياطية

1. بوابة القناة على مستوى المؤسسة — مفاتيح تبديل لكل قناة في إعدادات المؤسسة (settings → quiet_hours.<channel>.enabled)، تُكتب عبر PUT /api/v1/settings/general وتظهر في إعدادات المؤسسة على لوحة التحكم (انظر أيضاً وضع الامتثال).
2. نافذة الحملة الاحتياطية — زوج بدء/انتهاء واحد على مستوى المؤسسة لإرسالات drip وjourney التي لا تحمل صف الحملة فيها نافذة صريحة. في لوحة التحكم: الإعدادات → حدود الحملة → ساعات الصمت الافتراضية؛ عبر API: GET/PUT /api/v1/campaigns/quiet-hours/settings.
3. نقطة نهاية المعاينة — GET /api/v1/compliance/quiet-hours/preview، فحص للقراءة فقط يجيب على سؤال «هل يمر هذا الإرسال إلى هذا المستلم الآن؟». شغّلها قبل كل طرح؛ تُفصَّل في الدليل أدناه.

​

النافذتان

​

بوابة القناة على مستوى المؤسسة لكل قناة

​

الوضع الافتراضي لكل قناة

​

استثناءان يُبقيان حركة المرور الأساسية سارية

• الموافقة الصريحة المسبقة — مع ضبط consent_overrides_quiet_hours على true (الافتراضي)، يعبر المستلم الذي لديه سجل موافقة صريحة عبر أي قناة غير صوتية. الصوت لا يأخذ هذا الاستثناء أبداً.
• مسار حركة المعاملات — الإرسالات التي يوسمها المُتصِّل كمعاملات (OTP، التنبيهات، الإشعارات الحسابية) معفاة من البوابة حتى على قناة مفعّلة. الصوت لا يأخذ هذا الاستثناء أيضاً أبداً.

​

نافذة الحملة الاحتياطية

curl https://api.orbit.devotel.io/api/v1/campaigns/quiet-hours/settings \
  -H "Authorization: Bearer $ORBIT_API_KEY"

{
  "enabled": false,
  "start_hour": null,
  "end_hour": null,
  "platform_default_start": 21,
  "platform_default_end": 9
}

curl -X PUT https://api.orbit.devotel.io/api/v1/campaigns/quiet-hours/settings \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "start_hour": 22, "end_hour": 7 }'

curl -X PUT https://api.orbit.devotel.io/api/v1/campaigns/quiet-hours/settings \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

​

حل المنطقة الزمنية للمستلم

1. إشارة recipientTimezone صريحة من المُتصِّل، عند تقديمها.
2. رمز منطقة الولايات المتحدة → منطقة زمنية IANA، لأرقام +1.
3. رمز البلد E.164 → منطقة زمنية IANA تمثيلية (أوروبا، آسيا، الأمريكتين، والأسواق المشغّلة الشائعة).
4. لمستلمي البريد الإلكتروني، المنطقة الزمنية الافتراضية للمؤسسة.
5. عندما لا يحل أي مما سبق — unknown_timezone_policy للمؤسسة (قابل للتكوين أيضاً في لوحة التحكم عند الإعدادات → الصوت):

​

استثناء TCPA الفيدرالي للصوت

​

الموافقة تتجاوز ساعات الصمت

​

الطبقات الاتحادية المصغرة TCPA

• outside_state_window — طبقة ولاية ضيّقت النافذة وهذه الساعة وقعت خارجها.
• state_blocked_day — الطبقة تحظر الاتصال في هذا اليوم من الأسبوع كلياً.

​

دليل التشغيل

1. عاين عينة من المستلمين بـ GET /api/v1/compliance/quiet-hours/preview?phone=<E.164>&channel=<channel>، مضيفاً timezone_override=<IANA> فقط عندما يحمل نظام CRM لديك إشارة أفضل مما تحله الرقم.
2. أكّد كتلة بوابة المؤسسة: GET /api/v1/settings/general واقرأ شجرة quiet_hours قبل PUT — الكتابات تُدمَج في المستوى الأعلى، لكن مفتاح quiet_hours نفسه يُستبدَل كلياً (انظر قسم الكتابة أدناه).
3. للطروح الكبيرة، راقب GET /api/v1/settings/compliance-health — تحذيراته تُرتِّب أسوأ مخالف (المرسل الأكثر احتجازاً، مجموعات الأخطاء) لتُصلِّح أولاً أكثر المسارات ضجيجاً.

​

أمثلة عملية

​

طرح كبير عند 21:05 — سلوك قائمة الاحتجاز

• المستلمون داخل النافذة يُقبَلون فوراً.
• المستلمون المحتجَزون يحصلون على 422 مع next_allowed_at؛ عاملك يُوقِفهم ويستمر بالدفعة. الدفعة نفسها لا تتوقف — الاحتجازات لكل مستلم.
• عندما تُعاد فتح نافذة كل مستلم، أعد إرسال الصف المُوقِف؛ لم تُحرَق أي خانة أثناء الاحتجاز.

curl "https://api.orbit.devotel.io/api/v1/compliance/quiet-hours/preview?phone=%2B14155551234&channel=sms" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

{
  "allowed_now": false,
  "local_hour": 21,
  "local_timezone": "America/New_York",
  "window_start_local": "08:00",
  "window_end_local": "21:00",
  "next_allowed_at": "2026-08-26T12:00:00Z",
  "reason": "outside_window",
  "channel": "sms"
}

​

مستلم صوت أمريكي غير محلول المنطقة الزمنية — fail-closed

​

تجاوز الموافقة داخل النافذة

المُتصِّل أ — سجل موافقة في الملف     → مسموح (السبب: consent_override)
المُتصِّل ب — لا سجل موافقة           → محتجَز (422 QUIET_HOURS_BLOCKED)

​

تفعيل قناة عبر API إعدادات المؤسسة

curl -X PUT https://api.orbit.devotel.io/api/v1/settings/general \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "quiet_hours": {
        "sms": { "enabled": true },
        "whatsapp": { "enabled": true, "start_hour": 9, "end_hour": 21 },
        "unknown_timezone_policy": "skip",
        "consent_overrides_quiet_hours": true
      }
    }
  }'

​

اختر وضعاً

1. اترك كل شيء معطّلاً (الافتراضي) إذا كنت تعمل خارج ولايات ساعات الصمت القضائية، أو تعالج الحدود في مكان آخر. تحفوة واحدة: صوت الحملة والمُطلِب الأمريكي يظل محظوراً بشدة — لا يمكن إيقافه.
2. مشغّل تسويق أمريكي — فعّل sms (والصوت إذا اتصلت مخصص) في بوابة المؤسسة؛ ساعات المنصة 08:00–21:00 بالتوقيت المحلي للمستلم تُطبَّق فوراً. استثناء الموافقة يُبقي المستلمين المسموحين قابلين للوصول.
3. مشغّل EU/APAC بحملات drip — اضبط احتياط الحملة على نافذتك المحلية (مثلاً 22:00 → 07:00) في الإعدادات → حدود الحملة حتى كل drip وjourney يفتقر إلى نافذته الخاصة يرسل ضمن نظامك. أضف بوابة المؤسسة لكل قناة إذا أردت أيضاً احتجاز حركة 1:1.

​

انظر أيضاً

• بوابات الإرسال — نقطة نهاية المعاينة وكومة البوابات الكاملة (DNC, RND, إيقاف الطوارئ).
• نوافذ الاتصال حسب ولاية الولايات المتحدة — أي ولايات تحمل طبقة mini-TCPA أشد وكيف يُتعقَّب الحظر إلى قانون.
• مرجع API → الامتثال — مخططات الطلب/الاستجابة الكاملة.
• اختبار A/B للحملة — كيف يمر اختيار الفائز وتجارب الاحتجاز عبر هذه البوابة وحدود التكرار لكل مُتصِّل.