> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings: Frequency Caps Console Walkthrough

> Walkthrough of the Orbit Frequency Caps settings console (/settings/frequency-caps): configure per-channel and workspace send limits, inspect contact-level counters, and manage send-gate evaluation order.

# Settings: Frequency Caps Console

The **Frequency Caps** console in Orbit (`/settings/frequency-caps`) controls outbound send pacing across channels and contacts. It prevents over-messaging by enforcing rolling-window message limits at the gateway layer before traffic reaches carrier networks or voice trunks.

Every rule defined in this console applies centrally across campaigns, automated journeys, customer support replies, and direct API calls.

***

## 1. What the console shows

When you navigate to **Settings → Frequency Caps**, the console displays the tenant's active frequency-cap policies and workspace defaults:

* **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

To create a new frequency cap, click **Add Frequency Cap** in the top right corner of `/settings/frequency-caps`. The console presents a modal that maps directly to the `POST /api/v1/frequency-caps/` API endpoint.

### 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

Submitting the form executes an authenticated API request:

```bash theme={null}
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
  }'
```

For voice pacing:

```bash theme={null}
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

Orbit evaluates multiple outbound send gates before dispatching a message or initiating a call. Frequency caps operate in harmony with quiet hours and compliance rules:

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

The main table on `/settings/frequency-caps` lists all active and inactive rules for your organization:

| Channel / Scope | Quota & Window | Categories | Status | Actions |
| :- | :- | :- | :- | :- |
| **Global (`*`)** | 5 sends / 24 hours | All categories | Active | Edit, Pause, Delete |
| **SMS** | 2 sends / 24 hours | `marketing` | Active | Edit, Pause, Delete |
| **Voice** | 1 call / 7 days | `marketing` | Active | Edit, Pause, Delete |
| **WhatsApp** | 3 sends / 48 hours | `marketing`, `promotional` | Paused | Edit, Resume, Delete |

### Contact 360 and per-contact inspection

In addition to the organizational rule list in Settings, per-contact cap utilization is visible on the **Contacts** surface:

* 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

You can verify that a frequency cap is functioning properly without impacting production recipients:

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`:

```json theme={null}
{
  "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

Understanding the architectural model ensures rules behave predictably:

* **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.

For an in-depth breakdown of sorted sets and Redis memory lifecycle, review the [Frequency-cap model concept](/concepts/frequency-caps-model).

***

## 7. Edge cases and evaluation order

When multiple controls and gates overlap, Orbit applies a deterministic pipeline 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](/concepts/frequency-caps-model)
* [Frequency Caps API Reference](/api-reference/frequency-caps)
* [Settings Overview](/settings/overview)
* [Compliance & Quiet Hours](/concepts/send-gating-and-quiet-hours)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.