Skip to main content

Guardrails

Guardrails are rules your agents must follow. With them you can:

  • cap what an agent, a project or the whole organization may spend,
  • take calls, place calls or chat only during set hours,
  • cap call length, how many calls run at once and how many outbound calls are dialled per minute,
  • keep a do-not-call list of numbers that are never dialled,
  • limit which countries agents may call, and block callers,
  • choose which tools and which AI and voice models agents may use.

The platform checks guardrails itself, before a call, chat turn, workflow run or tool call goes ahead. They apply on every channel and every carrier, and they do not rely on the agent's prompt. Guardrails are available on every plan.

Everything that controls what agents may do lives in Guardrails. Calling hours, outbound call limits and the do-not-call list are guardrails too; there are no separate settings pages for them.

Where to find Guardrails​

LevelWhere in the consoleWho can change it
OrganizationOrganization → Guardrails in the main menuOrganization Owners and Admins
ProjectGuardrails in the project sidebar, under GovernProject Admins
AgentOpen the agent → Guardrails tabProject Admins

The organization and project Guardrails pages have these tabs:

TabWhat it shows
RulesAll guardrails: every rule at this level and below it, grouped by where it applies. See See every rule in one place.
Do-not-callProject only. The do-not-call list and the switch that turns it on or off. See Do-not-call.
ActivityRecent decisions: every block and every alert, with the rule, the reason, the project and the agent.

The agent's Guardrails tab shows the rules in force for that agent: its own, plus those inherited from its project and the organization. Each rule shows where it is set.

Moved pages

Calling hours, outbound limits and the do-not-call list used to be under project Settings. Old links to those pages now open the matching tab of the project's Guardrails page. Your existing calling hours and outbound limits were turned into guardrail rules named Calling hours (migrated) and Outbound limits (migrated), and every project with numbers on its do-not-call list has the do-not-call guardrail turned on. Nothing changes in how calls are handled.

See every rule in one place​

The Rules tab opens on All guardrails, so you can track every rule without opening each project and agent.

Where you areWhat All guardrails shows
OrganizationThe organization's own rules, every project's rules, and every agent's rules, across all projects.
ProjectThe project's own rules and the rules of each of its agents, plus the organization's rules that apply to it. Organization rules are locked and labelled From organization.

You only see the projects you can view. You can edit, switch and delete only the rules at levels you are allowed to manage; the others show with a lock.

Columns​

ColumnWhat it shows
TypeThe type's icon, for example a spend limit or working hours.
RuleThe rule's name and a plain-language summary, for example "Outbound calls Mon-Fri, 09:00-18:00 Asia/Dubai".
Applies toWhere the rule is set: Organization, a project (for example Sales), or an agent in a project (for example Sales › Booking agent). Click it to open that level's Guardrails page. An agent that lives in another region shows as Agent #id.
On / offThe rule's switch.
Last triggeredWhen the rule last blocked or alerted.
Blocks (30d)How many actions the rule refused in the last 30 days.
ActionsEdit, Copy to… and Delete.
  • Rules are grouped by where they apply: Organization first, then each project, then each agent under its project. Each group header shows how many rules it holds and can be collapsed. Switch to Flat list to see every rule in one list.
  • Filter by project, agent, type or category, and on / off, or search by name.

Change many rules at once​

Tick the rules you want, then choose Enable, Disable or Delete. Each rule is checked on its own: rules you are not allowed to change are skipped, and the result lists any that failed and why.

Add, edit and remove rules​

Add a rule​

  1. Open Guardrails: on the organization, a project or an agent.

  2. Click + Add guardrail. A gallery of guardrail types opens, grouped by category:

    CategoryTypes
    CostSpend limit
    AvailabilityWorking and calling hours, Legal calling hours
    CallsCall limits, Outbound countries, Inbound blocking
    ListsDo-not-call (project only)
    ToolsTool access
    ModelsModel access

    Each card says in one line what the type does. If a level has no rules yet, the gallery is shown straight away.

  3. Pick a type. A form for that type opens.

  4. Give the rule a name, fill in its settings, and choose what happens when it matches: Blocks or Alerts only.

  5. Click Next to choose where the rule applies. See Choose where a rule applies.

  6. Click Create. A result list shows each rule that was created, and any level where it could not be. The rules are in force within about 30 seconds.

When you add a rule from an agent's Guardrails tab, it applies to that agent.

Choose where a rule applies​

The Apply to step shows your organization as a tree: the organization, its projects, and each project's agents. Tick every level the rule should apply to.

  • The level you started from is ticked already.
  • Only levels you are allowed to manage can be ticked. On the organization page that is every level you manage; on a project page it is that project and its agents, plus the organization if you are an organization Owner or Admin.
  • Search the tree by project or agent name, and use Select all agents on a project to tick each of its agents.
  • The summary shows how many rules will be created, for example Will create 4 rules.

One separate rule is created for each level you tick, with the same name and settings. Each one can then be edited, switched off or deleted on its own. Up to 50 levels can be ticked at once.

A level is skipped, and listed as failed, when:

  • it already has a rule with the same name,
  • you are not allowed to manage it, or
  • the rule is a do-not-call guardrail and the level is not a project, or the project already has one.

Tip: to apply a rule to every project and agent, apply it once to the Organization. It is inherited by everything below. Apply it to individual projects or agents only when they need it and the others do not.

Edit a rule​

Click a rule in the Rules list, or its Edit button. The same form opens with the rule's current settings. Change what you need and click Save.

The level a rule applies to is shown at the top of the form, and cannot be changed. To use the rule on another level, copy it.

Copy a rule to other levels​

Click Copy to… on a rule. The Apply to tree opens; tick the levels to copy it to and click Copy. Each copy is a separate rule with the same name and settings. The same checks apply as when adding a rule, so a level that already has a rule with that name is skipped and listed.

Turn a rule off, or remove it​

  • Use the row's switch to turn a rule off. It is kept but not checked, and you can turn it on again later.
  • Click Delete to remove it for good.
  • To do either for many rules at once, see Change many rules at once.

Inherited and default rules​

  • A rule set higher up shows with a lock and a From organization or From project label. You cannot edit, switch off or delete it here; click its Applies to label to open the level where it was set.
  • Legal calling hours (callee local time) is on by default everywhere, even before anyone creates a rule. You can edit its country windows, or turn it off, on the organization or on a project. On a project, an organization rule shows as From organization with an Override for this project button. See Legal calling hours.

Concepts​

Rules​

A rule has:

PartWhat it is
NameYour label, for example "Sales team budget". It must be unique where the rule is set.
TypeWhat the rule controls, for example a spend limit, working and calling hours, or call limits. See Rule types.
ConditionsThe settings for that type, for example a USD amount or a list of countries.
EffectBlocks (deny) refuses the action. Alerts only lets it go ahead and records it, and sends an email.
On / offA rule that is off is kept but not checked.

Inheritance​

Rules add up. An agent follows its own rules, plus its project's rules, plus the organization's rules.

  • A lower level cannot switch off or loosen a higher rule. It can only add more rules. The one exception is legal calling hours: it is a default, not a restriction set by an owner, so a project's rule replaces the organization's for that project.
  • If any rule in force blocks an action, the action is refused. Alert-only rules never block.
  • Where two rules set the same limit, the strictest one applies. For example, if the organization allows 20 outbound calls per minute and the project allows 10, the project dials at most 10.
  • With no rules in force, nothing is restricted, except the default legal calling hours.

For example, if the organization allows outbound calls only to the UAE and India, and a project blocks India, agents in that project can call only the UAE.

What the caller or user sees​

When a rule blocks something, the platform refuses it the same way it refuses an action when the credit balance is zero, but with a reason such as Spend limit reached:

  • An incoming call that a rule blocks is not connected. For working hours, the caller hears your after-hours message, or is transferred to your after-hours number.
  • An outbound call that a rule blocks is not dialled. The Playground call panel shows the reason, and a workflow's Outbound Call step reports the call as blocked with the reason and, for hours, the next time calling opens, so the workflow can try again later.
  • A chat or widget message gets a short refusal message instead of a reply.
  • An API call gets an error with the reason.
  • A tool that is not allowed is not offered to the agent, and is refused if the agent calls it anyway.

Activity​

Every block and every alert is recorded with the rule, the reason, the project and the agent, and shows on the Activity tab. Reasons include:

ReasonMeaning
spend_limitA spend limit was reached.
scheduleOutside working or calling hours.
blocked_hoursOutside the legal calling hours for the callee's country.
rate_limitedAn outbound call would go over the calls-per-minute limit.
do_not_callThe number is on the project's do-not-call list.
call_limitToo many calls at once, or the call reached its maximum length.
outbound_countryThe callee's country is not allowed.
inbound_blockedThe caller's number or country is blocked.
tool_deniedThe tool is not allowed.
model_deniedThe AI or voice model is not allowed.

VoisX support can see these decisions too, to help explain why a call was blocked.

Rule types​

Spend limit​

Caps spend, in USD at the price you pay, for an agent, a project or the organization.

SettingMeaning
Limit (USD)The amount. Must be more than 0.
PeriodMonthly counts spend from the 1st of each month (UTC) and resets then. Once counts all spend from when the rule was created, and never resets.
Warn at (%)Optional, 1 to 99. Default 80.
Notify emailOptional. Where the warning emails go.

Spend is checked when a call, chat conversation or workflow run starts. Once spend reaches the limit, new ones are refused with Spend limit reached (with Blocks) until the next period or until you raise the limit. A call already in progress is not cut off.

Warning emails. A spend rule sends an email when spend reaches the Warn at share of the limit, and another when it reaches 100%. Each is sent once per period: once a month for a monthly rule, once only for a "once" rule. If spend jumps straight past the limit, you get one email, not two. The emails go to the rule's Notify email when it has one. Otherwise they go to your organization's billing contacts: the address on your balance alert, the billing email on your tax details, or, if neither is set, the organization's Owners and Admins. Spend is checked every 15 minutes, so an email can arrive up to about 15 minutes after the threshold is reached.

Example: a monthly budget of $500 for the organization that warns at 75%.

{
"action": "spend",
"effect": "deny",
"conditions": { "amount_usd": 500, "period": "monthly", "alert_percent": 75, "notify_email": "finance@example.com" }
}

Example: a $50 trial budget for one agent that only warns.

{
"action": "spend",
"effect": "alert",
"conditions": { "amount_usd": 50, "period": "once" }
}

Working and calling hours​

Allows calls and conversations only on set days and hours. Use it for an inbound or chat opening time, for outbound calling hours, or both.

SettingMeaning
Applies toAny of Inbound calls, Outbound calls and Chat. Default: all three.
Time zoneAn IANA time zone, for example Asia/Dubai.
DaysAny of Monday to Sunday.
From / To24-hour times, for example 09:00 and 18:00. An end time earlier than the start time makes an overnight window, which belongs to the day it starts on.
After-hours messageOptional. What callers hear, or chat users read, outside the hours.
After-hours numberOptional, inbound voice only. An E.164 number to transfer callers to outside the hours.

Calling hours are a rule of this type that applies to Outbound calls only. An outbound call outside the hours is not dialled, and is refused with reason schedule and the next time calling opens. A workflow's Outbound Call step uses that time to try again later. Your calling hours can only narrow the legal calling hours, never widen them. To widen the legal windows themselves, edit the legal calling hours rule.

Example: weekdays 9 to 6 in Dubai for incoming calls and chat, with transfer to the on-call line.

{
"action": "schedule",
"effect": "deny",
"conditions": {
"applies_to": ["inbound", "chat"],
"timezone": "Asia/Dubai",
"days": ["mon", "tue", "wed", "thu", "fri"],
"start": "09:00",
"end": "18:00",
"after_hours_message": "We're closed. Please call back between 9am and 6pm, Monday to Friday.",
"transfer_number": "+97145550100"
}
}

Example: outbound calling hours, Sunday to Thursday 10 to 5 in Dubai.

{
"action": "schedule",
"effect": "deny",
"conditions": {
"applies_to": ["outbound"],
"timezone": "Asia/Dubai",
"days": ["sun", "mon", "tue", "wed", "thu"],
"start": "10:00",
"end": "17:00"
}
}

Legal calling hours (callee local time) keeps outbound calls inside the hours each country allows, in the callee's local time. It is on by default for every organization and project: if no level has a rule, these default windows apply.

Callee's countryCalls allowed
India (IN)09:00 to 21:00
United Arab Emirates (AE)09:00 to 18:00
United States (US)08:00 to 21:00
Canada (CA)08:00 to 21:00
Every other country (default)08:00 to 21:00

The windows are start-inclusive and end-exclusive: under a 21:00 end, a callee at 20:59 can be called and one at 21:00 cannot. Where a country spans several time zones and the number does not say which, the call must be inside the window in every one of them.

An outbound call outside the window is not dialled. It is refused with reason blocked_hours and the next time calling opens (retry_after), so a workflow's Outbound Call step can try again later.

Edit the windows. Open the Legal calling hours row on the organization's or a project's Guardrails page and click Edit. The form starts with the windows in force (the defaults above until someone changes them). You can:

  • change a country's From and To times,
  • limit a country to some Days (Monday to Sunday; leave empty for every day),
  • add or remove a country, using its ISO code, for example SA,
  • change the Every other country window, and
  • click Reset to defaults to go back to the table above.

A country you do not list uses the Every other country window.

Turn it off. Use the rule's switch. A warning asks you to confirm that your organization is then responsible for complying with calling-hours laws in every country you call. Turning it off saves the rule as explicitly off, not as removed: outbound calls at that level are no longer checked against legal calling hours, and nothing is recorded. Your own calling hours still apply. Turn the switch back on, or click Reset to defaults, to restore the check.

Organization and projects. There is at most one legal calling hours rule per level, set on the organization or on a project (not on an agent). For each call, the platform uses:

  1. the project's rule, if it has one,
  2. otherwise the organization's rule,
  3. otherwise the default windows above.

A project's rule replaces the organization's for that project, so a project can widen the windows or turn the check off even when the organization's rule is on. This is the one guardrail where a lower level can loosen a higher one, because it is a safety default rather than a restriction set by an owner. On a project page, the organization's rule shows as From organization; click Override for this project to give the project its own copy and edit it. Delete the project's rule to go back to the organization's.

Example: the defaults plus Saudi Arabia, and UAE calls on weekdays only.

{
"action": "legal_calling_hours",
"effect": "deny",
"conditions": {
"enabled": true,
"windows": {
"default": { "start": "08:00", "end": "21:00" },
"IN": { "start": "09:00", "end": "21:00" },
"AE": { "start": "09:00", "end": "18:00", "days": ["mon", "tue", "wed", "thu", "fri"] },
"US": { "start": "08:00", "end": "21:00" },
"CA": { "start": "08:00", "end": "21:00" },
"SA": { "start": "09:00", "end": "21:00" }
}
}
}

Example: turned off for one project.

{ "action": "legal_calling_hours", "effect": "deny", "conditions": { "enabled": false } }

enabled defaults to true. A country missing from windows falls back to windows.default, and then to the default table. GET /api/guardrails/catalog returns the default windows for this type, which the console uses to fill in the form.

Outbound countries​

Controls which countries agents may call, on every carrier.

SettingMeaning
Allow onlyOptional. ISO country codes, for example AE, IN. Calls to any other country are refused.
BlockOptional. ISO country codes that may never be called.

Example: call only the UAE and Saudi Arabia.

{ "action": "call.outbound", "effect": "deny", "conditions": { "allow_countries": ["AE", "SA"] } }

Inbound blocking​

Refuses incoming calls from numbers or countries.

SettingMeaning
Block numbersOptional. E.164 numbers, for example +14155550123.
Block countriesOptional. ISO country codes of the caller's number.

Example: block one number.

{ "action": "call.inbound", "effect": "deny", "conditions": { "block_numbers": ["+14155550123"] } }

Call limits​

Caps how long a call may last, how many calls may run at once, and how fast outbound calls are dialled.

SettingMeaning
Max call lengthOptional. In seconds. The call is ended when it is reached.
Max calls at onceOptional. A new call is refused while this many are in progress. Counts outbound calls, and incoming calls where supported. Up to 500.
Max outbound calls per minuteOptional. How many outbound calls may be dialled in any one minute. A call over the limit is refused with reason rate_limited. Up to 600.

Without a call limits rule, each project dials at most 30 outbound calls per minute and runs at most 10 outbound calls at once. When the organization and the project both set a limit, the lower one applies.

Example: calls of up to 10 minutes, at most 5 at a time, at most 20 dialled per minute.

{
"action": "call.limits",
"effect": "deny",
"conditions": { "max_duration_seconds": 600, "max_concurrent_calls": 5, "max_calls_per_minute": 20 }
}

Do-not-call​

Never dials the numbers on the project's do-not-call list. It is set per project, and a project has at most one do-not-call guardrail. It can only be applied to projects, not to the organization or to agents. It has no settings of its own; the numbers are kept on the Do-not-call tab.

On the project's Guardrails page, open Do-not-call:

  • Use the switch to turn the do-not-call guardrail on or off. While it is off, the list is kept but not checked.
  • Click Add numbers and paste up to 5,000 numbers, one per line or separated by commas, in international format with the country code (for example +971501234567). Add an optional reason, such as "Asked not to be called".
  • Search the list, and remove a number with Remove.

Every outbound call, from the Playground, a workflow or the API, is checked before dialling. A call to a listed number is refused with reason do_not_call and shows on the Activity tab.

{ "action": "do_not_call", "effect": "deny", "conditions": {} }

Tool access​

Controls which tools agents may use. Name tools by their integration template (for example stripe) or by tool ID.

SettingMeaning
Allow onlyOptional. Only these tools may be used.
DenyOptional. These tools may never be used.

A denied tool is hidden from the agent and refused if the agent calls it anyway.

Example: never let agents issue refunds.

{ "action": "tool.use", "effect": "deny", "conditions": { "deny_tools": ["stripe_refund"] } }

Example: get an email whenever a payment tool is used, without blocking it.

{ "action": "tool.use", "effect": "alert", "conditions": { "deny_tools": ["payments"] } }

Model access​

Limits which AI (LLM) and voice providers or models agents may use. Name a provider, for example openai, or a provider and model, for example openai:gpt-4.1-mini.

SettingMeaning
Allowed AI modelsOptional. Providers or provider:model entries.
Allowed voicesOptional. Voice providers or provider:model entries.

Saving an agent that uses a model outside the list is refused with a clear error. If a rule is tightened after an agent was saved, the agent's conversations are refused until it is switched to an allowed model.

Example: OpenAI models only, ElevenLabs voices only.

{ "action": "model.use", "effect": "deny", "conditions": { "allow_llm": ["openai"], "allow_voice": ["elevenlabs"] } }

Alert-only rules​

A rule with Alerts only never blocks. Each time it matches, the decision is recorded, and an email goes to the rule's notify email or the organization's billing contacts. To avoid a flood of mail from a busy agent, you get at most one email per rule, project and agent each hour. Every match still shows on the Activity tab.

Regions​

Rules are saved once, centrally, and copied to every region your organization uses. They are checked in the region where the call, chat or workflow runs. The do-not-call numbers stay in the project's region, with the project's other data.

API​

The console uses these endpoints, with the signed-in user's permissions. Rules use the same action, effect and conditions fields as the examples above.

EndpointWhat it does
GET /api/organizations/{org_id}/guardrails?view=allEvery rule in the organization: organization, project and agent rules.
GET /api/projects/{project_id}/guardrails?view=allThe project's rules, its agents' rules, and inherited organization rules (with editable: false).
GET /api/guardrails/catalogThe rule types, with their settings and defaults, including the default legal calling hours windows.
GET /api/organizations/{org_id}/guardrails/targetsThe levels you may apply rules to, as a tree, each with can_manage. Also on /api/projects/{project_id}/guardrails/targets.
POST /api/organizations/{org_id}/guardrailsCreate a rule. Pass targets to create it on several levels at once. Also on /api/projects/{project_id}/guardrails. Without targets, the rule is created at the level in the path, as before.
POST /api/guardrails/{policy_id}/copyCopy a rule to other levels.
POST /api/guardrails/bulkEnable, disable or delete several rules.

Without view=all, the list endpoints return the rules in force at that level, as before.

In view=all, each rule also has:

FieldMeaning
targetWhere the rule applies: scope_type (org, project or agent), scope_id, project_id, project_name, agent_name (or null and an agent_label such as Agent #42 when the agent is in another region), and path, for example Sales › Booking agent.
editableWhether you may change the rule.
last_triggered_atWhen the rule last blocked or alerted, or null.
blocks_30dActions it refused in the last 30 days.

Create a rule on a project and two of its agents:

{
"name": "Sales calling hours",
"action": "schedule",
"effect": "deny",
"conditions": { "applies_to": ["outbound"], "timezone": "Asia/Dubai", "days": ["sun", "mon", "tue", "wed", "thu"], "start": "10:00", "end": "17:00" },
"targets": [
{ "scope_type": "project", "scope_id": 12 },
{ "scope_type": "agent", "scope_id": 301 },
{ "scope_type": "agent", "scope_id": 302 }
]
}

targets takes 1 to 50 levels. Each level is checked and created on its own, and the response lists both outcomes:

{
"created": [ { "id": 881, "name": "Sales calling hours", "target": { "scope_type": "project", "scope_id": 12, "path": "Sales" } } ],
"failed": [ { "target": { "scope_type": "agent", "scope_id": 302 }, "error": "A guardrail named \"Sales calling hours\" already exists here." } ]
}

Copy takes { "targets": [...] } and answers the same way. Bulk takes { "ids": [881, 882], "op": "disable" }, where op is enable, disable or delete, and answers { "done": [ids], "failed": [{ "id", "error" }] }.

Was this page helpful?