Overview
Asterisk 12 is a standard release of the Asterisk project. As such, the focus of development for this release was on core architectural changes and major new features. This includes:
- A more flexible bridging core based on the Bridging API
- A new internal message bus, Stasis
- Major standardization and consistency improvements to AMI
- Addition of the Asterisk REST Interface (ARI)
- A new SIP channel driver, chan_pjsip
In addition, as the vast majority of bridging in Asterisk was migrated to the Bridging API used by ConfBridge, major changes were made to most of the interfaces in Asterisk. This includes not only AMI, but also CDRs and CEL.
Specifications have been written for the affected interfaces:
It is highly recommended that anyone migrating to Asterisk 12 read the information regarding its release both in the CHANGES files and in the accompanying UPGRADE.txt file.
Build System
- Added build option
DISABLE_INLINE
. This option can be used to work around a bug in gcc. For more information, see http://gcc.gnu.org/bugzilla/show_bug.cgi?id=47816 - Removed the
CHANNEL_TRACE
development mode build option. Certain aspects of theCHANNEL_TRACE
build option were incompatible with the new bridging architecture. - Asterisk now optionally uses
libxslt
to improve XML documentation generation and maintainability. If libxslt is not available on the system, some XML documentation will be incomplete. - Asterisk now depends on
libjansson
. If a package oflibjansson
is not available on your distro, please see http://www.digip.org/jansson/. - Asterisk now depends on
libuuid
and, optionally,uriparser
. It is recommended that you installuriparser
, even if it is optional. - The new SIP stack and channel driver currently use a particular version of PJSIP. Please see https://wiki.asterisk.org/wiki/x/J4GLAQ for more information on configuring and installing PJSIP for usage with Asterisk.
Applications
AgentLogin
- Along with AgentRequest, this application has been modified to be a replacement for
chan_agent
. The act of a channel calling the AgentLogin application places the channel into a pool of agents that can be requested by the AgentRequest application. Note that this application, as well as all other agent related functionality, is now provided by theapp_agent_pool
module. See chan_agent and AgentRequest for more information. - This application no longer performs agent authentication. If authentication is desired, the dialplan needs to perform this function using the Authenticate or VMAuthenticate application or through an AGI script before running AgentLogin.
- If this application is called and the agent is already logged in, the dialplan will continue exection with the
AGENT_STATUS
channel variable set toALREADY_LOGGED_IN
. - The agents.conf schema has changed. Rather than specifying agents on a single line in comma delineated fashion, each agent is defined in a separate context. This allows agents to use the power of context templates in their definition.
- A number of parameters from agents.conf have been removed. This includes:
maxloginretries
autologoffunavail
updatecdr
goodbye
group
recordformat
urlprefix
savecallsin
app_agent_pool
.
AgentRequest
- A new application, this will request a logged in agent from the pool and bridge the requested channel with the channel calling this application. Logged in agents are those channels that called the AgentLogin application. If an agent cannot be requested from the pool, the
AGENT_STATUS
dialplan application will be set with an appropriate error value.
AgentMonitorOutgoing
- This application has been removed. It was a holdover from when AgentCallbackLogin was removed in Asterisk 1.6.0.
AlarmReceiver
Added support for additional Ademco DTMF signalling formats, including Express 4+1, Express 4+2, High Speed and Super Fast.
- Added channel variable
ALARMRECEIVER_CALL_LIMIT
. This sets the maximum call time, in milliseconds, to run the application. - Added channel variable
ALARMRECEIVER_RETRIES_LIMIT
. This sets the maximum number of times to retry the call. - Added a new configuration option
answait
. If set, the AlarmReceiver application will wait the number of milliseconds specified byanswait
after the channel has answered. Valid values range between 500 milliseconds and 10000 milliseconds. - Added configuration option
no_group_meta
. If enabled, grouping of metadata information in the AlarmReceiver log file will be skipped.
Answer
- It is now lo longer possible to bypass updating the CDR on the channel when answering. CDRs reflect the state of the channel and will always reflect the time they were Answered.
BridgeWait
- A new application in Asterisk, this will place the calling channel into a holding bridge, optionally entertaining them with some form of media. Channels participating in a holding bridge do not interact with other channels in the same holding bridge. Optionally, however, a channel may join as an announcer. Any media passed from an announcer channel is played to all channels in the holding bridge. Channels leave a holding bridge either when an optional timer expires, or via the ChannelRedirect application or AMI Redirect action.
ConfBridge
- All participants in a bridge can now be kicked out of a conference room by specifying the channel parameter as 'all' in the ConfBridge kick CLI command, i.e.,
confbridge kick <conference> all
- CLI output for the
confbridge list
command has been improved. When displaying information about a particular bridge, flags will now be shown for the participating users indicating properties of that user. - The ConfbridgeList event now contains the following fields:
WaitMarked
,EndMarked
, andWaiting
. This displays additional properties about the user's profile, as well as whether or not the user is waiting for a Marked user to enter the conference. - Added a new option for conference recording,
record_file_append
. If enabled, when the recording is stopped and then re-started, the existing recording will be used and appended to.
ConfBridge now has the ability to set the language of announcements to the conference. The language can be set on a bridge profile in confbridge.conf or by the dialplan function CONFBRIDGE(bridge, language)={langauge}.
ControlPlayback
- The channel variable
CPLAYBACKSTATUS
may now return the valueREMOTESTOPPED
. This occurs when playback is stopped by a remote interface, such as AMI. See the AMI action ControlPlayback for more information.
Directory
- Added the
a
option, which allows the caller to enter in an additional alias for the user in the directory. This option must be used in conjunction with thef
,l
, orb
options. Note that the alias for a user can be specified in voicemail.conf.
DumpChan
- The output of DumpChan no longer includes the
DirectBridge
orIndirectBridge
fields. Instead, if a channel is in a bridge, it includes aBridgeID
field containing the unique ID of the bridge that the channel happens to be in.
ForkCDR
- ForkCDR no longer automatically resets the forked CDR. See the
r
option for more information. - Variables are no longer purged from the original CDR. See the
v
option for more information. - The
A
option has been removed. The Answer time on a CDR is never updated once set. - The
d
option has been removed. The disposition on a CDR is a function of the state of the channel and cannot be altered. - The
D
option has been removed. Who the Party B is on a CDR is a function of the state of the respective channels involved in the CDR and cannot be altered. - The
r
option has been changed. Previously, ForkCDR always reset the CDR such that the start time and, if applicable, the answer time was updated. Now, by default, ForkCDR simply forks the CDR, maintaining any times. Ther
option now triggers the Reset, setting the start time (and answer time if applicable) to the current time. Note that thea
option still sets the answer time to the current time if the channel was already answered. - The
s
option has been removed. A variable can be set on the original CDR if desired using the CDR function, and removed from a forked CDR using the same function. - The
T
option has been removed. The concept ofDONT_TOUCH
andLOCKED
no longer applies in the CDR engine. - The
v
option now prevents the copy of the variables from the original CDR to the forked CDR. Previously the variables were always copied but were removed from the original. This was changed as removing variables from a CDR can have unintended side effects - this option allows the user to prevent propagation of variables from the original to the forked without modifying the original.
MeetMe
- Added the n option to MeetMe to prevent application of the DENOISE function to a channel joining a conference. Some channel drivers that vary the number of audio samples in a voice frame will experience significant quality problems if a denoiser is attached to the channel; this option gives them the ability to remove the denoiser without having to unload
func_speex
.
MixMonitor
- The
b
option now includes conferences as well as sounds played to the participants. - The AUDIOHOOK_INHERIT function is no longer needed to keep a MixMonitor running during a transfer. If a MixMonitor is started on a channel, the MixMonitor will continue to record the audio passing through the channel even in the presence of transfers.
NoCDR
- The NoCDR application is deprecated. Please use the CDR_PROP function to disable CDRs.
- While the NoCDR application will prevent CDRs for a channel from being propagated to registered CDR backends, it will not prevent that data from being collected. Hence, a subsequent call to ResetCDR or the CDR_PROP function that enables CDRs on a channel will restore those records that have not yet been finalized.
ParkAndAnnounce
- The
app_parkandannounce
module has been removed. The application ParkAndAnnounce is now provided by theres_parking
module. See the res_parking changes for more information.
Queue
Added queue available hint. The hint can be added to the dialplan using the following syntax:
exten => {exten},hint,Queue:{queue_name}_avail
For example, if the name of the queue is
markq
and the extension is8501
:exten => 8501,hint,Queue:markq_avail
This will report
In Use
if there are no logged in agents or no free agents. It will reportIdle
when an agent is free.Queues now support a hint for member paused state. The hint uses the following syntax:
exten => {exten},hint,Queue:{queue_name}_pause_{member_name}
Where
queue_name
andmember_name
are the name of the queue and the name of the member to subscribe to, respectively. For example, for the sales queue, with queue member mark at extension 8501:exten => 8501,hint,Queue:sales_pause_mark
Members will show as
In Use
when paused.- The configuration options
eventwhencalled
andeventmemberstatus
have been removed. As a result, the AMI events QueueMemberStatus, AgentCalled, AgentConnect, AgentComplete, AgentDump, and AgentRingNoAnswer will always be sent. The Variable fields will also no longer exist on theAgent*
events. These events can be filtered out from a connected AMI client using theeventfilter
setting in manager.conf. - The queue log now differentiates between blind and attended transfers. A blind transfer will result in a
BLINDTRANSFER
message with the destination context and extension. An attended transfer will result in anATTENDEDTRANSFER
message. This message will indicate the method by which the attended transfer was completed:BRIDGE
for a bridge merge,APP
for running an application on a bridge or channel, orLINK
for linking two bridges together with local channels. The queue log will also now detect externally initiated blind and attended transfers and record the transfer status accordingly. - When performing queue pause/unpause on an interface without specifying an individual queue, the
PAUSEALL
/{{UNPAUSEALL}} event will only be logged if at least one member of any queue exists for that interface. - Added the
queue_log_realtime_use_gmt
option to have timestamps in GMT for realtime queue log entries.
ResetCDR
- The
e
option has been deprecated. Use the CDR_PROP function to re-enable CDRs when they were previously disabled on a channel. - The
w
anda
options have been removed. Dispatching CDRs to registered backends occurs on an as-needed basis in order to preserve linkedid propagation and other needed behavior.
SayAlphaCase
A new application, this is similar to SayAlpha except that it supports case sensitive playback of the specified characters. For example:
same => n,SayAlphaCase(u,aBc)
Will result in 'a uppercase b c'.
SetAMAFlags
- This application is deprecated in favor of CHANNEL(amaflags).
SendDTMF
- The SendDTMF application will now accept
W
as valid input. This will cause the application to delay one second while streaming DTMF.
Stasis
- A new application in Asterisk 12, this hands control of the channel calling the application over to an external system. Currently, external systems manipulate channels in Stasis through the Asterisk REST Interface (ARI).
UserEvent
- UserEvent will now handle duplicate keys by overwriting the previous value assigned to the key.
- In addition to AMI, UserEvent invocations will now be distributed to any interested Stasis applications.
VoiceMail
- The voicemail.conf configuration file now has an
alias
configuration parameter for use with the Directory application. The voicemail realtime database table schema has also been updated with analias
column. - Mailboxes defined in
voicemail.conf
MUST be referenced by their full name by entities that want to subscribe for MWI, i.e.,mailbox@context
. Previously, Asterisk would automatically append "@default" to a mailbox name if it wasn't specified; however, in order to support other providers of voicemail, this is no longer possible.
Codecs
- Pass through support has been added for both VP8 and Opus.
- Added format attribute negotiation for the Opus codec. Format attribute negotiation is provided by the
res_format_attr_opus
module.
Core
- Masquerades as an operation inside Asterisk have been effectively hidden by the migration to the Bridging API. As such, many 'quirks' of Asterisk no longer occur. This includes renaming of channels, "<ZOMBIE>" channels, dropping of frame/audio hooks, and other internal implementation details that users had to deal with. This fundamental change has large implications throughout the changes documented for this version.
- Multiple parties in a bridge may now be transferred. If a participant in a multi-party bridge initiates a blind transfer, a Local channel will be used to execute the dialplan location that the transferer sent the parties to. If a participant in a multi-party bridge initiates an attended transfer, several options are possible. If the attended transfer results in a transfer to an application, a Local channel is used. If the attended transfer results in a transfer to another channel, the resulting channels will be merged into a single bridge.
- The channel variable
ATTENDED_TRANSFER_COMPLETE_SOUND
is no longer channel driver specific. If the channel variable is set on the transferrer channel, the sound will be played to the target of an attended transfer. - The channel variable
BRIDGEPEER
becomes a comma separated list of peers in a multi-party bridge. TheBRIDGEPEER
value can have a maximum of 10 peers listed. Any more peers in the bridge will not be included in the list. {{BRIDGEPEER}} is not valid in holding bridges like parking since those channels do not talk to each other even though they are in a bridge. - The channel variable
BRIDGEPVTCALLID
is only valid for two party bridges and will contain a value if theBRIDGEPEER
's channel driver supports it. - A channel variable
ATTENDEDTRANSFER
is now set which indicates which channel was responsible for an attended transfer in a similar fashion toBLINDTRANSFER
. - Modules using the Configuration Framework or Sorcery must have XML configuration documentation. This configuration documentation is included with the rest of Asterisk's XML documentation, and is accessible via CLI commands. See the CLI changes for more information.
AMI (Asterisk Manager Interface)
- Major changes were made to both the syntax as well as the semantics of the AMI protocol. In particular, AMI events have been substantially improved in this version of Asterisk. For more information, please see the AMI specification.
- AMI events that reference a particular channel or bridge will now always contain a standard set of fields. When multiple channels or bridges are referenced in an event, fields for at least some subset of the channels and bridges in the event will be prefixed with a descriptive name to avoid name collisions. See the AMI event documentation for more information.
- The CLI command
manager show commands
no longer truncates command names longer than 15 characters and no longer shows authorization requirement for commands.manager show command
now displays the privileges needed for using a given manager command instead. - The SIPshowpeer action will now include a SubscribeContext field for a peer in its response if the peer has a subscribe context set.
- The SIPqualifypeer action now acknowledges the request once it has established that the request is against a known peer. It also issues a new event, SIPQualifyPeerDone, once the qualify action has been completed.
- The PlayDTMF action now supports an optional Duration parameter. This specifies the duration of the digit to be played, in milliseconds.
- Added VoicemailRefresh action to allow an external entity to trigger mailbox updates when changes occur instead of requiring the use of
pollmailboxes
.
- Added a new action ControlPlayback. The ControlPlayback action allows an AMI client to manipulate audio currently being played back on a channel. The supported operations depend on the application being used to send audio to the channel. When the audio playback was initiated using the ControlPlayback application or CONTROL STREAM FILE AGI command, the audio can be paused, stopped, restarted, reversed, or skipped forward. When initiated by other mechanisms (such as the Playback application), the audio can be stopped, reversed, or skipped forward.
- Channel related events now contain a snapshot of channel state, adding new fields to many of these events.
- The AMI event Newexten field Extension is deprecated, and may be removed in a future release. Please use the common Exten field instead.
- The AMI event UserEvent from
app_userevent
now contains the channel state fields. The channel state fields will come before the body fields. - The AMI events ParkedCall, ParkedCallTimeOut, ParkedCallGiveUp, and UnParkedCall have changed significantly in the new
res_parking
module.- The Channel and From headers are gone.
- For the channel that was parked or is coming out of parking, a Parkee channel snapshot is issued and it has a number of fields associated with it. The old Channel header relayed the same data as the new ParkeeChannel header.
- The From field was ambiguous and changed meaning depending on the event. For most of these, it was the name of the channel that parked the call (the Parker).
- There is no longer a header that provides this channel name, however the ParkerDialString will contain a dialstring to redial the device that parked the call.
- On UnParkedCall events, the From header would instead represent the channel responsible for retrieving the parkee. It receives a channel snapshot labeled Retriever. The From field is is replaced with RetrieverChannel.
- Lastly, the Exten field has been replaced with ParkingSpace.
- The Channel and From headers are gone.
- The AMI event Parkinglot (response to Parkinglots command) in a similar fashion has changed the field names StartExten and StopExten to StartSpace and StopSpace respectively.
- The deprecated use of | (pipe) as a separator in the
channelvars
setting in manager.conf has been removed. - Channel Variables conveyed with a channel no longer contain the name of the channel as part of the key field, i.e.,
ChanVariable(SIP/foo): bar=baz
is nowChanVariable: bar=baz
. When multiple channels are present in a single AMI event, the various ChanVariable fields will contain a prefix that specifies which channel they correspond to. - The NewPeerAccount AMI event is no longer raised. The NewAccountCode AMI event always conveys the AMI event for a particular channel.
- All Reload events have been consolidated into a single event type. This event will always contain a Module field specifying the name of the module and a Status field denoting the result of the reload. All modules now issue this event when being reloaded.
- The ModuleLoadReport event has been removed. Most AMI connections would fail to receive this event due to being connected after modules have loaded. AMI connections that want to know when Asterisk is ready should listen for the FullyBooted event.
app_fax
now sends the same send fax/receive fax events asres_fax
. The FaxSent event is now the SendFAX event, and the FaxReceived event is now the ReceiveFAX event.- The MusicOnHold event is now two events: MusicOnHoldStart and MusicOnHoldStop. The sub type field has been removed.
- The JabberEvent event has been removed. It is not AMI's purpose to be a carrier for another protocol.
- The Bridge Manager action's Playtone header now accepts more fine-grained options.
Channel1
andChannel2
may be specified in order to play a tone to the specific channel.Both
may be specified to play a tone to both - channels. The old
yes
option is still accepted as a way of playing the tone toChannel2
only. - The AMI Status response event to the AMI Status action replaces the BridgedChannel and BridgedUniqueid headers with the BridgeID header to indicate what bridge the channel is currently in.
- The AMI Hold event has been moved out of individual channel drivers, into core, and is now two events: Hold and Unhold. The status field has been removed.
- The AMI events in
app_queue
have been made more consistent with each other. Events that reference channels (QueueCaller* and Agent*) will show information about each channel. The (infamous) Join and Leave AMI events have been changed to QueueCallerJoin and QueueCallerLeave. - The MCID AMI event now publishes a channel snapshot when available and its non-channel-snapshot parameters now use either the MCallerID or MConnectedID prefixes with Subaddr*, Name*, and Num* suffixes instead of CallerID and ConnectedID to avoid confusion with similarly named parameters in the channel snapshot.
- The AMI events Agentlogin and Agentlogoff have been renamed AgentLogin and AgentLogoff respectively.
- The Channel key used in the AlarmClear, Alarm, and DNDState has been renamed DAHDIChannel since it does not convey an Asterisk channel name.
- ChannelUpdate events have been removed.
- All AMI events now contain a SystemName field, if available.
- Local channel optimization is now conveyed in two events: LocalOptimizationBegin and LocalOptimizationEnd. The Begin event is sent when the Local channel driver begins attempting to optimize itself out of the media path; the End event is sent after the channel halves have successfully optimized themselves out of the media path.
- Local channel information in events is now prefixed with LocalOne and LocalTwo. This replaces the suffix of '1' and '2' for the two halves of the Local channel. This affects the LocalBridge, LocalOptimizationBegin, and LocalOptimizationEnd events.
- The option
allowmultiplelogin
can now be set or overriden in a particular account. When set in the general context, it will act as the default setting for defined accounts. - The BridgeAction event was removed. It technically added no value, as the Bridge Action already receives confirmation of the bridge through a successful completion Event.
- The BridgeExec events were removed. These events duplicated the events that occur in the Bridging API, and are conveyed now through BridgeCreate, BridgeEnter, and BridgeLeave events.
- The RTCPSent/RTCPReceived events have been significantly modified from previous versions. They now report all SR/RR packets sent/received, and have been restructured to better reflect the data sent in a SR/RR. In particular, the event structure now supports multiple report blocks.
- Added BlindTransfer and AttendedTransfer events. These events are raised when a blind transfer/attended transfer completes successfully. They contain information about the transfer that just completed, including the location of the transferred channel.
- Added a 'security' class authorization for security events emitted by AMI. Note that these events are produced by the Asterisk Security Event framework.
- The majority of Queue events have had the
Location
field renamed to theInterface
field.
CDR (Call Detail Records)
- Significant changes have been made to the behavior of CDRs. The CDR engine was effectively rewritten and built on the Stasis message bus. For a full definition of CDR behavior in Asterisk 12, please read the CDR specification for Asterisk 12.
- CDRs will now be created between all participants in a bridge. For each pair of channels in a bridge, a CDR is created to represent the path of communication between those two endpoints. This lets an end user choose who to bill for what during bridge operations with multiple parties.
- The
duration
,billsec
,start
,answer
, andend
times now reflect the times associated with the current CDR for the channel, as opposed to a cumulative measurement of all CDRs for that channel. - When a CDR is dispatched, user defined CDR variables from both parties are included in the resulting CDR. If both parties have the same variable, only the Party A value is provided.
- Added a new option to cdr.conf,
debug
. When enabled, significantly more information regarding the CDR engine is logged as verbose messages. This option should only be used if the behavior of the CDR engine needs to be debugged. - Added CLI command
cdr set debug {on|off
}. This toggles thedebug
setting normally configured in cdr.conf. - Added CLI command
cdr show active {channel
}. When{channel
} is not specified, this command provides a summary of the channels with CDR information and their statistics. When{channel
} is specified, it shows detailed information about all records associated with{channel
}.
CEL (Channel Event Logging)
- CEL has undergone significant rework in Asterisk 12, and is now built on the Stasis message bus. Please see the specification for CEL for more detailed information.
- The extra field of all CEL events that use it now consists of a JSON blob with key/value pairs which are defined in the Asterisk 12 CEL documentation. This JSON blob will be interpreted by the various CEL backends into their specific format.
BLINDTRANSFER
events now report the transferee bridge unique identifier, extension, and context in a JSON blob as the extra string instead of the transferee channel name as the peer.ATTENDEDTRANSFER
events now report the peer as NULL and additional information in the 'extra' string as a JSON blob. For transfers that occur between two bridged channels, the 'extra' JSON blob contains the primary bridge unique identifier, the secondary channel name, and the secondary bridge unique identifier. For transfers that occur between a bridged channel and a channel running an app, the 'extra' JSON blob contains the primary bridge unique identifier, the secondary channel name, and the app name.LOCAL_OPTIMIZE
events have been added to convey local channel optimizations with the record occurring for the semi-one channel and the semi-two channel name in the peer field.BRIDGE_START
,BRIDGE_END
,BRIDGE_UPDATE
,3WAY_START
,3WAY_END
,CONF_ENTER
,CONF_EXIT
,CONF_START
, andCONF_END
events have all been removed. These events have been replaced byBRIDGE_ENTER
/BRIDGE_EXIT
. TheBRIDGE_ENTER
andBRIDGE_EXIT
events are raised when a channel enters/exits any bridge, regardless of whether or not that bridge happens to contain multiple parties.
CLI
- When compiled with
--enable-dev-mode
, theastobj2
library will now add several CLI commands that allow for inspection ofao2
containers that register themselves withastobj2
. The CLI commands are:astobj2 container dump
astobj2 container stats
astobj2 container check
- Added specific CLI commands for bridge inspection. This includes:
bridge show all
- list all bridges in the systembridge show {id
} - provide specific information about a bridge
- Added CLI command
bridge destroy
. This will destroy the specified bridge, ejecting the channels currently in the bridge. If the channels cannot continue in the dialplan or application that put them in the bridge, they will be hung up. - Added command
bridge kick
. This will eject a single channel from a bridge. - Added commands to inspect and manipulate the registered bridge technologies. This includes:
bridge technology show
- list the registered bridge technologiesbridge technology {suspend|unsuspend} {tech}
- control whether or not a registered bridge technology can be used during smart bridge operations. If a technology is suspended, it will not be used when a bridge technology is picked for channels; when unsuspended, it can be used again.
- The command
config show help
will show configuration documentation for modules with XML configuration documentation. This takes in three optional parameters -module
,type
, andoption -
which, when provided, provider greater detail.- When
module
,type
, andoption
are omitted, a listing of all modules with registered documentation is displayed. - When
module
is specified, a listing of all configuration types for that module is displayed, along with their synopsis. - When
module
andtype
are specified, a listing of all configuration options for that type are displayed along with their synopsis. - When
module
,type
, andoption
are specified, detailed information for that configuration option is displayed.
- When
- Added
core show sounds
andcore show sound
CLI commands. These display a listing of all installed media sounds available on the system and detailed information about a sound, respectively. xmldoc dump
has been added. This CLI command will dump the XML documentation DOM as a string to the specified file. The Asterisk core will populate certain XML elements pulled from the source files with additional run-time information; this command lets a user produce the XML documentation with all information.
Features
- Parking has been pulled from core and placed into a separate module called res_parking. Configuration for parking should now be performed in res_parking.conf. Configuration for parking in features.conf is now unsupported.
- Core attended transfers now have several new options. While performing an attended transfer, the transferer now has the following options:
*1
- cancel the attended transfer (configurable viaatxferabort
)*2
- complete the attended transfer, dropping out of the call (configurable viaatxfercomplete
)*3
- complete the attended transfer, but stay in the call. This will turn the call into a multi-party bridge (configurable viaatxferthreeway
)*4
- swap to the other party. Once an attended transfer has begun, this options may be used multiple times (configurable viaatxferswap
)
- For DTMF blind and attended transfers, the channel variable
TRANSFER_CONTEXT
must be on the channel initiating the transfer to have any effect. - The
BRIDGE_FEATURES
channel variable would previously only set features for the calling party and would set this feature regardless of whether the feature was in caps or in lowercase. Use of a caps feature for a letter will now apply the feature to the calling party while use of a lowercase letter will apply that feature to the called party. - Add support for
automixmon
to theBRIDGE_FEATURES
channel variable. - The channel variable
DYNAMIC_PEERNAME
is redundant withBRIDGEPEER
and is removed. The more usefulDYNAMIC_WHO_ACTIVATED
gives the channel name that activated the dynamic feature. - The channel variables
DYNAMIC_FEATURENAME
andDYNAMIC_WHO_ACTIVATED
are set only on the channel executing the dynamic feature. Executing a dynamic feature on the bridge peer in a multi-party bridge will execute it on all peers of the activating channel. - You can now have the settings for a channel updated using the FEATURE() and FEATUREMAP() functions inherited to child channels by setting
FEATURE(inherit)=yes
. automixmon
now supports additional channel variables fromautomon
including:TOUCH_MIXMONITOR_PREFIX
,TOUCH_MIXMONITOR_MESSAGE_START
, andTOUCH_MIXMONITOR_MESSAGE_STOP
.- A new general features.conf option
recordingfailsound
has been added which allows setting a failure sound for a user tries to invoke a recording feature such asautomon
orautomixmon
and it fails. - It is no longer necessary (or possible) to define the
ATXFER_NULL_TECH
infeatures.c
foratxferdropcall=no
to work properly. This option now just works.
Logging
- Added log rotation strategy
none
. If set, no log rotation strategy will be used. Given that this can cause the Asterisk log files to grow quickly, this option should only be used if an external mechanism for log management is preferred.
Realtime
- Dynamic realtime tables for SIP Users can now include a
path
field. This will store the path information for that peer when it registers. Realtime tables can also use thesupportpath
field to enable Path header support. - LDAP realtime configurations for SIP Users now have the
AstAccountPathSupport
objectIdentifier
. This maps to thesupportpath
option in sip.conf.
Sorcery
- Sorcery is a new data abstraction and object persistence API in Asterisk. It provides modules a useful abstraction on top of the many storage mechanisms in Asterisk, including the Asterisk Database, static configuration files, static Realtime, and dynamic Realtime. It also provides a caching service. Users can configure a hierarchy of data storage layers for specific modules in sorcery.conf.
- All future modules which utilize Sorcery for object persistence must have a column named
id
within their schema when using the Sorcery realtime module. This column must be able to contain a string of up to 128 characters in length.
Security Events Framework
- Security Event timestamps now use ISO 8601 formatted date/time instead of the
seconds-microseconds
format that it was using previously.
Stasis Message Bus
- The Stasis message bus is a publish/subscribe message bus internal to Asterisk. Many services in Asterisk are built on the Stasis message bus, including AMI, ARI, CDRs, and CEL. Parameters controlling the operation of Stasis can be configured in stasis.conf. Note that these parameters operate at a very low level in Asterisk, and generally will not require changes.
Channel Drivers
- When a channel driver is configured to enable jiterbuffers, they are now applied unconditionally when a channel joins a bridge. If a jitterbuffer is already set for that channel when it enters, such as by the JITTERBUFFER function, then the existing jitterbuffer will be used and the one set by the channel driver will not be applied.
chan_agent
chan_agent
has been removed and replaced with AgentLogin and AgentRequest dialplan applications provided by theapp_agent_pool
module. Agents are connected with callers using the new AgentRequest dialplan application. TheAgents:<agent-id>
device state is available to monitor the status of an agent. See agents.conf.sample for valid configuration options.- The
updatecdr
option has been removed. Altering the names of channels on a CDR is not supported - the name of the channel is the name of the channel, and pretending otherwise helps no one. TheAGENTUPDATECDR
channel variable has also been removed, for the same reason. - The
endcall
andenddtmf
configuration options are removed. Use the dialplan functionCHANNEL(dtmf-features)
to set DTMF features on the agent channel before calling AgentLogin.
chan_bridge
chan_bridge
has been removed. Its functionality has been incorporated directly into the ConfBridge application itself.
chan_dahdi
- Added the CLI command
pri destroy span
. This will destroy the D-channel of the specified span and its B-channels. Note that this command should only be used if you understand the risks it entails. - The CLI command
dahdi destroy channel
is nowdahdi destroy channels
. A range of channels can be specified to be destroyed. Note that this command should only be used if you understand the risks it entails. - Added the CLI command
dahdi create channels
. A range of channels can be specified to be created, or the keywordnew
can be used to add channels not yet created. - The script specified by the
chan_dahdi.conf
mwimonitornotify
option now gets the exact configured mailbox name. Forapp_voicemail
mailboxes this ismailbox@context
. - Added
mwi_vm_boxes
that also must be configured for ISDN MWI to be enabled.
chan_iax2
- IPv6 support has been added. chan_iax2 is now able to bind to and communicate using IPv6 addresses.
chan_local
- The
/b
option has been removed. chan_local
moved into the system core and is no longer a loadable module.
chan_mobile
- Added general support for busy detection.
- Added ECAM command support for Sony Ericsson phones.
chan_pjsip
- A new SIP channel driver for Asterisk, chan_pjsip is built on the PJSIP SIP stack. A collection of resource modules provides the bulk of the SIP functionality. For more information on configuring the new SIP channel driver, see the Configuring res_pjsip.
chan_sip
- Added support for RFC 3327 "Path" headers. This can be enabled in sip.conf using the
supportpath
setting, either on a global basis or on a peer basis. This setting enables Asterisk to route outgoing out-of-dialog requests via a set of proxies by using a pre-loaded route-set defined by the Path headers in theREGISTER
request. See Realtime updates for more configuration information. The
SIP_CODEC
family of variables may now specify more than one codec. Each codec must be separated by a comma. The first codec specified is the preferred codec for the offer. This allows a dialplan writer to specify both audio and video codecs, e.g.,same => n,Set(SIP_CODEC=ulaw,h264)
- The
callevents
parameter has been removed. Hold AMI events are now raised in the core, and can be filtered out using theeventfilter
parameter in manager.conf. - Added
ignore_requested_pref
. When enabled, this will use the preferred codecs configured for a peer instead of the requested codec. - The option
register_retry_403
has been added to chan_sip to work around servers that are known to erroneously send 403 in response to valid REGISTER requests and allows Asterisk to continue attepmting to connect.
chan_skinny
- Added the
immeddialkey
parameter. If set, when the user presses the configured key the already entered number will be immediately dialed. This is useful when the dialplan allows for variable length pattern matching. Valid options are*
and#
. - Added the
callfwdtimeout
parameter. This configures the amount of time (in milliseconds) before a call forward is considered to not be answered. - The
serviceurl
parameter allows Service URLs to be attached to line buttons.
Functions
AGENT
- The password option has been disabled, as the AgentLogin application no longer provides authentication.
AUDIOHOOK_INHERIT
- Due to changes in the Asterisk core, this function is no longer needed to preserve a MixMonitor on a channel during transfer operations and dialplan execution. It is effectively obsolete.
CDR (function)
- The
amaflags
andaccountcode
attributes for the CDR function are deprecated. Use the CHANNEL function instead to access these attributes. - The
l
option has been removed. When reading a CDR attribute, the most recent record is always used. When writing a CDR attribute, all non-finalized CDRs are updated. - The
r
option has been removed, for the same reason as thel
option. - The
s
option has been removed, asLOCKED
semantics no longer exist in the CDR engine.
CDR_PROP
- A new function CDR_PROP has been added. This function lets you set properties on a channel's active CDRs. This function is write-only. Properties accept boolean values to set/clear them on the channel's CDRs. Valid properties include:
-
party_a
- make this channel the preferred Party A in any CDR between two channels. If two channels have this property set, the creation time of the channel is used to determine who is Party A. Note that dialed channels are ever Party A in a CDR. disable
- disable CDRs on this channel. This is analogous to the NoCDR application when set toTrue
, and analogous to thee
option in ResetCDR when set toFalse
.
-
CHANNEL
- Added the argument
dtmf_features
. This sets the DTMF features that will be enabled on a channel when it enters a bridge. Allowed values areT
,K
,H
,W
, andX
, and are analogous to the parameters passed to the Dial application. - Added the argument
after_bridge_goto
. This can be set to a parseable Goto string, i.e.,[[context],extension],priority
. When set, if a channel leaves a bridge but is not hung up it will resume dialplan execution at that location.
JITTERBUFFER
- JITTERBUFFER now accepts an argument of
disabled
which can be used to remove jitterbuffers previously set on a channel with JITTERBUFFER. The value of this setting is ignored when disabled is used for the argument.
PJSIP_DIAL_CONTACTS
- A new function provided by
chan_pjsip
, this function can be used in conjunction with the Dial application to construct a dial string that will dial all contacts on an Address of Record associated with achan_pjsip
endpoint.
PJSIP_MEDIA_OFFER
- Provided by
chan_pjsip
, this function sets the codecs to be offered on the outbound channel prior to dialing.
REDIRECTING
- Redirecting reasons can now be set to arbitrary strings. This means that the REDIRECTING dialplan function can be used to set the redirecting reason to any string. It also allows for custom strings to be read as the redirecting reason from SIP Diversion headers.
SPEECH_ENGINE
- The SPEECH_ENGINE function now supports read operations. When read from, it will return the current value of the requested attribute.
VMCOUNT
- Mailboxes defined by
app_voicemail
MUST be referenced by the rest of the system asmailbox@context
. The rest of the system cannot add@default
to mailbox identifiers forapp_voicemail
that do not specify a context any longer. It is a mailbox identifier format that should only be interpreted byapp_voicemail
.
Resources
res_agi (Asterisk Gateway Interface)
- The manager event AGIExec has been split into AGIExecStart and AGIExecEnd.
- The manager event AsyncAGI has been split into AsyncAGIStart, AsyncAGIExec, and AsyncAGIEnd.
- The CONTROL STREAM FILE command now accepts an
offsetms
parameter. This will start the playback of the audio at the position specified. It will also return the final position of the file inendpos
. - The CONTROL STREAM FILE command will now populate the
CPLAYBACKSTATUS
channel variable if the user stopped the file playback or if a remote entity stopped the playback. If neither stopped the playback, it will indicate the overall success/failure of the playback. If stopped early, the final offset of the file will be set in theCPLAYBACKOFFSET
channel variable. - The SAY ALPHA command now accepts an additional parameter to control whether it specifies the case of uppercase, lowercase, or all letters to provide functionality similar to SayAlphaCase.
res_ari (Asterisk REST Interface) (and others)
- The Asterisk REST Interface (ARI) provides a mechanism to expose and control telephony primitives in Asterisk by remote client. This includes channels, bridges, endpoints, media, and other fundamental concepts. Users of ARI can develop their own communications applications, controlling multiple channels using an HTTP REST interface and receiving JSON events about the objects via a WebSocket connection. ARI can be configured in Asterisk via ari.conf .
res_parking
- Parking has been extracted from the Asterisk core as a loadable module,
res_parking
. Configuration for parking is now provided by res_parking.conf. Configuration through features.conf is no longer supported.
- Parked calls are now placed in bridges. While this is largely an architectural change, it does have implications on how channels in a parking lot are viewed. For example, commands that display channels in bridges will now also display the channels in a parking lot.
- The order of arguments for the new parking applications have been modified. Timeout and return
context/exten/priority
are now implemented as options, while the name of the parking lot is now the first parameter. See the application documentation for Park, ParkedCall, and ParkAndAnnounce for more in-depth information as well as syntax. - Extensions are by default no longer automatically created in the dialplan to park calls or pickup parked calls. Generation of dialplan extensions can be enabled using the
parkext
configuration option. - ADSI functionality for parking is no longer supported. The
adsipark
configuration option has been removed as a result. - The
PARKINGSLOT
channel variable has been deprecated in favor ofPARKING_SPACE
to match the naming scheme of the new system. PARKING_SPACE
andPARKEDLOT
channel variables will now be set for a parked channel even when the configuration optioncomebactoorigin
is enabled.- A new CLI command
parking show
has been added. This allows a user to inspect the parking lots that are currently in use.parking show <parkinglot>
will also show the parked calls in a specific parking lot. - The CLI command
parkedcalls
is now deprecated in favor ofparking show <parkinglot>
. - The AMI command ParkedCalls will now accept a ParkingLot argument which can be used to get a list of parked calls for a specific parking lot.
- The AMI command Park field Channel2 has been deprecated and replaced with TimeoutChannel. If both Channel2 and TimeoutChannel are specified, TimeoutChannel will be used. The field TimeoutChannel is no longer a required argument.
- The ParkAndAnnounce application is now provided through
res_parking
instead of through the separateapp_parkandannounce
module.
- ParkAndAnnounce will no longer go to the next position in dialplan on timeout by default. Instead, it will follow the timeout rules of the parking lot. The old behavior can be reproduced by using the
c
option. - Dynamic parking lots will now fail to be created under the following conditions:
- If the parking lot specified by
PARKINGDYNAMIC
does not exist. - If they require exclusive park and parked call extensions which overlap with existing parking lots.
- If the parking lot specified by
- Dynamic parking lots will be cleared on reload for dynamic parking lots that currently contain no calls. Dynamic parking lots containing parked calls will persist through the reloads without alteration.
- If
parkext_exclusive
is set for a parking lot and that extension is already in use when that parking lot tries to register it, this is now considered a parking system configuration error. Configurations which do this will be rejected. - Added channel variable
PARKER_FLAT
. This contains the name of the extension that would be used ifcomebacktoorigin
is enabled. This can be useful whencomebacktoorigin
is disabled, but the dialplan or an external control mechanism wants to use the extension in the park-dial context that was generated to re-dial the parker on timeout.
res_pjsip (and many others)
- A large number of resource modules make up the SIP stack based on PJSIP. The
chan_pjsip
channel driver users these resource modules to provide various SIP functionality in Asterisk. The majority of configuration for these modules is performed in pjsip.conf . Other modules may use their own configuration files. See Asterisk 12 Module Configuration for more information.
res_rtp_asterisk
- ICE/STUN/TURN support in
res_rtp_asterisk
has been made optional. To enable them, the Asterisk-specific version of PJSIP should now be installed. Tarballs are available from https://github.com/asterisk/pjproject/tags/.
res_statsd/res_chan_stats
- A new resource module,
res_statsd
, has been added, which acts as a statsd client. This module allows Asterisk to publish statistics to a statsd server. In conjunction withres_chan_stats
, it will publish statistics about Asterisk channels to the statsd server. It can be configured via res_statsd.conf.
res_xmpp
Device state for XMPP buddies is now available using the following format:
XMPP/<client name>/<buddy address>
If any resource is available the device state is considered to be not in use. If no resources exist or all are unavailable the device state is considered to be unavailable.
Scripts
Realtime/Database Scripts
- Asterisk previously included example db schemas in the
contrib/realtime/
directory of the source tree. This has been replaced by a set of database migrations using the Alembic framework. This allows you to use Alembic to initialize the database for you. It will also serve as a database migration tool when upgrading Asterisk in the future. See contrib/ast-db-manage/README.md for more details.
sip_to_res_pjsip.py
- A new script has been added in the
contrib/scripts/sip_to_res_pjsip
folder. This python script will convert an existing sip.conf file to a pjsip.conf file, for use with thechan_pjsip
channel driver. This script is meant to be an aid in converting an existingchan_sip
configuration to achan_pjsip
configuration, but it is expected that configuration beyond what the script provides will be needed.