State Call Limits

What a State Call Limit Is

A state call limit caps the number of outbound contacts
to a single phone number within a configurable sliding
time window. The limit counts both outbound calls and
outbound SMS messages to the same caller_number within
the company.

Key Fields

• states: a PostgreSQL text array of state codes using the us-XX format (e.g., us-ca, us-tx).
• Maximum Calls & SMS During Time Period: the maximum number of contacts allowed within the window. Validated as 1 to 999. Default: 3.
• Time Period: the sliding window duration in seconds. Validated as 3600 (1 hour) to 5,184,000 (2 months). Default: 86400 (24 hours).
• company_id: the owning company.

How Counting Works

The limit is enforced per phone number, not per state. The
state is only used to determine whether the rule applies to
a given call. When a call's state matches the rule's states
array, the system counts:

1. All outbound calls to the same caller_number within the company during the lookback window (call_limit_interval seconds ago to now).
2. If calls alone do not exceed the limit, it also counts outbound SMS messages to the same number in the same window.
3. If the combined count exceeds call_limit_limit, the call is blocked with next_action_at set to 1 day from now.

This is a sliding window, not a daily reset at midnight.
The window slides forward continuously based on the current
time.