Skip to main content

​
What are Call Guardrails?

Call guardrails help you control when your agent makes outbound calls by enforcing time-based restrictions. This ensures compliance with calling regulations and respects recipient time zones. With call guardrails, you can define allowed calling hours (e.g., 9 AM - 5 PM) for your agents. Calls outside these hours are automatically rescheduled to the next available time window. For emergency or priority calls, you can use the bypass flag to override these restrictions.

​
How It Works

  1. Configure guardrails on your agent with allowed calling hours (call_start_hour and call_end_hour)
  2. Initiate a call via API (optionally with bypass_call_guardrails flag)
  3. Timezone detection - System automatically detects recipient’s timezone from phone number
  4. Time validation - If bypass is false, checks if current time in recipient’s timezone is within allowed window
  5. Execute or reschedule - Call is made immediately if within hours, or automatically rescheduled if outside
The hours are interpreted in the recipient’s local timezone, not yours. For example, if call_start_hour=9, the call can be made at 9 AM Indian time for an Indian number.

​
Configuration

Configure guardrails when creating or updating an agent via the /v2/agent API:
FieldTypeRequiredDefaultDescription
call_start_hourintegerNo-Start of allowed calling window (0-23, 24-hour format)
call_end_hourintegerNo-End of allowed calling window (0-23, 24-hour format)
Example: Business hours (9 AM - 5 PM) 
curl --request POST \
  --url https://api.bolna.ai/v2/agent \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "agent_config": {
      "agent_name": "Sales Agent",
      "agent_welcome_message": "Hello, how can I help you?",
      "calling_guardrails": {
        "call_start_hour": 9,
        "call_end_hour": 17
      },
      "tasks": [...]
    },
    "agent_prompts": {...}
  }'
Hours use 24-hour format where 0 = midnight, 9 = 9 AM, 17 = 5 PM, 23 = 11 PM. call_end_hour must be greater than or equal to call_start_hour.

​
Making Calls

​
Standard Call (With Guardrails)

When you initiate a call, the agent’s guardrails are automatically applied: 
curl --request POST \
  --url https://api.bolna.ai/call \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "recipient_phone_number": "+14155551234",
    "user_data": {...}
  }'
What happens:
  • If within allowed hours → Call is made immediately
  • If outside allowed hours → Call status is set to rescheduled and automatically rescheduled to next call_start_hour

​
Bypass Call Guardrails

The bypass_call_guardrails parameter allows you to skip all time validation checks for specific calls. When set to true, calls are made immediately regardless of configured time windows. When to use bypass:
  • Emergency calls or critical notifications
  • VIP/priority calls that can’t wait
  • Testing call flows in development
  • Time-sensitive notifications or alerts
Single call with bypass: 
curl --request POST \
  --url https://api.bolna.ai/call \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "recipient_phone_number": "+14155551234",
    "bypass_call_guardrails": true,
    "user_data": {...}
  }'
Use the bypass flag responsibly. Bypassing guardrails may violate calling regulations or disturb recipients.

​
Common Use Cases

​
Business Hours Only

Configure standard 9-5 business hours: 
{
  "calling_guardrails": {
    "call_start_hour": 9,
    "call_end_hour": 17
  }
}
Calls are only made between 9:00 AM and 5:00 PM in the recipient’s timezone.

​
Important Notes

  • Time format: Use 24-hour format (0-23).
  • Timezone behavior: Time validation uses the recipient’s timezone, automatically detected from phone number.
  • Automatic rescheduling: Calls outside allowed hours are automatically rescheduled to the next call_start_hour. No manual intervention required.
  • Bypass flag: For single calls (POST /call) use flag bypass_call_guardrails. Default is false.
  • status: The status is updated to rescheduled when the call is triggered outside allowed hours

​
In-Call Reschedule Validation

When a user asks to reschedule a call to a specific time during a conversation (e.g., “reschedule for 9 PM today”), the system validates the requested time against the agent’s allowed calling window before scheduling it. Priority order for validation:
  1. calling_guardrails — explicit call_start_hour / call_end_hour config always takes precedence
  2. Agent prompt — if no explicit guardrails are set, the LLM reads the agent’s system prompt for any mentioned time restrictions
  3. Default window (9 AM – 9 PM) — fallback if neither of the above is configured
If the requested reschedule time falls outside the allowed window, the reschedule is dropped entirely. The system does not snap to the boundary — if the time is disallowed, the request is rejected.
Ensure your agent’s system prompt and calling_guardrails config mention the same calling hours to avoid inconsistent behavior during conversations.

​
Next Steps