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 is 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: Works for both single calls (POST /call) and batch calls (POST /batches/{batch_id}/schedule). Default is false.

​
Next Steps