Schedules: one-shot and recurring scheduled calls
Book a voice AI call to fire at a specific date and time — once, or on a recurring schedule. Time zones, recurrence rules, and how to wire schedules to post-call actions.
Updated May 6, 2026
Schedules let you commit to a call at a specific future moment — once or on a recurring cadence. They're the right primitive for confirmations, reminders, and follow-ups.
Creating a schedule
curl -X POST https://api.call2me.app/v1/schedules \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent_abc123",
"phone_number": "+905551234567",
"from_number": "+908501234567",
"scheduled_at": "2026-05-07T14:30:00",
"timezone": "Europe/Istanbul",
"contact_name": "Ahmet",
"variables": {
"appointment_date": "8 May Cumartesi 14:00"
}
}'
Required: agent_id, phone_number (E.164), scheduled_at.
Optional: timezone (defaults to Europe/Istanbul), from_number,
contact_name, description, variables, recurrence, recurrence_end_at.
Recurrence
Set recurrence to a string to repeat the schedule, and optionally
recurrence_end_at to stop it:
{
"recurrence": "weekly",
"recurrence_end_at": "2026-12-31T00:00:00"
}
Supported values: daily, weekly, monthly. Without recurrence_end_at
the schedule runs until you delete it. There is no interval or
days-of-week option.
Time zones, done right
Schedules store the timezone alongside the local time. This matters for two reasons:
- DST: a 9am Istanbul schedule fires at 9am local year-round, even through the spring-forward and fall-back transitions
- Cross-timezone teams: if your operator is in Berlin and the customer
is in California, the schedule fires at the customer's 9am — set the
timezone to
America/Los_Angeles.
Always set the timezone explicitly. Defaults can surprise you when DST shifts.
Auto-scheduling from a call
The most-used pattern is letting the AI agent schedule its own follow-up.
Configure a post-call action of type
schedule_call:
{
"type": "schedule_call",
"name": "Follow-up Call",
"condition": { "field": "follow_up_required", "operator": "==", "value": true },
"config": {
"use_field": "follow_up_date",
"fallback_delay_minutes": 1440
}
}
When a call ends with follow_up_required = true, the platform reads the
follow_up_date field from extraction and books the schedule. If the date
is missing or invalid, the fallback_delay_minutes kicks in (24 hours by
default).
Status lifecycle
| Status | Meaning |
|---|---|
scheduled | Waiting for the trigger time |
dialing | The platform is placing the call now |
completed | Call finished successfully |
failed | All retries exhausted |
cancelled | You called DELETE on the schedule |
Status transitions are visible in real time in the dashboard.
What's next
- Post-Call Actions — auto-schedule follow-ups
- Phone Numbers — pick the right
from_number
Frequently asked
Q.What is a schedule for?
A schedule is one call (or a recurring series) to one number, placed at the time you set. Use it for confirmations, reminders and call-backs a customer asked for.
Q.Can the agent itself create a schedule mid-call?
Yes — that's the most common use. When a caller says 'call me tomorrow at 10', a Post-Call Action with type schedule_call books it automatically using the extracted follow_up_date field.
Q.Does the system handle daylight saving?
Yes. Schedules store the timezone, not just UTC. A 9am-Istanbul recurring schedule fires at 9am local time year-round, regardless of DST shifts.
Q.What happens if a scheduled call's recipient doesn't pick up?
The schedule retries based on the retry rules you set per schedule — count and delay. After retries, the schedule is marked failed.