> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tidyhire.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Call Settings
> Retry policy, working hours, and WhatsApp notifications
`call_settings` is an optional object in the [Initiate AI Call](/api-reference/endpoint/call-initiate) request that controls **retries**, **working hours**, and **WhatsApp notifications**. Omit it entirely and the call is placed immediately with no retries.
```json theme={null}
{
"ats_job_id": "ats-job-12345",
"candidates": [ ... ],
"instructions": "...",
"call_settings": {
"retry_policy": { ... },
"working_hours": { ... },
"whatsapp_notifications": { ... }
}
}
```
***
## Retry Policy
Controls whether failed calls are retried and when.
```json theme={null}
"retry_policy": {
"conditions": ["missed", "declined"],
"intervals": [
{ "type": "delay", "duration": 15, "unit": "minutes" },
{ "type": "delay", "duration": 1, "unit": "hours" },
{ "type": "delay", "duration": 1, "unit": "days" }
]
}
```
### conditions
Array of call outcomes that should trigger a retry:
| Condition | Meaning |
| - | - |
| `missed` | Candidate didn't pick up |
| `declined` | Candidate rejected the call |
| `sent_to_voicemail` | Call went to voicemail |
| `silenced` | Phone was on silent / do-not-disturb |
| `abruptly_disconnected` | Call dropped mid-conversation |
### intervals
Optional array describing the retry schedule. Each entry is either:
* **Delay** — retry after a wait: `{ "type": "delay", "duration": 15, "unit": "minutes" }` where `unit` is `minutes`, `hours`, or `days`
* **Specific time** — retry at a fixed point: `{ "type": "specific_datetime", "datetime": "2026-05-27T10:15:00Z" }` (ISO 8601)
Retries execute in the order listed — the first entry is the first retry attempt, the second is the second attempt, and so on. If `intervals` is omitted, retries use default timing.
If `retry_policy` is omitted entirely, failed calls are never retried.
***
## Working Hours
Restricts when calls can be placed. Each day takes a shift with `start_time` and `end_time` in 12-hour format.
```json theme={null}
"working_hours": {
"enabled": true,
"monday": { "start_time": "09:00 AM", "end_time": "07:00 PM" },
"tuesday": { "start_time": "09:00 AM", "end_time": "07:00 PM" },
"wednesday": { "start_time": "09:00 AM", "end_time": "07:00 PM" },
"thursday": { "start_time": "09:00 AM", "end_time": "07:00 PM" },
"friday": { "start_time": "09:00 AM", "end_time": "07:00 PM" }
}
```
Behavior:
* `enabled` (default `true`) — set `false` to bypass working-hours checks
* **Omit a day** to disallow calls on that day (the example above allows Mon–Fri only)
* If the call time falls outside all configured shifts, the call is **delayed until the start of the next available shift**
* `end_time` must be after `start_time`
* [`schedule_at`](/api-reference/endpoint/call-initiate) is always respected as-is — working hours never push it
Example — weekends allowed with different hours:
```json theme={null}
"working_hours": {
"enabled": true,
"monday": { "start_time": "09:00 AM", "end_time": "06:00 PM" },
"saturday": { "start_time": "10:00 AM", "end_time": "02:00 PM" }
}
```
***
## WhatsApp Notifications
Sends approved WhatsApp templates to the candidate around the call. Each notification takes a `template_name` (must be an approved WhatsApp template) and optional `template_variables`.
WhatsApp notifications require setup — contact the support team at [support@tidyhire.app](mailto:support@tidyhire.app) to configure your templates and enable the option for your workspace.
```json theme={null}
"whatsapp_notifications": {
"pre_call": {
"template_name": "interview_reminder",
"template_variables": {
"body_1": "{{candidate_first_name}}",
"body_2": "Thursday, 21 May 2026, 6:00 PM – 8:45 PM"
}
},
"fallback": {
"template_name": "call_fallback",
"template_variables": {
"body_1": "{{candidate_first_name}}",
"body_2": "We tried calling you about the position but couldn't reach you. Please reply with your availability."
}
}
}
```
| Notification | When it's sent |
| - | - |
| `pre_call` | Before the AI call is placed |
| `fallback` | If the call fails and cannot be retried |
`template_variables` values are either:
1. **Variable reference** — exactly a variable like `{{candidate_first_name}}`, filled in automatically
2. **Literal text** — anything else, passed to WhatsApp as-is
***
## Complete Example
```json theme={null}
{
"ats_job_id": "ats-job-12345",
"candidates": [
{
"id": "ats-candidate-001",
"name": "John Doe",
"phone": "+917873476062"
}
],
"instructions": "You are a recruiter for {{sender_company}}. Screen the candidate.",
"call_settings": {
"retry_policy": {
"conditions": ["missed", "declined", "sent_to_voicemail"],
"intervals": [
{ "type": "delay", "duration": 30, "unit": "minutes" },
{ "type": "delay", "duration": 2, "unit": "hours" }
]
},
"working_hours": {
"enabled": true,
"monday": { "start_time": "09:00 AM", "end_time": "07:00 PM" },
"tuesday": { "start_time": "09:00 AM", "end_time": "07:00 PM" },
"wednesday": { "start_time": "09:00 AM", "end_time": "07:00 PM" },
"thursday": { "start_time": "09:00 AM", "end_time": "07:00 PM" },
"friday": { "start_time": "09:00 AM", "end_time": "07:00 PM" }
},
"whatsapp_notifications": {
"pre_call": {
"template_name": "interview_reminder",
"template_variables": {
"body_1": "{{candidate_first_name}}"
}
},
"fallback": {
"template_name": "call_fallback",
"template_variables": {
"body_1": "{{candidate_first_name}}"
}
}
}
},
"schedule_at": "2026-05-27T10:00:00Z"
}
```
With this configuration: the call is placed Wednesday 10:00 UTC; if the candidate doesn't answer, it retries after 30 minutes, then again after 2 hours — but never outside the Mon–Fri 9 AM–7 PM shifts.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.