VoIP.infoThe independent guide to business communications.
VoIP.info Guide

Asterisk WaitUntil: epoch scheduling, status and channel-lifetime evidence

Wait on an active channel until an absolute epoch while keeping civil-time conversion, status, channel lifetime, call timeout and downstream action independently observable.

Reviewed 2026-10-15Current Asterisk branch-23-generated WaitUntil, TIMEOUT, STRFTIME and STRPTIME references and branch 22 WaitUntil reference reviewed October 15, 2026; installed branch, module packaging, exact dialplan, channel lifetime, epoch source, civil-time input, timezone database, host clock, clock correction, scheduling, downstream action and caller treatment remain deployment specific; no host, module, dialplan, channel, epoch source, timezone database, clock, packet, scheduler or live call was inspected or testedAdvancedDocumentation based · not lab tested

Use an absolute epoch only when this channel should remain waiting

WaitUntil(epoch) waits until the current time reaches the supplied Unix epoch. The argument is an absolute target, not a number of seconds to delay and not a detached job-scheduler request. Confirm that keeping this exact channel and dialplan path alive is intended before selecting it.

For a long wait, document caller treatment, channel and bridge occupancy, cancellation behavior and what should happen if the call ends first. Those are deployment design questions derived from holding an active channel, not laboratory findings about a particular PBX.

Convert civil time once with an explicit timezone and format

An epoch identifies an instant without carrying a timezone. Timezone and format become material when a human date or time is converted to that epoch or when the epoch is displayed. Asterisk documents STRPTIME(datetime,timezone,format) for parsing a date-time string and STRFTIME(epoch,timezone,format) for formatting an epoch.

Record the original civil-time string, explicit zone, format, resulting epoch and conversion timestamp. Daylight-saving gaps or duplicated local times are conversion-boundary questions; do not describe WaitUntil() itself as choosing a timezone or resolving an ambiguous local time.

Validate the target before entering the wait

Reject missing, malformed or policy-invalid input before invoking the application, and log a privacy-safe representation of the target. Compare the epoch with a captured current time and define an allowed future window so a stale or unit-mismatched value does not unexpectedly enter the call path.

Do not infer that every PAST result is an application error. The current reference defines PAST specifically for a target time that has already passed. A correct past-time classification, a bad civil-time conversion and an invalid application argument remain separate findings.

Keep WaitUntil separate from the channel absolute timeout

TIMEOUT(absolute) sets the maximum time permitted for the call in seconds; setting it to zero disables that timeout. WaitUntil() instead accepts a target epoch. A seconds-based call-lifetime ceiling and an absolute wall-clock target are different controls and can both affect one run.

Record the existing absolute timeout before the wait and the intended relationship between the two. Do not “fix” a wait by disabling a safety timeout without separately reviewing the call-lifetime policy. The digit and response timeout types govern digit collection and are not alternative epoch schedulers.

Design explicitly for hangup and clock uncertainty

The documented HANGUP status means the channel ended before the target time elapsed. Treat that as a channel-lifecycle outcome rather than proof that the scheduler failed. Put any required external cleanup or durable work under its own authorized and observable contract.

Host clock synchronization, the source of the epoch and behavior during clock correction remain deployment specific. Capture the clock source and relevant before-and-after timestamps when timing accuracy matters; this guide makes no universal monotonicity or precision claim.

Branch on status, then verify the downstream action

The generated reference documents WAITUNTILSTATUS values OK, FAILURE, HANGUP and PAST. Preserve the value immediately after the application on the channel that ran it. FAILURE identifies an invalid argument, while OK identifies a completed wait under the application contract.

Application return does not prove that a later playback, call, alert, bridge or caller outcome succeeded. Test authorized future, exact-boundary, past, invalid and hangup cases with bounded timing and rollback. No host, module, dialplan, channel, epoch source, timezone database, clock, packet, scheduler or live call was inspected or tested for this guide.

Sources & applicability

Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.

Examples require adaptation to your topology. No live PBX or hardware testing is claimed.

Continue your research

Guide · Asterisk 22 GotoIfTime, ExecIfTime, IFTIME, TESTTIME and STRFTIME documentation plus current public Sangoma Time Conditions and Time Groups guidance and FreePBX release/17.0 Time Conditions metadata version 17.0.1.19 reviewed October 15, 2026; Sangoma interface guidance is explicitly labelled for PBX GUI version 13 and is used for object and override semantics rather than as an exact FreePBX 17 screen map; installed modules, generated dialplan, host and explicit timezones, clock state, schedule, overrides, targets and calls remain deployment specific; no PBX, module, clock, timezone, dialplan, condition, override, destination or live call was inspected or tested

Asterisk time-based dialplan routing: conditions, zones and test time

Keep the timespec, timezone, channel clock, selected primitive, jump target and final destination independently observable when routing by time.

Read guide →
Guide · Asterisk 22 LTS

Asterisk dialplan: contexts, patterns and loaded-call evidence

Build a restricted Asterisk 22 call path, then prove its context, match, priorities and runtime behavior separately.

Read guide →
Guide · Current Asterisk variable-inheritance guidance and Asterisk 22 Set, CHANNEL, MASTER_CHANNEL, LOCAL, LOCAL_PEEK, VARIABLE_EXISTS and IMPORT documentation reviewed October 15, 2026; channel creation, inheritance depth, Gosub stack frames, master-channel lifetime, cross-channel access and loaded dialplan remain deployment specific; no PBX, channel, variable, subroutine, transfer, Local-channel path or live call was inspected or tested

Asterisk channel-variable scope and inheritance

Choose channel, child-depth, Gosub-frame, master-channel or explicit cross-channel scope before using a variable to control a call.

Read guide →
Guide · Asterisk hangup-handler, CHANNEL, AMI event, hangup-cause and Return documentation reviewed October 12, 2026; exact events and channel behavior remain dependent on the installed Asterisk branch, modules, dialplan, channel technology and observer permissions, and no PBX, dialplan, channel, handler stack, event, record, endpoint, call or teardown path was inspected or tested

Asterisk hangup handlers: channel stack, order and teardown evidence

Attach bounded hangup subroutines to the correct channel, preserve LIFO stack order and prove push, pop, run and final hangup separately.

Read guide →
Troubleshooting · Current Asterisk branch-23-generated WaitUntil, TIMEOUT, STRFTIME and STRPTIME references and branch 22 WaitUntil reference reviewed October 15, 2026; installed branch, module packaging, exact dialplan, channel lifetime, epoch source, civil-time input, timezone database, host clock, clock correction, scheduling, downstream action and caller treatment remain deployment specific; no host, module, dialplan, channel, epoch source, timezone database, clock, packet, scheduler or live call was inspected or tested

Asterisk WaitUntil returns PAST, fails or fires at the wrong time

Find the first divergence among installed application, loaded epoch, civil-time conversion, timezone, host clock, channel lifetime, absolute timeout, immediate status and downstream action.

Read guide →