Call Settings

call_settings is an optional object in the Initiate AI Call request that controls retries, working hours, and WhatsApp notifications. Omit it entirely and the call is placed immediately with no retries.

{
  "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.

"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.

"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 is always respected as-is — working hours never push it

Example — weekends allowed with different hours:

"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 to configure your templates and enable the option for your workspace.

"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:

Variable reference — exactly a variable like {{candidate_first_name}}, filled in automatically
Literal text — anything else, passed to WhatsApp as-is

Complete Example

{
  "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.

API Reference

API Key

Interview

Call

Others

Retry Policy

conditions

intervals

Working Hours

WhatsApp Notifications

Complete Example

​Retry Policy

​conditions

​intervals

​Working Hours

​WhatsApp Notifications

​Complete Example

Retry Policy

conditions

intervals

Working Hours

WhatsApp Notifications

Complete Example