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",
"to_number": "+905551234567",
"from_number": "+908501234567",
"scheduled_at": "2026-05-07T14:30:00",
"timezone": "Europe/Istanbul",
"dynamic_variables": {
"customer_name": "Ahmet",
"appointment_date": "8 May Cumartesi 14:00"
}
}'
Required: agent_id, to_number, scheduled_at, timezone.
Optional: from_number (defaults to your default outbound number),
dynamic_variables (interpolated into the agent's prompt at call time).
Recurrence
Add recurrence to repeat the schedule:
{
"recurrence": {
"frequency": "weekly",
"interval": 1,
"days_of_week": ["monday", "wednesday", "friday"],
"until": "2026-12-31"
}
}
Supported frequencies: daily, weekly, monthly. The until field is
optional — without it, the schedule runs indefinitely until you delete it.
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
- Campaigns — when you need many calls instead of one
- Post-Call Actions — auto-schedule follow-ups
- Phone Numbers — pick the right
from_number
Frequently asked
Q.What's the difference between a schedule and a campaign?
A schedule is one call (or a recurring series) to one number. A campaign is many calls to many numbers. Use schedules for confirmations and reminders; use campaigns for bulk outreach.
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 same retry rules campaigns use — count and delay you set per schedule. After retries, the schedule is marked failed.