Capture the owner, ID and symptom before changing dialplan
Record timestamp and timezone, installed Asterisk branch, loaded-module evidence, owner-channel name and unique identity, linked identity, bridge or application state, creation expression, returned hook ID, context, extension, whole-second interval, on or off actions, hook-channel identity, audio application result, recording state and the exact listener symptom. Redact caller data and secrets.
Classify the problem as no ID, one ID with no invocation, invocation with failed dialplan or playback, injected audio not heard, repeated creation, wrong ID toggled, more than one owner channel, variable-scope mistake, delayed or buffered audio, or evidence from another call leg. Do not reduce all cases to a timer failure.
Prove module, function and loaded target first
Confirm the installed branch exposes PERIODIC_HOOK() and that func_periodic_hook is loaded. Verify the referenced context and extension in the running dialplan, not only in a saved source file. Preserve the returned hook ID from one creation.
If the ID is empty or creation logs an error, fix that boundary before changing media. If an ID exists, it still does not prove an interval elapsed, the target executed or audio reached the owner channel.
Correlate each asynchronous run with its owner
Log HOOK_ID and HOOK_CHANNEL at the start of the bounded hook extension, together with the hook-channel identity and time. The hook runs on a new channel, so a variable read, hangup state or bridge query on that channel may not describe the owner. Compare the documented hook variables with the stored owner identity rather than matching by a partial channel name.
When no run appears, verify the owner remained alive through the interval and that the intended ID was on. When a run appears on the wrong call, find where the creation expression or stored ID crossed channel scope.
Separate duplicate creation from duplicate audio
Search the dialplan path for every evaluation of the read form. A retry, loop, included context or transferred path can create more than one hook and return more than one ID. Preserve every observed ID and owner channel before disabling anything.
If only one hook run exists but listeners report two sounds, follow the audio path: the hook application may play more than one file, both call legs may have hooks, a bridge or recording monitor may expose more than one mix, or a device may render buffered audio. Do not delete dialplan branches until hook count and media duplication are distinguished.
Trace application success through media injection
For a playback-based hook, retain PLAYBACKSTATUS, the selected file and language, file availability and the hook-channel timeline. Then verify injection into the owner call and the final bridge or media topology. A successful playback attempt on the asynchronous channel is not itself a listener-side audio result.
Check whether the owner was answered, bridged, on hold, transferred or using a topology that changes which leg or recording receives mixed audio. Keep signaling, hook execution, RTP flow, decoded audio and human audibility as separate evidence.
Correct one state owner and retest teardown
Correct only the first proved divergence: module load, target dialplan, creation point, stored ID, variable scope, interval, on or off action, audio file or media-owner assumption. Preserve rollback and remove temporary high-volume logging.
Repeat one bounded call through create, first run, off, an absent interval, on, another run and hangup. If audio is reported late, correlate timestamps, owner identity, hook ID, hook-channel identity and buffered media before assigning it to the ended call. No host, module, dialplan, channel, hook, bridge, recording, audio stream or live call was inspected or tested for this diagnostic.
Sources & applicability
Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.
- Asterisk 23 PERIODIC_HOOK function ↗
- Asterisk 22 PERIODIC_HOOK function ↗
- Asterisk 20 PERIODIC_HOOK function ↗
- Asterisk Playback application ↗
- Asterisk CHANNEL function ↗
Examples require adaptation to your topology. No live PBX or hardware testing is claimed.