​

Settings: Frequency Caps Console

​

1. What the console shows

• Workspace-wide default cap: A global ceiling (scope global, channel wildcard *) that limits total outbound touches across all channels combined (for example, no more than 5 total communications per contact in a rolling 24-hour window).
• Per-channel send-count caps: Channel-specific rules that limit volume on an individual channel (for example, maximum 2 SMS messages per rolling day, or 1 marketing voice call per rolling week).
• Category filters: Badges indicating whether a rule applies to all traffic or is scoped strictly to specific message categories like marketing or transactional.
• Status toggles: Controls to enable or disable rules instantly without deleting the underlying configuration.
• Counter scope: Clear indicators distinguishing contact-level limits from tenant-wide throughput backstops.

​

2. Set a cap: step-by-step form walkthrough

​

Form fields and options

1. Scope:
   • Channel-specific (channel): The limit applies only to sends on the selected channel. Select this option when creating channel-pacing rules (e.g., SMS, Voice, WhatsApp).
   • Workspace default (global): The limit aggregates touches across every active channel. When selected, the channel dropdown is disabled and stored as *.
2. Channel (required when scope is channel):
   • Choose the outbound channel: sms, whatsapp, email, voice, rcs, viber, line, messenger, instagram, push, telegram, or in_app.
   • Dual example — Voice surface: Select voice to prevent automated dialers or voice notifications from calling a contact repeatedly within a short window.
   • Dual example — Contacts messaging surface: Select sms or whatsapp to pace promotional messaging.
3. Max Sends (max_count):
   • The maximum number of permitted outbound interactions within the window (integer between 1 and 10,000).
4. Time Window (window_seconds):
   • The rolling time duration. The UI allows selecting presets or entering custom seconds:
     • 1 hour (3600)
     • 24 hours (86400)
     • 7 days (604800)
     • 30 days (2592000)
5. Applies to Categories (applies_to_categories):
   • Select categories to restrict enforcement:
     • marketing / promotional
     • transactional / alerts
   • Important: Leaving this field empty makes the rule keyless, meaning it applies to every outbound send on that channel, including one-time passwords (OTPs) and critical order updates. To protect transactional alerts from marketing throttles, explicitly select marketing.
6. Enabled:
   • Toggle switch (true/false) to activate or pause the rule.

​

Corresponding API payload

curl -X POST https://api.orbit.devotel.io/api/v1/frequency-caps/ \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "scope": "channel",
    "max_count": 2,
    "window_seconds": 86400,
    "applies_to_categories": ["marketing"],
    "enabled": true
  }'

curl -X POST https://api.orbit.devotel.io/api/v1/frequency-caps/ \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "voice",
    "scope": "channel",
    "max_count": 1,
    "window_seconds": 604800,
    "applies_to_categories": ["marketing"],
    "enabled": true
  }'

​

3. How caps interact with quiet hours and compliance overrides

1. Tenant-configured quiet hours:
   • Quiet-hours rules (configured in Settings → Compliance) determine when messages and calls can be delivered based on recipient local time.
   • If quiet hours are active, non-urgent messages are held in a scheduled queue or dropped according to your campaign settings.
   • Frequency caps determine how many sends are allowed once the quiet-hours window opens. A send deferred by quiet hours only checks and claims a frequency-cap slot when it is actually released for dispatch.
2. Compliance overrides:
   • Federal voice dialing windows: Federal statutory requirements (such as the US TCPA federal voice dialing window) are platform-enforced hard guards that block voice dials outside legal hours.
   • Tenant compliance controls: Opt-outs, consent records, and suppression lists are tenant-owned controls. When a contact opts out or is placed on a suppression list, the send-gate rejects the send at the suppression check—before reaching the frequency cap. As a result, an opted-out contact never burns a frequency-cap quota slot.

​

4. Reading the configured list

​

Contact 360 and per-contact inspection

• Open Contacts and select any contact record to view the Send Gate Status panel.
• The panel displays real-time rolling counters for that specific contact across all applicable rules:
  • Current count of sends in the active window (e.g., 1 / 2 SMS used).
  • Time remaining until the oldest in-window send rolls off (window_resets_in).
  • Cap breach status (Clear vs Capped).

​

5. Testing a cap with a deliberately flagged send

1. Set a tight test cap:
   • In /settings/frequency-caps, create a test rule: Channel: sms, Max sends: 1, Window: 3600 seconds (1 hour), Category: marketing.
2. Execute send #1 (Permitted):
   • Send an SMS to your test phone number with category: "marketing".
   • The send succeeds with HTTP 201 Created or 200 OK. The first slot in the rolling window is claimed.
3. Execute send #2 (Deliberately flagged / blocked):
   • Immediately attempt a second SMS send to the same number with category: "marketing".
   • The platform intercepts the send at the gateway and returns an HTTP 429 Too Many Requests:

{
  "error": {
    "code": "FREQUENCY_CAP_EXCEEDED",
    "message": "Send blocked by a frequency-cap rule for this recipient and channel. Try again later or raise the cap in Settings → Frequency caps.",
    "details": {
      "channel": "sms",
      "window_seconds": 3600,
      "max_count": 1,
      "cap_id": "fc_9Qx2TestRule",
      "retry_after_seconds": 3585
    }
  }
}

4. Verify non-consumption on failure:
   • The blocked send is rejected before dispatch. It does not hit carrier aggregators and does not increment counters on any secondary caps.
5. Clean up:
   • Delete or edit the test rule in /settings/frequency-caps once verified.

​

6. Console configuration vs the frequency-cap concept model

• Postgres Rule Store: The rules you view and edit in /settings/frequency-caps are stored in your tenant’s Postgres database. They represent the policy definitions (channel, window duration, quota limit, category filters).
• Redis Sliding-Window Counters: When a message or voice call is dispatched, the evaluation engine queries high-performance Redis sorted sets (ZSET). The counter key is structured by rule ID and recipient:
  freqcap:cnt:<cap_id>:<recipient-address>
  
• Atomic Slot Claims: Evaluating the cap and incrementing the counter happens atomically via Lua script. If a contact has concurrent requests in flight, the engine prevents race conditions—only sends within the quota are allowed through.
• Rule propagation: Updates made in the console propagate to the send gateway within 30 seconds as local rule caches invalidate.

​

7. Edge cases and evaluation order

​

Gate evaluation order

1. Organization Billing & Balance Check
   └── Rejects if prepaid wallet depleted or credit limit exceeded.
2. Suppression & Opt-Out Gate
   └── Rejects if recipient opted out or exists on suppression list.
3. Duplicate Content Gate
   └── Drops identical message bodies sent within deduplication window.
4. Frequency Cap Gate (Atomic Slot Claim)
   └── Rejects if contact exceeds channel-specific or global rolling count.
5. Quiet Hours & Scheduling Gate
   └── Defers non-urgent sends until local allowed sending hours.
6. Carrier Throughput / Rate Ceiling Gate
   └── Paces outbound dispatch to match provider MPS limits.

​

Key edge cases

• Overlapping Channel and Global Caps:
  • If a contact is subject to both a 2-SMS/day cap and a 5-message/day global cap, both must pass.
  • If the contact has received 2 SMS, a 3rd SMS is blocked by the channel cap, even though the global cap still has 3 slots remaining.
  • If the contact has received 2 SMS, 2 emails, and 1 WhatsApp message (total 5), a 1st voice call is blocked by the global cap, even if no voice-specific cap exists.
• Uncategorized vs Categorized Sends:
  • A cap with applies_to_categories: ["marketing"] completely ignores sends marked category: "transactional".
  • A cap with empty categories throttles all traffic on that channel, regardless of payload tags.
• Failed Provider Dispatches:
  • If a send clears the frequency-cap gate but fails at the carrier or softswitch layer (e.g., invalid phone number), the slot is not permanently lost. Two-phase verification releases or expires the slot, preventing ghost charges against the contact’s cap.
• Timezone shifts and Daylight Saving:
  • Frequency caps operate purely on elapsed rolling seconds (window_seconds), unaffected by daylight saving transitions or recipient timezones. In contrast, quiet-hours gates evaluate local wall-clock time.

​

Related guides

• Frequency Caps Concept & Model
• Frequency Caps API Reference
• Settings Overview
• Compliance & Quiet Hours