Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 26 Next »

Icon

This Specification is still in draft form.

Introduction

This Asterisk Manager Interface (AMI) specification describes the relationship between Asterisk and an external entity wishing to communicate with Asterisk over the AMI protocol. It describes:

  • An overview of the AMI protocol
  • The operations AMI provides external entities wishing to control Asterisk
  • Basic formatting of AMI message structures
  • Guaranteed operations, configuration control, and other information provided by Asterisk in AMI 1.4

Scope

This specification describes AMI version 1.4, specifically for Asterisk 12. This specification provides details on the functional, operational and design requirements for AMI 1.4. Note that this does not include a comprehensive listing of the AMI configuration file parameters or messages that a system interfacing over AMI in Asterisk 12 will send/receive; however, it does provide a baseline of the supported features and messages provided in AMI 1.4. This specification should be used in conjunction with the documented AMI actions and events in Asterisk 12 to encompass the full range of functionality provided by AMI in Asterisk 12.

In addition, this specification provides interface requirements levied on AMI by Stasis, a message bus internal to Asterisk. It conveys sufficient detail to understand how AMI attaches to the Stasis message bus and interacts with other entities on Stasis.

This specification is intended for all parties requiring such information, including software developers, system designers and testers responsible for implementing the interface.

Terminology

TermDefinition
ActionA command issued to Asterisk from an external entity via AMI
ClientAn external entity communicating with Asterisk via AMI over some transport mechanism
EventA message sent from Asterisk to an external entity via AMI
FieldA key/value pair that exists in either an action or event
StasisThe internal framework that AMI is built on top of

Protocol Overview

Asterisk provides a number of interfaces that serve different purposes. Say, for example, we wanted to manipulate a call between Alice and Bob via some external mechanism. Depending on what we wanted to do with the call, we may use one or more interfaces to manipulate the channels that make up the call between Alice and Bob.

Alice calls Bob and...Interface
... we want to use a local script to execute some logic on Alice's channelAGI
... we want to execute a script on a remote machine on Bob's channelFastAGI
... we want to put Alice into an IVR with fine grained media control, where the IVR is written outside of extensions.confExternalIVR
... we want to control Alice and Bob's underlying channel objects at some asynchronous timeAMI (possibly with AsyncAGI)
... we want to write our own Dialling application to control both Alice and BobARI

In general, AMI is used to manage Asterisk and its channels. It does not determine what actions are executed on a particular channel - the dialplan and/or an AGI interface does that - but it does allow a client to control call generation, aspects of call flow, and other internals of Asterisk.

At its heart, AMI is an asynchronous message bus: it spills events that contain information about the Asterisk system over some transport. In response, clients may request that Asterisk takes some action. These two concepts - actions and events - make up the core of what is AMI. As AMI is asynchronous, as events occur in Asterisk they are immediately sent to the clients. This means that actions issued by entities happen without any synchronization with the events being received, even if those events occur in response to an action. It is the responsibility of entities to associate event responses back to actions.

Clients wishing to use AMI act as clients and connect to Asterisk's AMI server over a supported transport mechanism. Authentication may or may not be enabled, depending on the configuration. Once connected, events can be automatically spilled to the connected clients, or limited in a variety of fashions. A connected client can send an action to the AMI server at any time. Depending on the allowed authorizations, the action may be allowed or disallowed.

More information on the various ways a client can be configured can be seen in [AMI Configuration|#ami_configuration].

Icon

Sometimes, the term command may be used instead of the term action. With respect to AMI actions, command is synonymous with action, and the two can be treated the same. For the sake of consistency, we've attempted to use the term action where possible.

Historically, AMI has existed in Asterisk as its own core component manager. AMI events were raised throughout Asterisk encoded in an AMI specific format, and AMI actions were processed and passed to the functions that implemented the logic. In Asterisk 12, AMI has been refactored to sit on top of Stasis, a generic, protocol independent message bus internal to Asterisk. From the perspective of clients wishing to communicate with Asterisk over AMI very little has changed; internally, the Stasis representation affords a much higher degree of flexibility with how messages move through Asterisk. It also provides a degree of uniformity for information that is propagated to interested parties.

Semantics and Syntax

Message Sending and Receiving

By default, AMI is an asynchronous protocol that sends events immediately to clients when those events are available. Likewise, clients are free to send actions to AMI at any time, which may or may not trigger additional events. The exception to this is when the connection is over [HTTP/HTTPS|#transport_http]; in that scenario, events are only transmitted as part of the response to an HTTP POST.

Various options for configuration of clients can control which events are sent to a client. Events can be whitelisted/blacklisted explicitly via event filters, or implicitly by [class authorizations|#class_authorizations].

Message Layout

AMI is an ASCII protocol that provides bidirectional communication with clients. An AMI message – action or event – is composed of fields delineated by the '\r\n' characters. Within a message, each field is a key value pair delineated by a ':'. A single space MUST follow the ':' and precede the value. Fields with the same key may be repeated within an AMI message. An action or event is terminated by an additional '\r\n' character.

Event: Newchannel
Privilege: call,all
Channel: PJSIP/misspiggy-00000001
Uniqueid: 1368479157.3
ChannelState: 3
ChannelStateDesc: Up
CallerIDNum: 657-5309
CallerIDName: Miss Piggy
ConnectedLineName:
ConnectedLineNum:
AccountCode: Pork
Priority: 1
Exten: 31337
Context: inbound

 This is syntantically equivalent to the following ASCII string:

Event: Newchannel\r\nPrivilege: call,all\r\nChannel: PJSIP/misspiggy-00000001\r\nUniqueid: 1368479157.3\r\nChannelState: 3\r\nChannelStateDesc: Up\r\nCallerIDNum: 657-5309\r\nCallerIDName: Miss Piggy\r\nConnectedLineName:\r\nConnectedLineNum:\r\nAccountCode: Pork\r\nPriority:\r\nExten: 31337\r\nContext: inbound\r\n\r\n

 

Actions are specified in a similar manner. Note that depending on the message, some keys can be repeated.

Action: Originate
ActionId: SDY4-12837-123878782
Channel: PJSIP/kermit-00000002
Context: outbound
Exten: s
Priority: 1
CallerID: "Kermit the Frog" <123-4567>
Account: FrogLegs
Variable: MY_VAR=frogs
Variable: HIDE_FROM_CHEF=true

In addition, no ordering is implied on message specific keys. Hence, the following two messages are semantically the same.

Action: Originate
ActionId: SDY4-12837-123878782
Channel: PJSIP/kermit-00000002
Context: outbound
Exten: s
Priority: 1
CallerID: "Kermit the Frog" <123-4567>
Account: FrogLegs
Variable: MY_VAR=frogs
Variable: HIDE_FROM_CHEF=true
ActionId: SDY4-12837-123878782
Action: Originate
Variable: HIDE_FROM_CHEF=true
Variable: MY_VAR=frogs
Channel: PJSIP/kermit-00000002
Account: FrogLegs
Context: outbound
Exten: s
CallerID: "Kermit the Frog" <123-4567>
Priority: 1

This is also true for events, although by convention, the Event key is the first key in the event. If an action or event contains duplicate keys, such as Variable, the order in which Asterisk processes said keys is the order in which they occur within the action or event.

Keys are case insensitive. Hence, the following keys are equivalent:

Action: Originate
ACTION: Originate
action: Originate

The case sensitivity for values is left up to the context in which they are interpreted.

Common Fields

Actions

General Fields

This section lists fields that apply generally to all actions.

Action

Action specifies the action to execute within Asterisk. Each value corresponds to a unique action to execute within Asterisk. The value of the Action field determines the allowed fields within the rest of the message. By convention, the first field in any action is the Action field.

ActionId

ActionId is a universal unique identifier that can optionally be provided with an action. If provided in an action, events that are related to that action will contain the same ActionId value, allowing a client to associate actions with events that were caused by that action.

It is recommended that clients always provide an ActionId for each action they submit.

Icon

It is up to the client to ensure that the ActionId provided with an Action is unique.

Channels

This section lists fields that apply generally to all actions that interact upon an Asterisk channel. Note that an Action that interacts with a channel *must* supply the *Channel* field.

Upgrading

Icon

 In the past, AMI clients would have to contend with channel rename events. As Asterisk will now no longer change the name of a channel during its lifetime, this is no longer necessary.

Channel

The Asterisk channel name. A channel name is provided by AMI to clients during a Newchannel event. A channel name can be viewed as the handle to a channel.

Uniqueid

A universal unique identifier for the channel. In systems with multiple Asterisk instances, this field can be used to construct a globally unique identifier for a channel, as a channel name may occur multiple times across Asterisk instances.

Events

General Fields

This section lists fields that apply generally to all events.

Event

The unique name of the event being raised. The value of the Event field determines the rest of the contents of the message. By convention, the Event field is the first field in an AMI message.

ActionId

If present, the Action's corresponding ActionId that caused this event to be created. If an Action contained an ActionId, any event relating the success or failure of that action MUST contain an ActionId field with the same value.

Privilege

The class authorizations associated with this particular event. The class authorizations for a particular event are in a comma-delineated list. For more information, see [class authorizations|#class_authorizations].

Event responses to an Action only occur if the Action was executed, which means the user had the appropriate class authorization. Therefore they will not have a Privilege field.

Channels

This section lists fields that apply generally to all events that occur due to interactions upon an Asterisk channel.

Events that relate multiple channels will prefix these fields with an event specific role specifier. For example, a DialBegin or a DialEnd event will prefix the outbound channel's fields with Dest. So, the Channel field is the DestChannel field; the Uniqueid field is the DestUniqueid field, etc.

Channel

The current Asterisk channel name. This corresponds to the Channel field in actions.

Uniqueid

A universal unique identifier for the channel. This corresponds to the Uniqueid field in actions.

ChannelState

The current state of the channel, represented as an integer value. The valid values are:

ValueStateDescription
0DownChannel is down and available.
1RsrvdChannel is down, but reserved.
2OffHookChannel is off hook.
3DialingThe channel is in the midst of a dialing operation.
4RingThe channel is ringing.
5RingingThe remote endpoint is ringing. Note that for many channel technologies, this is the same as Ring.
6UpA communication path is established between the endpoint and Asterisk.
7BusyA busy indication has occurred on the channel.
8Dialing OffhookDigits (or equivalent) have been dialed while offhook.
9Pre-ringThe channel technology has detected an incoming call and is waiting for a ringing indication.
10UnknownThe channel is an unknown state.
Icon

Depending on the underlying channel technology, not all states will be used. Channels typically begin in either the Down or Up states.

ChannelStateDesc

The text description of the channel state. This will be one of the State descriptions in the table in ChannelState.

CallerIDNum

The current caller ID number. If the caller ID number is not known, the string "<unknown>" is returned instead.

CallerIDName

The current caller ID name. If the caller ID name is not known, the string "<unknown>" is returned instead.

ConnectedLineNum

The current connected line number. If the connected line number is not known, the string "<unknown>" is returned instead.

ConnectedLineName

The current connected line name. If the connected line name is not known, the string "<unknown>" is returned instead.

AccountCode

The channel's accountcode.

Context

The current context in the dialplan that the channel is executing in.

Exten

The current extension in the dialplan that the channel is executing in.

Priority

The current priority of the current context, extension in the dialplan that the channel is executing in.

ChanVariable

Channel variables specific to a channel can be conveyed in each AMI event related to that channel. When this occurs, each variable is referenced in a ChanVariable field. The value of a ChanVariable field will always be of the form key=value, where key is the name of the channel variable and value is its value.

Bridges
BridgeUniqueid

A unique identifier for the bridge, which provides a handle to actions that manipulate bridges.

BridgeType

The type of the bridge. Bridge types determine how a participant in a bridge can behave. For example, a 'base' bridge is a bridge that has few inherent properties or features associated with it, while a 'parking' bridge is one used for a parking application. Specific modules within Asterisk will determine the type of bridge that is created.

Note that this is not the same as how media within a bridge is mixed. How media is mixed between participants in a bridge is determined by the BridgeTechnology.

BridgeTechnology

How the media can be mixed within a bridge. Specific modules in Asterisk provide different bridge technologies that can be used by Asterisk to alter how media passes between the participants. For a given bridge, the BridgeTechnology* can also change as the number and type of participants change. The most common bridge technologies are:

  • holding_bridge – normal participants joining the bridge may receive audio, but audio sent from a normal participant is dropped. Special participants, known as announcers, may broadcast their audio to all normal participants.

  • native_dahdi – a native bridge between DAHDI channels. Media is passed directly between all participants.

  • native_rtp – a native bridge between channels that use RTP for media. Media is passed directly between all participants.

  • simple_bridge – a two-party bridge between any two channels. Media is passed through the Asterisk core between the two participants.

  • softmix – a multi-party bridge between one or more participants. All media from all participants is mixed together and sent to all participants.

BridgeCreator

Some bridges are created as the result of a particular application or action. If so, the bridge will specify who created it. If the bridge was not created as a result of any particular application or action, the field will have the value <unknown>.

BridgeName

Some bridges are created with a names as a result of their application. If so, the bridge will specify the name given to it. If the bridge was created without a name, the field will have the value <unknown>.

BridgeNumChannels

The number of channels currently in the bridge.

Action Responses

When an Action is submitted to AMI, the success or failure of the action is communicated in subsequent events.

Response

Contains whether or not the action succeeded or failed. Valid values are "Success" or "Error". Events that are in response to an action MUST include this field.

EventList

Some actions will cause a chain of events to be created. Events that are a response to an action that causes such a sequence will contain the EventList field with a value of "start". When all generated events have been sent, a final event will be sent containing the EventList field with the value "complete".

If, for some reason, an error occurs and the events cannot be sent, an event will be sent with an EventList field that contains the value "cancelled".

Note that the events that mark the completion or cancellation of an event list are not technically action responses, and have their own specific event types.

Message

An optional text message that provides additional contextual information regarding the success or failure of the action.

Actions

The supported actions for Asterisk 12 are listed here:

Asterisk 12 AMI Actions

While new AMI Actions may be added over the lifetime of Asterisk 12, existing AMI Actions will not be removed.

Optional fields may be added to an existing AMI action with altering the AMI version number, but required fields will not be added or removed.

Events

The supported events for Asterisk 12 are listed here:

Asterisk 12 AMI Events

While new AMI Events may be added over the lifetime of Asterisk 12, existing AMI Events will not be removed.

Fields may be added to an existing AMI event without altering the AMI version number, but existing fields will not be removed.

Channel Interaction/Lifetime

While channels are independent of AMI, they have a large implication on the events sent out over AMI. Many of the events in AMI correspond to changes in channel state. While AMI is an asynchronous protocol, there is some ordering with respect to the events that are relayed for a particular channel. This section provides the basic event relationships that are guaranteed through AMI.

Basic Channel Lifetime

All channels begin with a Newchannel event. A Newchannel will always contain the following fields:

  • The current Channel name that acts as a handle to the channel for that channel's lifetime for a single Asterisk system.
  • The Uniqueid for the channel, that allows systems to have a globally unique identifier for the channel.

Changes in the state of the channel, i.e., the ChannelState field, are conveyed via Newstate events.

Notification of a Channel being disposed of occurs via a Hangup event. A Hangup signals the termination of the channel associated with the Uniqueid. After the Hangup event, no further events will be raised in relation to the channel with that Uniqueid, and the communication between the endpoint and Asterisk via that channel is terminated.

Icon

The examples in this specification do not show all of the fields in every event. For a full listing of all of the fields, see the documentation for the specific event in Asterisk 12 AMI Events.

Example

Channel Variables

For each channel variable that is changed, a VarSet event is sent to the client. The VarSet event contains the new value of the appropriate channel variable. Note that channel variables can also be conveyed in ChanVariable fields.

DTMF

DTMF is indicated via a DTMFBegin/DTMFEnd events. A DTMFEnd event MUST convey the duration of the DTMF tone in milliseconds.

Behavior Change

Icon

 The combination of DTMFBegin/DTMFEnd events replaces the removed DTMF event.

Dialplan Execution

As a channel executes operations in the dialplan, those operations are conveyed via a NewExten event. Each transition to a new combination of context, extension, and priority will trigger a NewExten event.

Example

 

 

  • No labels