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

Asterisk DIALGROUP: manage dynamic dial targets with explicit fallbacks

Build a named dial-target list with whole-list replacement or explicit add and delete operations, then keep membership, contact expansion and Dial outcomes independently observable.

Reviewed 2026-10-19Current Asterisk Latest API DIALGROUP, Dial, PJSIP_DIAL_CONTACTS, HANGUPCAUSE_KEYS, HANGUPCAUSE and HangupCauseClear references, the Asterisk CLI guide and the upstream func_dialgroup implementation were reviewed October 19, 2026. The generated Latest API pages reported branch 23; the installed Asterisk branch, loaded func_dialgroup module, dialplan revision, named-group lifecycle, concurrent writers, endpoint and contact state, channel-driver behavior and call outcomes remain deployment specific. No PBX, module, dialplan, group, endpoint, contact, channel, packet, media stream or live call was inspected or testedAdvancedDocumentation based · not lab tested

Use DIALGROUP for a dial list, not concurrency accounting

DIALGROUP(group,op) manages a named list of interfaces intended for use with Dial(). Reading ${DIALGROUP(frontline)} produces the list to dial. A write with no operation replaces the whole list; add and del are write-only membership operations.

This is distinct from GROUP() and GROUP_COUNT(), which label and count live channels, and from the Queue application, which owns queue policy and agent behavior. Choose DIALGROUP only when a dialplan-owned list with an explicit fallback matches the requirement.

Give membership one writer and one lifecycle

Name the group, define which dialplan path may replace it, which paths may add or delete members, and when an entry should leave. Prefer one owner that serializes administrative intent instead of letting unrelated call paths race to rewrite the same list.

The reviewed function reference documents operations and dial use, but it does not promise restart persistence, reload persistence, transactional multi-step edits or conflict resolution between concurrent writers. Prove those properties on the installed branch before depending on them, and use a persistent external owner when persistence is the actual requirement.

Keep interface strings and PJSIP contact expansion separate

A DIALGROUP member is a channel name or interface string. For PJSIP, decide whether the list contains an endpoint dial target or a dial string produced from current contacts. PJSIP_DIAL_CONTACTS(endpoint[,aor[,request_user]]) returns a properly formatted string for all contacts on the selected AoR.

Do not represent that contact snapshot as permanent membership or a guarantee that a device will answer. Preserve the endpoint, AoR, expansion time and resulting redacted dial string so stale group membership and changing registration state remain distinguishable.

Guard the empty-list and malformed-target boundaries

Read the group into a named variable, record its blank/nonblank state and apply an explicit fallback before calling Dial(). The DIALGROUP reference says dialplan execution may continue when no interfaces are available; that is a control-flow opportunity, not evidence that a queue fallback, voicemail destination or failure branch happened.

Validate member grammar at the writer. Do not concatenate untrusted dial strings, expose credentials in logs or assume a blank value proves which add, delete or replacement operation occurred.

Separate list construction from Dial outcomes

Dial() attempts one or more channels and sets DIALSTATUS after it returns. Preserve the exact group name, redacted value read immediately before Dial, timeout, relevant options, returned status and next priority. An apparently correct list can still produce CHANUNAVAIL, BUSY, NOANSWER or another documented result.

For multiple outbound legs, HANGUPCAUSE_KEYS() supplies the channel names with available causes and HANGUPCAUSE(channel,type) separates technology-specific from translated Asterisk cause information. Clear old cause data deliberately with HangupCauseClear() only when the trace requires a new cause set.

Test membership and routing as two contracts

In an authorized staging path, start from a recorded baseline, replace the list with two controlled targets, read it back, add one target, delete one target and exercise an empty-list fallback. Then test one registered target, one unavailable target and the intended later route while capturing DIALSTATUS and per-leg cause evidence.

Restore the original list and temporary logging. A successful membership edit does not prove device reachability, media, failover or queue behavior. This guide is documentation-derived; no PBX, module, group, endpoint, contact, channel or call was tested.

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 · Current Asterisk branch-23-generated and branch 22 Dial references, pre-dial-handler guidance, hangup-cause guidance, HANGUPCAUSE_KEYS and CHANNEL references reviewed October 15, 2026; installed branch, channel driver, loaded dialplan, endpoint, contact set, signaling, causes, bridge, media and caller treatment remain deployment specific; no host, module, dialplan, channel, endpoint, trunk, packet, bridge, media stream or live call was inspected or tested

Asterisk Dial: outbound legs, status, timing and continuation evidence

Follow one Dial invocation through created channels, provisional events, answer, bridge, return status and post-call continuation without collapsing per-leg evidence into one result.

Read guide →
Guide · Asterisk Latest API PJSIP_DIAL_CONTACTS, Dial, PJSIP_AOR, PJSIP_CONTACT and AMI object documentation plus PJSIP configuration relationships reviewed October 12, 2026; the generated pages reported branch 23, but the installed Asterisk version, endpoint, AoRs, contacts, registration expiry, qualification, dialplan, SIP responses and call legs remain deployment-specific, and no PBX, endpoint, AoR, contact, registration, device, channel, request, response or call was inspected or tested

Asterisk PJSIP_DIAL_CONTACTS: dial every current AoR contact

Build a call-time PJSIP dial string from the intended endpoint and AoR while keeping contact inventory, qualification, outbound channels and the winning answer independently observable.

Read guide →
Guide · Asterisk Latest API GROUP, GROUP_COUNT, GROUP_LIST and GROUP_MATCH_COUNT references generated from branch 23, channel architecture, variable-inheritance and Local-channel optimization documentation reviewed October 12, 2026; a group count is local channel state rather than a provider entitlement or complete call count, and no PBX, dialplan, group, channel, bridge, trunk, account, call, limit or denial was inspected or tested

Asterisk channel groups: counting concurrency without counting calls twice

Assign channels to explicit group and category names, interpret counts against the chosen call leg and lifecycle, and keep a local dialplan guard separate from trunk entitlement or platform capacity.

Read guide →
Guide · Current Asterisk branch-23-generated HANGUPCAUSE, HANGUPCAUSE_KEYS, HangupCauseClear, Dial and CHANNEL references plus the project mapping table reviewed October 6, 2026; exact behavior still depends on the installed Asterisk branch, channel driver, dialplan and call path

Asterisk hangup causes: preserve each called-channel result

Interpret Dial status, per-channel technology causes, translated Asterisk causes and hangup source without collapsing parallel or sequential call attempts into one reason.

Read guide →
Guide · Current Asterisk 22 dialplan, CLI, application and hangup-cause documentation reviewed October 1, 2026; no Asterisk host, dialplan, endpoint, trunk, call, media or emergency route was tested

Testing an Asterisk dialplan change safely

Prove context entry, extension matching, priority execution, call-leg outcomes and rollback without treating a successful reload as a successful call.

Read guide →
Troubleshooting · Current Asterisk Latest API DIALGROUP, Dial, PJSIP_DIAL_CONTACTS, HANGUPCAUSE_KEYS, HANGUPCAUSE and HangupCauseClear references, the Asterisk CLI guide and the upstream func_dialgroup implementation were reviewed October 19, 2026. The generated Latest API pages reported branch 23; the installed Asterisk branch, loaded func_dialgroup module, dialplan revision, named-group lifecycle, concurrent writers, endpoint and contact state, channel-driver behavior and call outcomes remain deployment specific. No PBX, module, dialplan, group, endpoint, contact, channel, packet, media stream or live call was inspected or tested

Asterisk DIALGROUP is empty, stale or dials the wrong targets

Trace one failed attempt through group ownership, the last membership operation, exact readback, PJSIP contact expansion, Dial status and per-leg cause evidence.

Read guide →