Skip to content
Thirdlane

Action Scripts

Action Scripts define the behavior that occurs when calls reach routes, extensions, and feature codes. Each action script contains dialplan commands that control how calls are processed.

Action scripts are used in Bulk Generator, User Extensions, Feature Codes, Voice Menus, Inbound Routes, Outbound Routes, and Hunt Groups.

The system ships with many built-in action scripts for common scenarios. You can clone and modify them or create your own.

Built-in action scripts are protected and cannot be modified or deleted. Clone one to create an editable copy. Use the Save Settings button on the Advanced tab to change where a built-in script is available.

Grid Features

Used column shows how many routes, extensions, and feature codes reference each action script. Hover over the count for a summary. Scripts with no Available In flags show a Hidden badge here, meaning they will not appear in any assignment dropdown.

Available In column shows colored badges for each area where the action script can be assigned (Inbound, User, Feature, Outbound, Other).

Available In filter allows you to show only action scripts intended for Inbound Routes, User Extensions, Feature Codes, etc.

Hiding Action Scripts

To hide an action script from all assignment dropdowns, open it and uncheck all Available In options on the Advanced tab. The script will show a Hidden badge in the Used column. Already-assigned scripts continue to function normally.

For built-in scripts, use the Save Settings button on the Advanced tab to save visibility changes.

Create/Edit Action Script

General Tab

Name. A short, descriptive name shown in dropdowns when assigning this action script.

Category. Group this action script belongs to, used for organizing the list.

Description. Longer explanation of what this action script does.

Internal Name. Unique alphanumeric identifier (no spaces). For new action scripts only. We recommend using a common prefix. Built-in action scripts use the “tl-” prefix, which should not be used for custom scripts.

Advanced Tab

Available In. Select which areas can use this action script: Inbound Routes, User Extensions, Feature Codes, Outbound Routes, or Other (internal use by other scripts). Unchecking all options hides the script from all dropdowns.

Dialplan Code. The Asterisk dialplan commands that execute when this action script runs. Standard macro rules apply, so arguments are referenced as ${ARG1}, ${ARG2}, etc.

Example:

exten => s,1,ExecIf($["${ARG6}" != ""]?Set(CHANNEL(musicclass)=${ARG6}))
exten => s,n,GotoIf($["${MACRO_EXTEN}" = "s"]?dial)
exten => s,n,Set(__DIALED_NUMBER=${MACRO_EXTEN})
exten => s,n(dial),Macro(tl-dialout-base,${ARG1},${ARG2},${ARG3},${ARG4},${ARG5})

Action Parameters. Define the parameters that an administrator fills in when assigning this action script (for example the trunk, destination number, or greeting). Click Add Argument to add one. Parameters are positional: the first argument is ${ARG1} in the dialplan code, the second ${ARG2}, and so on. Each argument has:

  • Argument Description: The label shown next to the field when the script is assigned.
  • Argument Type: The kind of value expected. This controls how the field is rendered - a plain text box, a numeric field, or a picker populated with the relevant objects (see the table below).
  • Multiple: Whether more than one value can be selected/entered (values are passed as an Asterisk-style list).
  • Required: Whether the field must be filled in before the assignment can be saved.
  • Choices: Only used by the Dropdown type. Enter the options as value=Label pairs separated by semicolons, for example original=Original caller;did=Our DID. No commas are allowed (commas separate arguments internally). Labels may be language keys, which are localized automatically.

Argument types

TypeRenders asValue passed to ${ARGn}
TextFree text boxThe entered text
Yes/No?Checkbox1 / 0
Dropdown (choices)Select box built from ChoicesThe selected option’s value
Phone(s) / Line(s)Phone/line pickerDevice name(s)
Extension(s)Extension pickerExtension number(s)
User Extension(s)User-extension pickerExtension number(s)
Feature Extension(s)Feature-code pickerFeature code(s)
Hunt GroupHunt Group pickerHunt Group name
Mailbox(es)Mailbox pickerMailbox number(s)
Voice MenuIVR/voice-menu pickerMenu name
ScheduleTime Range Group pickerSchedule name
TrunkTrunk pickerTrunk name
Queue(s)Queue pickerQueue name(s)
Conference RoomConference pickerRoom number
Recorded MessageRecorded-message (OGM) pickerPrompt name
Music-on-holdMusic-on-hold class pickerMOH class name

The Dropdown type is the general-purpose way to offer a fixed set of choices without wiring up a new picker. It is used, for example, by the built-in Forward to External Number script to let a route override the trunk’s Forwarded Caller ID policy per route.

Built-in scripts of note

Forward to External Number answers an inbound call, optionally plays a greeting and screens the caller, and forwards the call to an external number, with voicemail on no answer. Its trunk determines how the original caller ID is presented to the carrier via the trunk’s Forwarded Caller ID setting; the script’s own Caller ID method parameter (a Dropdown) can override that trunk default for an individual route. Leave it unset to inherit the trunk’s policy.

Which trunk the call goes back out

Leave Trunk blank and the call is forwarded out the trunk it arrived on. That is almost always what you want, because the carrier that delivered the DID is the one that owns it, and therefore the only one entitled to present it as the caller ID. The most common reason a carrier refuses a forwarded call is a caller ID it does not own.

Set a trunk only to force a different carrier, and if you do, check that the number the route ends up presenting is one that carrier will accept — either a number it owns in the trunk’s Forwarded Caller ID identity field, or an Outbound caller ID number on the route.

There is deliberately no second or backup trunk. A DID belongs to one carrier, so a second carrier would be asked to present a number it does not own and would refuse the call — redundancy of that kind has to be arranged at the carrier or SBC level, not per route. When the trunk cannot take the call at all, the caller goes to the route’s voicemail box.

Screening and the two timeouts

Turn Screen the call on when the destination is a mobile, so that the mobile’s own voicemail cannot swallow the call. The destination hears a prompt and has to press 1 to be connected. Any other key rejects the call, which sends the caller to the voicemail box configured on the route, or hangs up if the route has no box.

Pressing nothing is the case that makes screening worthwhile. A voicemail service that picks up never presses a key, so the call is treated as unanswered and moves on to the route’s voicemail box.

The two timeouts cover different parts of the call and add up:

  • Ring timeout (sec) is how long the destination is rung. It stops as soon as anything answers - including the destination’s voicemail, which counts as an answer.
  • Screening timeout (sec) is how long the destination then has to press a digit, chosen from a dropdown of 10 to 20 seconds. It defaults to 10. When it expires the call is treated as unanswered and goes to the voicemail box.

So a route with screening on, a 25-second ring timeout and a 10-second screening timeout can spend up to 25 seconds ringing plus the length of the prompt plus 10 seconds waiting for a digit before it moves on. Set Ring timeout shorter than the destination’s own voicemail delay if you want the PBX to give up before the mobile carrier answers.

The prompt itself is fixed - the same short one extension-level call screening uses, asking the destination to press 1 to accept or any other key to reject. A key pressed while it is still playing takes effect immediately, so a destination that knows the prompt never waits for it to finish.

Telling the destination who is calling

Announce caller controls what the destination hears before the accept prompt. It only applies when screening is on.

  • Do not announce - the destination goes straight to the accept prompt. The caller’s number is still delivered as caller ID, so it shows on the handset.
  • Read out the number - the caller’s number is spoken digit by digit. Useful when the call arrives on a mobile that shows your trunk’s number rather than the caller’s, so the handset display is not enough to decide.
  • Play name recorded by caller - the caller is asked to record their name before the call is placed, and the destination hears it. This adds roughly five seconds to the front of every screened call, before any ringing starts, and callers who say nothing produce an empty recording.

Choose “Read out the number” when the decision depends on who is calling and callers should not be delayed, and “Play name recorded by caller” when the destination needs more than a number to decide. Recordings are per call and are deleted when the call ends.