Skip to content

Latest commit

 

History

History
371 lines (285 loc) · 18.3 KB

ARI_HISTORY.md

File metadata and controls

371 lines (285 loc) · 18.3 KB

ARI History

The change notes listed here are extracted from the CHANGES and UPGRADE-#.txt files from the Asterisk source tree. A copy of the full files can be found in the Asterisk github mirror. This file is a lens into the ARI changes made to Asterisk since ARI was introduced in Asterisk 12.

Asterisk 18.0.0

  • A new parameter inhibitConnectedLineUpdates is now available in the bridges.addChannel call. This prevents the identity of the newly connected channel from being presented to other bridge members.

  • The Channel resource has a new sub-resource externalMedia. This allows an application to create a channel for the sole purpose of exchanging media with an external server. Once created, this channel could be placed into a bridge with existing channels to allow the external server to inject audio into the bridge or receive audio from the bridge. See https://wiki.asterisk.org/wiki/display/AST/External+Media+and+ARI for more information.

  • Adds support for AudioSocket, a very simple bidirectional audio streaming protocol. There are both channel and application interfaces.

    A description of the protocol can be found on the referenced wiki page. A short talk about the reasons and implementation can be found on YouTube at the link provided.

    ARI support has also been added via the existing externalMedia ARI functionality. The UUID is specified using the arbitrary data field.

    Wiki: https://wiki.asterisk.org/wiki/display/AST/AudioSocket YouTube: https://www.youtube.com/watch?v=tjduXbZZEgI

  • In order to reduce the amount of AMI and ARI events generated, the global "Message/ast_msg_queue" channel can be set to suppress its normal channel housekeeping events such as "Newexten", "VarSet", etc. This can greatly reduce load on the manager and ARI applications when the Digium Phone Module for Asterisk is in use. To enable, set "hide_messaging_ami_events" in asterisk.conf to "yes" In Asterisk versions <18, the default is "no" preserving existing behavior. Beginning with Asterisk 18, the option will default to "yes".

  • When creating a channel in ARI using the create call you can now specify dialplan variables to be set as part of the same operation.

Asterisk 16.3.0

  • Application event filtering is now supported. An application can now specify an "allowed" and/or "disallowed" list(s) of event types. Only those types indicated in the "allowed" list are sent to the application. Conversely, any types defined in the "disallowed" list are not sent to the application. Note that if a type is specified in both lists "disallowed" takes precedence.

  • A new REST API call has been added: 'move'. It follows the format 'channels/{channelId}/move' and can be used to move channels from one application to another without needing to exit back into the dialplan. An application must be specified, but the passing a list of arguments to the new application is optional. An example call would look like this:

    client.channels.move(channelId=chan.id, app='ari-example', appArgs='a,b,c')

    If the channel was inside of a bridge when switching applications, it will remain there. If the application specified cannot be moved to, then the channel will remain in the current application and an event will be triggered named "ApplicationMoveFailed", which will provide the destination application's name and the channel information.

Asterisk 16.2.0

  • Whenever an ARI application is started, a context will be created for it automatically as long as one does not already exist, following the format 'stasis-<app_name>'. Two extensions are also added to this context: a match-all extension, and the 'h' extension. Any phone that registers under this context will place all calls to the corresponding Stasis application.

Asterisk 16

  • The ContactInfo event's contact_status field is now set to "NonQualified" when a contact exists but has not been qualified.

Asterisk 14.3.0

  • The ari set debug command has been enhanced to accept 'all' as an application name. This allows dumping of all apps even if an app hasn't registered yet.

  • ari set debug now displays requests and responses as well as events.

Asterisk 14.2.0

  • The bridges resource now exposes two new operations:

    • POST /bridges/{bridgeId}/videoSource/{channelId}: Set a video source in a multi-party mixing bridge
    • DELETE /bridges/{bridgeId}/videoSource: Remove the set video source, reverting to talk detection for the video source

  • The bridge model in any returned response or event now contains the following optional fields: - video_mode: the video source mode for the bridge. Can be one of 'none', 'talker', or 'single'. - video_source_id: the unique ID of the channel that is the video source in this bridge, if one exists.

  • A new event, BridgeVideoSourceChanged, has been added for bridges. Applications subscribed to a bridge will receive this event when the source of video changes in a mixing bridge.

  • The ARI major version has been bumped. There are not any known breaking changes in ARI. The major version has been bumped because otherwise we can end up with overlapping version numbers between different Asterisk versions. Now each major version of Asterisk will bring with it a change in the major version of ARI. The ARI version in Asterisk 14 is now 2.0.0.

  • Three new CLI commands have been added for ARI:

    • ari show apps: Displays a listing of all registered ARI applications.
    • ari show app <name>: Display detailed information about a registered ARI application.
    • ari set debug <name> <on|off>: Enable/disable debugging of an ARI application. When debugged, verbose information will be sent to the Asterisk CLI.

  • The configuration file ari.conf now supports a channelvars option, which specifies a list of channel variables to include in each channel-oriented ARI event.

Asterisk 14.1.0

  • ARI events will all now include a new field in the root of the JSON message, 'asterisk_id'. This will be the unique ID for the Asterisk system transmitting the event. The value can be overridden using the 'entityid' setting in asterisk.conf.

Asterisk 14.0.0

  • A new ARI method has been added to the channels resource. "create" allows for you to create a new channel and place that channel into a Stasis application. This is similar to origination except that the specified channel is not dialed. This allows for an application writer to create a channel, perform manipulations on it, and then delay dialing the channel until later.

  • To complement the "create" method, a "dial" method has been added to the channels resource in order to place a call to a created channel.

  • All operations that initiate playback of media on a resource now support a list of media URIs. The list of URIs are played in the order they are presented to the resource. A new event, "PlaybackContinuing", is raised when a media URI finishes but before the next media URI starts. When a list is played, the "Playback" model will contain the optional attribute "next_media_uri", which specifies the next media URI in the list to be played back to the resource. The "PlaybackFinished" event is raised when all media URIs are done.

  • Stored recordings now allow for the media associated with a stored recording to be retrieved. The new route, GET /recordings/stored/{name}/file, will transmit the raw media file to the requester as binary.

  • "Dial" events have been modified to not only be sent when dialing begins and ends. They now are also sent for intermediate states, such as "RINGING", "PROGRESS", and "PROCEEDING".

  • The policy for when to send "Dial" events has changed. Previously, "Dial" events were sent on the calling channel's topic. However, starting in Asterisk 14, if there is no calling channel on which to send the event, the event is instead sent on the called channel's topic. Note that for the ARI channels resource's dial operation, this means that the "Dial" events will always be sent on the called channel's topic.

Asterisk 13.10.0

  • Added 'formats' to channel create/originate to allow setting the allowed formats for a channel when no originator channel is available. Especially useful for Local channel creation where no other format information is available. 'core show codecs' can now be used to look up suitable format names.

Asterisk 13.6.0

  • Two new endpoint related events are now available: PeerStatusChange and ContactStatusChange. In particular, these events are useful when subscribing to all event sources, as they provide additional endpoint related information beyond the addition/removal of channels from an endpoint.

  • Added the ability to subscribe to all ARI events in Asterisk, regardless of whether the application 'controls' the resource. This is useful for scenarios where an ARI application merely wants to observe the system, as opposed to control it. There are two ways to accomplish this:

    1. Via the WebSocket connection URI. A new query parameter, 'subscribeAll',
has been added that, when present and True, will subscribe all
specified applications to all ARI event sources in Asterisk.

2. Via the applications resource. An ARI client can, at any time, subscribe
to all resources in an event source merely by not providing an explicit
resource. For example, subscribing to an event source of 'channels:'
as opposed to 'channels:12345' will subscribe the application to all
channels.

  • A new feature has been added to the Asterisk resource that allows for log channels to be manipulated.

Asterisk 13.5.0

  • A new feature has been added that enables the retrieval of modules and module information through an HTTP request. Information on a single module can be also be retrieved. Individual modules can be loaded to Asterisk, as well as unloaded and reloaded.

  • A new resource has been added to the 'asterisk' resource, 'config/dynamic'. This resource allows for push configuration of sorcery derived objects within Asterisk. The resource supports creation, retrieval, updating, and deletion. Sorcery derived objects that are manipulated by this resource must have a sorcery wizard that supports the desired operations.

Asterisk 13.4.0

  • Two new events, 'ChannelHold' and 'ChannelUnhold', have been added to the events data model. These events are raised when a channel indicates a hold or unhold, respectively.

Asterisk 13.3.0

  • The ARI /channels resource now supports a new operation, 'redirect'. The redirect operation will perform a technology and state specific redirection on the channel to a specified endpoint or destination. In the case of SIP technologies, this is either a 302 Redirect response to an on-going INVITE dialog or a SIP REFER request.

Asterisk 13.2.0

  • The Originate operation now takes in an originator channel. The linked ID of this originator channel is applied to the newly originated outgoing channel. If using CEL this allows an association to be established between the two so it can be recognized that the originator is dialing the originated channel.

  • "language" (the default spoken language for the channel) is now included in the standard channel state output for suitable events.

  • The POST channels/{id} operation and the POST channels/{id}/continue operation now have a new "label" parameter. This allows for origination or continuation to a labeled priority in the dialplan instead of requiring a specific priority number. The ARI version has been bumped to 1.7.0 as a result.

Asterisk 13.1.0

  • Event ChannelConnectedLine is emitted when the connected line information on a channel changes.

Asterisk 13.0.0

  • A bug fix in bridge creation has caused a behavioural change in how subscriptions are created for bridges. A bridge created through ARI, does not, by itself, have a subscription created for any particular Stasis application. When a channel in a Stasis application joins a bridge, an implicit event subscription is created for that bridge as well. Previously, when a channel left such a bridge, the subscription was leaked; this allowed for later bridge events to continue to be pushed to the subscribed applications. That leak has been fixed; as a result, bridge events that were delivered after a channel left the bridge are no longer delivered. An application must subscribe to a bridge through the applications resource if it wishes to receive all events related to a bridge.

Asterisk 12.5.0

  • Stored recordings now support a new operation, copy. This will take an existing stored recording and copy it to a new location in the recordings directory.

  • LiveRecording objects now have three additional fields that can be reported in a RecordingFinished ARI event:

    • total_duration: the duration of the recording
    • talking_duration: optional. The duration of talking detected in the recording. This is only available if max_silence_seconds was specified when the recording was started.
    • silence_duration: optional. The duration of silence detected in the recording. This is only available if max_silence_seconds was specified when the recording was started. Note that all duration values are reported in seconds.

  • Users of ARI can now send and receive out of call text messages. Messages can be sent directly to a particular endpoint, or can be sent to the endpoints resource directly and inferred from the URI scheme. Text messages are passed to ARI clients as TextMessageReceived events. ARI clients can choose to receive text messages by subscribing to the particular endpoint technology or endpoints that they are interested in.

  • The applications resource now supports subscriptions to all endpoints of a particular channel technology. For example, subscribing to an eventSource of 'endpoint:PJSIP' will subscribe to all PJSIP endpoints.

Asterisk 12.4.0

  • New event models have been aded for the TALK_DETECT function. When the function is used on a channel, ChannelTalkingStarted/ChannelTalkingFinished events will be emitted to connected WebSockets subscribed to the channel, indicating the start/stop of talking on the channel.

Asterisk 12.3.0

  • A new Playback URI 'tone' has been added. Tones are specified either as an indication name (e.g. 'tone:busy') from indications.conf or as a tone pattern (e.g. 'tone:240/250,0/250'). Tones differ from normal playback URIs in that they must be stopped manually and will continue to occupy a channel's ARI control queue until they are stopped. They also can not be rewound or fastforwarded.

  • User events can now be generated from ARI. Events can be signalled with arbitrary json variables, and include one or more of channel, bridge, or endpoint snapshots. An application must be specified which will receive the event message (other applications can subscribe to it). The message will also be delivered via AMI provided a channel is attached. Dialplan generated user event messages are still transmitted via the channel, and will only be received by a stasis application they are attached to or if the channel is subscribed to.

Asterisk 12.2.0

  • The live recording object on recording events now contains a target_uri field which contains the URI of what is being recorded.

  • The bridge type used when creating a bridge is now a comma separated list of bridge properties. Valid options are: mixing, holding, dtmf_events, and proxy_media.

  • A channelId can now be provided when creating a channel, either in the uri (POST channels/my-channel-id) or as query parameter. A local channel will suffix the second channel id with ';2' unless provided as query parameter otherChannelId.

  • A bridgeId can now be provided when creating a bridge, either in the uri (POST bridges/my-bridge-id) or as a query parameter.

  • A playbackId can be provided when starting a playback, either in the uri (POST channels/my-channel-id/play/my-playback-id / POST bridges/my-bridge-id/play/my-playback-id) or as a query parameter.

  • A snoop channel can be started with a snoopId, in the uri or query.

Asterisk 12.1.0

  • The Bridge data model now contains the additional fields 'name' and 'creator'. The 'name' field conveys a descriptive name for the bridge; the 'creator' field conveys the name of the entity that created the bridge. This affects all responses to HTTP requests that return a Bridge data model as well as all event derived data models that contain a Bridge data model. The POST /bridges operation may now optionally specify a name to give to the bridge being created.

  • Added a new ARI resource 'mailboxes' which allows the creation and modification of mailboxes managed by external MWI. Modules res_mwi_external and res_stasis_mailbox must be enabled to use this resource. For more information on external MWI control, see res_mwi_external.

  • Added new events for externally initiated transfers. The event BridgeBlindTransfer is now raised when a channel initiates a blind transfer of a bridge in the ARI controlled application to the dialplan; the BridgeAttendedTransfer event is raised when a channel initiates an attended transfer of a bridge in the ARI controlled application to the dialplan.

  • Channel variables may now be specified as a body parameter to the POST /channels operation. The 'variables' key in the JSON is interpreted as a sequence of key/value pairs that will be added to the created channel as channel variables. Other parameters in the JSON body are treated as query parameters of the same name.

Asterisk 12.0.0

  • ARI added to Asterisk