Reference

Call execution configuration

Complete reference for CallExecutionConfig — scheduling, retries, providers, rate limiting, inbound rules, and pre-checks.

Overview

The CallExecutionConfig controls how outbound and inbound calls are executed. It defines the calling provider, retry logic, scheduling windows, rate limits, blacklist enforcement, inbound call behavior, and pre-call checks.

Fields reference

Field	Type	Default	Description
`id`	`str`	—	Unique identifier for this call execution config.
`reseller_id`	`str`	—	Reseller identifier.
`template`	`str`	—	Template ID this config is associated with.
`merchant_id`	`str`	—	Merchant identifier.
`initial_offset`	`int`	—	Delay in seconds before the first call attempt starts.
`retry_offset`	`int`	—	Delay in seconds between retry attempts.
`call_start_time`	`time`	—	Earliest time of day calls can be placed (24h format, e.g. `09:00`).
`call_end_time`	`time`	—	Latest time of day calls can be placed (24h format, e.g. `21:00`).
`max_retry`	`int`	—	Maximum number of retry attempts for failed/unanswered calls.
`calling_provider`	`CallProvider`	—	Telephony provider: `TWILIO`, `EXOTEL`, or `PLIVO`.
`enable_calling`	`bool`	—	Master switch to enable or disable outbound calling.
`enable_international_call`	`bool`	—	Allow calls to international numbers.
`enable_inbound`	`bool`	—	Accept inbound calls on this configuration.
`inbound_call_start_time`	`Optional[time]`	`null`	Earliest time to accept inbound calls.
`inbound_call_end_time`	`Optional[time]`	`null`	Latest time to accept inbound calls.
`inbound_call_timezone`	`Optional[str]`	`null`	Timezone for inbound calling hours (e.g. `Asia/Kolkata`).
`inbound_block_action`	`InboundBlockAction`	—	Action when inbound call is outside hours: `REJECT` or `REDIRECT`.
`inbound_redirect_number`	`Optional[str]`	`null`	Phone number to redirect blocked inbound calls to (when action is `REDIRECT`).
`inbound_block_message`	`Optional[str]`	`null`	Message played before rejecting/redirecting an inbound call.
`enforce_blacklist`	`bool`	—	Block calls to numbers in the blacklist.
`rate_limit_enabled`	`bool`	—	Enable rate limiting on outbound calls.
`rate_limit_max_calls`	`int`	—	Maximum number of calls allowed in the rate limit window.
`rate_limit_window_seconds`	`int`	—	Duration of the rate limit window in seconds.
`rate_limit_whitelist`	`string`	—	Comma-separated list of E.164 phone numbers exempt from rate limiting. Stored as a single string, not an array.
`pre_checks`	`Optional[List[PreCheckConfig]]`	`null`	Pre-call validation checks (e.g. DND check, balance check).
`telephony_config`	`Optional[TelephonyConfig]`	`null`	Provider-specific telephony settings (SID, auth, numbers).

Calling provider

Provider	Value	Regions
Twilio	`TWILIO`	Global
Exotel	`EXOTEL`	India, SEA
Plivo	`PLIVO`	Global

Call scheduling

Outbound calls are only placed between call_start_time and call_end_time. The initial_offset adds a delay before the first attempt, and retry_offset spaces out retries.

json

{
  "call_start_time": "09:00",
  "call_end_time": "21:00",
  "initial_offset": 0,
  "retry_offset": 300,
  "max_retry": 3
}

initial_offset

The scheduler sets next_attempt_at = now + initial_offset on push. 0 means the lead is eligible to dial on the very next scheduler tick (typically within seconds). A positive value delays the first dial — useful when you push a batch overnight but don’t want to dial until a specific time.

Outbound calls are scheduled in IST

Outbound call_start_time and call_end_time are hardcoded to IST (UTC+5:30). Inbound call times honour inbound_call_timezone when set. If your campaigns run outside India, raise this with your platform operators.

Inbound call configuration

When enable_inbound is true, the system accepts incoming calls. You can restrict inbound hours and define what happens when a call arrives outside the window.

InboundBlockAction

Action	Description
`REJECT`	Reject the call. Optionally play `inbound_block_message` before hanging up.
`REDIRECT`	Redirect the call to `inbound_redirect_number`. Optionally play message first.

json

{
  "enable_inbound": true,
  "inbound_call_start_time": "08:00",
  "inbound_call_end_time": "22:00",
  "inbound_call_timezone": "Asia/Kolkata",
  "inbound_block_action": "REDIRECT",
  "inbound_redirect_number": "+919876543210",
  "inbound_block_message": "We are currently outside business hours. Redirecting you to our support line."
}

Rate limiting

Prevent excessive outbound calls by configuring rate limits. Calls exceeding the limit within the window are queued or dropped.

json

{
  "rate_limit_enabled": true,
  "rate_limit_max_calls": 100,
  "rate_limit_window_seconds": 60,
  "rate_limit_whitelist": "+919999999999,+919888888888"
}

Whitelist format

rate_limit_whitelist is a comma-separated string of E.164 numbers, not a JSON array. Numbers in this list bypass rate limiting entirely — use sparingly, typically for internal test numbers or VIP contacts.

Pre-checks

The pre_checks array defines validations that run before a call is placed. Every entry must have type: "external_api" (the only supported type today), a name, an HTTP request, and a response config. See Pre-checks for the full field breakdown and semantics.

json

{
  "pre_checks": [
    {
      "type": "external_api",
      "name": "DND Check",
      "enabled": true,
      "credential_id": "cred_dnd_provider",
      "http_request": {
        "url": "https://dnd-api.example.com/check?phone={customer_mobile_number}",
        "method": "GET",
        "timeout": 5,
        "max_retries": 2
      },
      "response_config": {
        "response_field": "blocked",
        "response_field_value": false
      },
      "default_on_failure": "proceed"
    }
  ]
}

Full JSON example

json

{
  "id": "exec-config-001",
  "reseller_id": "reseller-abc",
  "template": "template-xyz",
  "merchant_id": "merchant-123",
  "initial_offset": 0,
  "retry_offset": 300,
  "call_start_time": "09:00",
  "call_end_time": "21:00",
  "max_retry": 3,
  "calling_provider": "TWILIO",
  "enable_calling": true,
  "enable_international_call": false,
  "enable_inbound": true,
  "inbound_call_start_time": "08:00",
  "inbound_call_end_time": "22:00",
  "inbound_call_timezone": "Asia/Kolkata",
  "inbound_block_action": "REDIRECT",
  "inbound_redirect_number": "+919876543210",
  "inbound_block_message": "We are outside business hours. Redirecting you now.",
  "enforce_blacklist": true,
  "rate_limit_enabled": true,
  "rate_limit_max_calls": 100,
  "rate_limit_window_seconds": 60,
  "rate_limit_whitelist": "+919999999999",
  "pre_checks": [
    {
      "type": "external_api",
      "name": "DND Check",
      "enabled": true,
      "credential_id": "cred_dnd_provider",
      "http_request": {
        "url": "https://dnd-api.example.com/check?phone={customer_mobile_number}",
        "method": "GET",
        "timeout": 5,
        "max_retries": 2
      },
      "response_config": {
        "response_field": "blocked",
        "response_field_value": false
      },
      "default_on_failure": "proceed"
    }
  ],
  "telephony_config": {
    "account_sid": "AC...",
    "auth_token": "...",
    "from_number": "+14155551234"
  }
}

enable_calling is a master switch

Setting enable_calling to false stops ALL outbound calls for this config, regardless of other settings. Use this to quickly pause campaigns without modifying other fields.

Was this helpful?

Edit on GitHub