<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2176/25/9/_/styles/combined.css?spaceKey=AST&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/AST/AMI+1.4+Specification">AMI 1.4 Specification</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~mjordan">Matt Jordan</a>
</h4>
<br/>
<h4>Changes (3)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">{gliffy:name=AMI Local Channels Diagram|align=left|size=L|version=1} <br>{gliffy:name=AMI High Level Diagram|align=left|size=L|version=1} <br></td></tr>
<tr><td class="diff-unchanged" >{numberedheadings} <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{tr} <br>{td} <br></td></tr>
<tr><td class="diff-changed-lines" >{gliffy:name=AMI High <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Level|align=left|size=L|version=3}</span> <span class="diff-added-words"style="background-color: #dfd;">Level Diagram|align=left|size=L|version=1}</span> <br></td></tr>
<tr><td class="diff-unchanged" >{td} <br>{tr} <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >* A Local channel is actually always two separate channels with a special bridge between them. <br> <br></td></tr>
<tr><td class="diff-changed-lines" >{gliffy:name=AMI Local <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Channels|align=left|size=L|version=2}</span> <span class="diff-added-words"style="background-color: #dfd;">Channels Diagram|align=left|size=L|version=1}</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br>While the Local channel exists as a single concept from the perspective of the dialplan, from the perspective of an AMI client, it is always two channels that are tied together by a special bridge. When the bridge between the Local channel halves is formed, a *LocalBridge* event is raised denoting that the two are connected. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<div>
<ul>
<li><a href='#AMI1.4Specification-Introduction'>1. Introduction</a></li>
<ul>
<li><a href='#AMI1.4Specification-Scope'>1.1. Scope</a></li>
</ul>
<li><a href='#AMI1.4Specification-Terminology'>2. Terminology</a></li>
<li><a href='#AMI1.4Specification-ProtocolOverview'>3. Protocol Overview</a></li>
<li><a href='#AMI1.4Specification-SemanticsandSyntax'>4. Semantics and Syntax</a></li>
<ul>
<li><a href='#AMI1.4Specification-MessageSendingandReceiving'>4.1. Message Sending and Receiving</a></li>
<ul>
<li><a href='#AMI1.4Specification-Publish%2FSubscribe'>4.1.1. Publish/Subscribe</a></li>
<ul>
<li><a href='#AMI1.4Specification-PropertiesofTags'>4.1.1.1. Properties of Tags</a></li>
<li><a href='#AMI1.4Specification-LocalChannelsandTags'>4.1.1.2. Local Channels and Tags</a></li>
<li><a href='#AMI1.4Specification-ObjectsandTags'>4.1.1.3. Objects and Tags</a></li>
</ul>
</ul>
<li><a href='#AMI1.4Specification-MessageLayout'>4.2. Message Layout</a></li>
<ul>
<li><a href='#AMI1.4Specification-CommonFields'>4.2.1. Common Fields</a></li>
<ul>
<li><a href='#AMI1.4Specification-Actions'>4.2.1.1. Actions</a></li>
<ul>
<li><a href='#AMI1.4Specification-GeneralFields'>4.2.1.1.1. General Fields</a></li>
<ul>
<li><a href='#AMI1.4Specification-Action'>4.2.1.1.1.1. Action</a></li>
<li><a href='#AMI1.4Specification-ActionId'>4.2.1.1.1.2. ActionId</a></li>
</ul>
<li><a href='#AMI1.4Specification-Channels'>4.2.1.1.2. Channels</a></li>
<ul>
<li><a href='#AMI1.4Specification-Channel'>4.2.1.1.2.1. Channel</a></li>
<li><a href='#AMI1.4Specification-Uniqueid'>4.2.1.1.2.2. Uniqueid</a></li>
</ul>
</ul>
<li><a href='#AMI1.4Specification-Events'>4.2.1.2. Events</a></li>
<ul>
<li><a href='#AMI1.4Specification-GeneralFields'>4.2.1.2.1. General Fields</a></li>
<ul>
<li><a href='#AMI1.4Specification-Event'>4.2.1.2.1.1. Event</a></li>
<li><a href='#AMI1.4Specification-ActionId'>4.2.1.2.1.2. ActionId</a></li>
<li><a href='#AMI1.4Specification-Privilege'>4.2.1.2.1.3. Privilege</a></li>
</ul>
<li><a href='#AMI1.4Specification-Channels'>4.2.1.2.2. Channels</a></li>
<ul>
<li><a href='#AMI1.4Specification-Channel'>4.2.1.2.2.1. Channel</a></li>
<li><a href='#AMI1.4Specification-Uniqueid'>4.2.1.2.2.2. Uniqueid</a></li>
<li><a href='#AMI1.4Specification-ChannelState'>4.2.1.2.2.3. ChannelState</a></li>
<li><a href='#AMI1.4Specification-ChannelStateDesc'>4.2.1.2.2.4. ChannelStateDesc</a></li>
<li><a href='#AMI1.4Specification-CallerIDNum'>4.2.1.2.2.5. CallerIDNum</a></li>
<li><a href='#AMI1.4Specification-CallerIDName'>4.2.1.2.2.6. CallerIDName</a></li>
<li><a href='#AMI1.4Specification-ConnectedLineNum'>4.2.1.2.2.7. ConnectedLineNum</a></li>
<li><a href='#AMI1.4Specification-ConnectedLineName'>4.2.1.2.2.8. ConnectedLineName</a></li>
<li><a href='#AMI1.4Specification-Tag'>4.2.1.2.2.9. Tag</a></li>
</ul>
<li><a href='#AMI1.4Specification-Bridges'>4.2.1.2.3. Bridges</a></li>
<ul>
<li><a href='#AMI1.4Specification-Bridgetype'>4.2.1.2.3.1. Bridgetype</a></li>
<li><a href='#AMI1.4Specification-BridgeUniqueid'>4.2.1.2.3.2. BridgeUniqueid</a></li>
</ul>
<li><a href='#AMI1.4Specification-ActionResponses'>4.2.1.2.4. Action Responses</a></li>
<ul>
<li><a href='#AMI1.4Specification-Response'>4.2.1.2.4.1. Response</a></li>
<li><a href='#AMI1.4Specification-EventList'>4.2.1.2.4.2. EventList</a></li>
<li><a href='#AMI1.4Specification-Message'>4.2.1.2.4.3. Message</a></li>
</ul>
</ul>
</ul>
</ul>
<li><a href='#AMI1.4Specification-Actions'>4.3. Actions</a></li>
<li><a href='#AMI1.4Specification-Events'>4.4. Events</a></li>
<li><a href='#AMI1.4Specification-ChannelInteraction%2FLifetime'>4.5. Channel Interaction/Lifetime</a></li>
<ul>
<li><a href='#AMI1.4Specification-BasicChannelLifetime'>4.5.1. Basic Channel Lifetime</a></li>
<li><a href='#AMI1.4Specification-ChannelVariables'>4.5.2. Channel Variables</a></li>
<li><a href='#AMI1.4Specification-DTMF'>4.5.3. DTMF</a></li>
<li><a href='#AMI1.4Specification-DialplanExecution'>4.5.4. Dialplan Execution</a></li>
<li><a href='#AMI1.4Specification-Dialing'>4.5.5. Dialing</a></li>
<li><a href='#AMI1.4Specification-Bridging'>4.5.6. Bridging</a></li>
<ul>
<li><a href='#AMI1.4Specification-TwoPartyBridging'>4.5.6.1. Two Party Bridging</a></li>
<li><a href='#AMI1.4Specification-Transfers'>4.5.6.2. Transfers</a></li>
</ul>
<li><a href='#AMI1.4Specification-LocalChannels'>4.5.7. Local Channels</a></li>
<ul>
<li><a href='#AMI1.4Specification-LocalChannelCreation'>4.5.7.1. Local Channel Creation</a></li>
<li><a href='#AMI1.4Specification-LocalChannelBridging'>4.5.7.2. Local Channel Bridging</a></li>
<li><a href='#AMI1.4Specification-LocalChannelOptimization'>4.5.7.3. Local Channel Optimization</a></li>
</ul>
<li><a href='#AMI1.4Specification-Masquerades'>4.5.8. Masquerades</a></li>
</ul>
<li><a href='#AMI1.4Specification-Transports'>4.6. Transports</a></li>
</ul>
<li><a href='#AMI1.4Specification-SecurityConsiderations'>5. Security Considerations</a></li>
<ul>
<li><a href='#AMI1.4Specification-ClassAuthorizations'>5.1. Class Authorizations</a></li>
<li><a href='#AMI1.4Specification-AccessControlLists'>5.2. Access Control Lists</a></li>
<li><a href='#AMI1.4Specification-Authorization'>5.3. Authorization</a></li>
</ul>
<li><a href='#AMI1.4Specification-AMIConfiguration'>6. AMI Configuration</a></li>
<ul>
<li><a href='#AMI1.4Specification-GeneralSettings'>6.1. General Settings</a></li>
<li><a href='#AMI1.4Specification-ClientSettings'>6.2. Client Settings</a></li>
</ul>
</ul></div>
<h1><a name="AMI1.4Specification-Introduction"></a>1. Introduction</h1>
<p>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:</p>
<ul>
<li>An overview of the AMI protocol</li>
<li>The operations AMI provides external entities wishing to control Asterisk</li>
<li>Basic formatting of AMI message structures</li>
<li>Guaranteed operations, configuration control, and other information provided by Asterisk in AMI 1.4</li>
</ul>
<h2><a name="AMI1.4Specification-Scope"></a>1.1. Scope</h2>
<p>This specification describes AMI version 1.4 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.</p>
<p>In addition, this specification provides interface requirements levied on AMI by Stasis Core. It conveys sufficient detail to understand how AMI attaches to Stasis Core and interacts with other entities on the Stasis Core message bus.</p>
<p>This specification is intended for all parties requiring such information, including software developers, system designers and testers responsible for implementing the interface.</p>
<h1><a name="AMI1.4Specification-Terminology"></a>2. Terminology</h1>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Term </th>
<th class='confluenceTh'> Definition </th>
</tr>
<tr>
<td class='confluenceTd'> Action </td>
<td class='confluenceTd'> A command issued to Asterisk from an external entity via AMI </td>
</tr>
<tr>
<td class='confluenceTd'> Client </td>
<td class='confluenceTd'> An external entity communicating with Asterisk via AMI over some transport mechanism </td>
</tr>
<tr>
<td class='confluenceTd'> Event </td>
<td class='confluenceTd'> A message sent from Asterisk to an external entity via AMI </td>
</tr>
<tr>
<td class='confluenceTd'> Field </td>
<td class='confluenceTd'> A key/value pair that exists in either an action or event </td>
</tr>
<tr>
<td class='confluenceTd'> Stasis Core </td>
<td class='confluenceTd'> The internal framework that AMI is built on top of </td>
</tr>
</tbody></table>
</div>
<h1><a name="AMI1.4Specification-ProtocolOverview"></a>3. Protocol Overview</h1>
<p>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.</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Alice calls Bob and... </th>
<th class='confluenceTh'> Interface </th>
</tr>
<tr>
<td class='confluenceTd'> ... we want to use a local script to execute some logic on Alice's channel </td>
<td class='confluenceTd'> AGI </td>
</tr>
<tr>
<td class='confluenceTd'> ... we want to execute a script on a remote machine on Bob's channel </td>
<td class='confluenceTd'> FastAGI </td>
</tr>
<tr>
<td class='confluenceTd'> ... we want to put Alice into an IVR with fine grained media control, where the IVR is written outside of <tt>extensions.conf</tt> </td>
<td class='confluenceTd'> ExternalIVR </td>
</tr>
<tr>
<td class='confluenceTd'> ... we want to control Alice and Bob's underlying channel objects </td>
<td class='confluenceTd'> AMI (with, possibly, AsyncAGI as well) </td>
</tr>
</tbody></table>
</div>
<p>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 some AGI interface does that - but it does allow a client to control call generation, aspects of call flow, and other internals of Asterisk.</p>
<p>At its heart, AMI is an asynchronous message bus: it spills <b>events</b> that contain information about the Asterisk system over some transport. In response, clients may request that Asterisk takes some <b>action</b>. 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.</p>
<p>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.</p>
<p>More information on the various ways a client can be configured can be seen in <a href="#AMI1.4Specification-amiconfiguration">AMI Configuration</a>.</p>
<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Sometimes, the term <b>command</b> may be used instead of the term <b>action</b>. 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 <b>action</b> where possible.</td></tr></table></div>
<p>Historically, AMI has existed in Asterisk as its own core component <tt>manager</tt>. 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 Core, which is 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.</p>
<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><tbody><tr>
<table><tr><td>
<table width="100%">
<tr>
<td align="left" >
<table>
<caption align="bottom">
</caption>
<tr>
<td>
<img style="border: none; width: 790px;"
usemap="#gliffy-map-22478872-6581"
src="/wiki/download/attachments/22086004/AMI+High+Level+Diagram.png?version=1&modificationDate=1357310789124"
alt=""/>
</td>
</tr>
</table>
</td>
</tr>
</table>
</td></tr>
<tr><td><p>Asterisk's Stasis Core provides a generic publish/subscribe message bus inside of Asterisk. AMI sits on top of Stasis Core, publishing messagse on the Stasis bus (actions) and receiving messages from the bus (events). It translates the generic Stasis messages into an AMI message, and sends those to the appropriate AMI clients.</p></td></tr></table></tr></tbody></table>
<h1><a name="AMI1.4Specification-SemanticsandSyntax"></a>4. Semantics and Syntax</h1>
<h2><a name="AMI1.4Specification-MessageSendingandReceiving"></a>4.1. Message Sending and Receiving</h2>
<p>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 <a href="#AMI1.4Specification-transporthttp">HTTP/HTTPS</a>; in that scenario, events are only transmitted as part of the response to an HTTP POST.</p>
<p>Various options for configuration of clients can control which events are sent to a client. Events can be whitelisted/blacklisted either explicitly, or implicitly by <a href="#AMI1.4Specification-classauthorizations">class authorizations</a>. A separate mechanism for sending/receiving messages is also supported, which allows clients to subscribe only to events associated with tagged endpoints. This changes AMI from a "send everything" message bus to a publish/subscribe message bus that clients can configure themselves for.</p>
<p><a name="AMI1.4Specification-publishsubscribe"></a></p>
<h3><a name="AMI1.4Specification-Publish%2FSubscribe"></a>4.1.1. Publish/Subscribe</h3>
<p>AMI supports an optional publish/subscribe model of event distribution through the use of endpoint tags. While AMI by default sends all events to a client, if the client has been configured with a set of tags, then only events associated with channels that were created in relation to an endpoint with that tag will be sent to the client. Events that are in relation to an action initiated by the client are not checked for tags.</p>
<div class="panel" style="border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;"><b>Configuration Example</b></div><div class="panelContent">
<p></p>
<table><tr><td width="50%"><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>sip.conf</b></div><div class="preformattedContent panelContent">
<pre>[sip_peer_a](my_peer_template)
type=peer
secret=secret
tag=endpoint_group_one
tag=special_endpoints
[sip_peer_b](my_peer_template)
type=peer
secret=secret
tag=endpoint_group_two
</pre>
</div></div></td>
<td><p>Two peers have been defined: <em>sip_peer_a</em> and <em>sip_peer_b</em>. <em>sip_peer_a</em> has tags of <em>endpoint_group_one</em> and <em>special_endpoints</em>, while <em>sip_peer_b</em> has a tag of <em>endpoint_group_two</em>.</p></td></tr>
<tr><td width="50%"><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>manager.conf</b></div><div class="preformattedContent panelContent">
<pre>[manager_account]
secret=mysecret
read=all
write=all
tag=endpoint_group_one
...
</pre>
</div></div></td>
<td><p>A manager account has been set up to only receive events related to channels that correspond with endpoints with the tag <em>endpoint_group_one</em>. Because SIP peer <em>sip_peer_a</em> has that tag, the AMI client authenticated under <em>manager_account</em> will receive events from channels associated with that endpoint. It will not receive channel events associated with SIP peer <em>sip_peer_b</em>, as it does not share that tag.</p></td></tr></table>
</div></div>
<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>An AMI client receives events from channels with an endpoint's tag if the intersection of the tag sets for the client and the channel is not the empty set; that is, only a single tag has to match.</td></tr></table></div>
<p>In addition to channels created for endpoints via the dialplan or by channel drivers for inbound calls, tags may also be added to outbound channels via the <b>Originate</b> action. Tags may be added to channels via the <b>CHANNEL</b> dialplan function.</p>
<h4><a name="AMI1.4Specification-PropertiesofTags"></a>4.1.1.1. Properties of Tags</h4>
<p>Tags are constant properties of channels; that is, once a tag is added it cannot be modified. Tags can be added to channels on creation and during a channel's lifetime; however, once a tag is added to a channel the tag cannot be removed and will persist until the channel's destruction. When a tag is added to a channel after the channel's creation, a <b>TagAdded</b> event MUST be sent to all clients. Tags that are created with a channel are included in the channel's <b>NewChannel</b> event.</p>
<h4><a name="AMI1.4Specification-LocalChannelsandTags"></a>4.1.1.2. Local Channels and Tags</h4>
<p>Local channels have no configuration, and are not associated with endpoints. As such, based on the previous definition of tag subscriptions, an AMI client would never receive events associated with Local channels. This is problematic when you have a Local channel tied to an Asterisk application, as opposed to another channel. Say we have a tagged SIP channel in a bridge with a non-optimizing Local channel that is locally bridged with a source of music (or is playing back some sound file). By default, the only <b>BridgeEnter</b>/<b>BridgeLeave</b> events we would receive would be the events associated with the SIP channel. This means that we would not be able to determine what sound files were being played back to the SIP channel, as that information is associated with the Local channel.</p>
<p>This scenario leads to the following exception: Local channels MUST inherit the tags of whatever channels they are bridged to, either in a local bridge or core bridge.</p>
<h4><a name="AMI1.4Specification-ObjectsandTags"></a>4.1.1.3. Objects and Tags</h4>
<p>While tags are typically used by some channel technology's definition of an "endpoint", other objects in Asterisk can also be associated with tags. This includes the following:</p>
<ul>
<li>Bridges (created either via the dialplan or through an AMI action)
<ul>
<li>Parking Lots</li>
<li>ConfBridge conferences</li>
</ul>
</li>
<li>Queues</li>
<li>VoiceMail Mailboxes</li>
</ul>
<h2><a name="AMI1.4Specification-MessageLayout"></a>4.2. Message Layout</h2>
<p>AMI is an ASCII protocol that provides bidirectional communication with clients. Each field in an AMI message - action or event - is delineated by the '\r\n' characters. An action or event is terminated by an additional '\r\n' character. Within a message, each field is a key value pair delineated by a ':'. A single space MUST follow the ':' and preceed the value.</p>
<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><tbody><tr>
<td class="confluenceTd" valign="top" width="50%">
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: NewChannel
Channel: SIP/misspiggy-00000001
Uniqueid: G0001-asdf87-1n23j-18237
ChannelState: 3
ChannelStateDesc: Up
CallerIDNum: 657-5309
CallerIDName: Miss Piggy
AccountCode: Pork
Exten: 31337
Context: inbound
</pre>
</div></div></td>
<td class="confluenceTd" valign="top" width="50%">
<p>This is syntantically equivalent to the following ASCII string:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: NewChannel\r\nChannel: SIP/misspiggy-00000001\r\n
Uniqueid: G0001-asdf87-1n23j-18237\r\nChannelState: 3\r\n
ChannelStateDesc: Up\r\nCallerIDNum: 657-5309\r\n
CallerIDName: Miss Piggy\r\nAccountCode: Pork\r\n
Exten: 31337\r\nContext: inbound\r\n\r\n
</pre>
</div></div></td></tr></tbody></table>
<p>Actions are specified in a similar manner. Note that depending on the message, some keys can be repeated.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Action: Originate
ActionId: SDY4-12837-123878782
Channel: SIP/kermit
Context: outbound
Exten: s
Priority: 1
CallerID: "Kermit the Frog" <123-4567>
Account: FrogLegs
Variable: MY_VAR=frogs
Variable: HIDE_FROM_CHEF=true
</pre>
</div></div>
<p>In addition, no ordering is implied on message specific keys. Hence, the following two messages are semantically the same.</p>
<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><tbody><tr>
<td class="confluenceTd" valign="top" width="50%">
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Action: Originate
ActionId: SDY4-12837-123878782
Channel: SIP/kermit
Context: outbound
Exten: s
Priority: 1
CallerID: "Kermit the Frog" <123-4567>
Account: FrogLegs
Variable: MY_VAR=frogs
Variable: HIDE_FROM_CHEF=true
</pre>
</div></div></td>
<td class="confluenceTd" valign="top" width="50%">
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>ActionId: SDY4-12837-123878782
Action: Originate
Variable: HIDE_FROM_CHEF=true
Variable: MY_VAR=frogs
Channel: SIP/kermit
Account: FrogLegs
Context: outbound
Exten: s
CallerID: "Kermit the Frog" <123-4567>
Priority: 1
</pre>
</div></div></td></tr></tbody></table>
<p>The exception to this is AMI events. In an event, the <tt>Event</tt> key MUST be the first key. All other keys in an event are unordered. If an action or event contains duplicate keys, such as <tt>Variable</tt>, the order in which they are processed is the order in which they occur within the action or event.</p>
<p>Keys are case insensitive. Hence, the following keys are equivalent:</p>
<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><tbody><tr>
<td class="confluenceTd" valign="top" width="30%">
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Action: Originate
</pre>
</div></div></td>
<td class="confluenceTd" valign="top" width="30%">
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>ACTION: Originate
</pre>
</div></div></td>
<td class="confluenceTd" valign="top" width="30%">
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>action: Originate
</pre>
</div></div></td></tr></tbody></table>
<p>The case sensitivity for values is left up to the context in which they are interpreted.</p>
<h3><a name="AMI1.4Specification-CommonFields"></a>4.2.1. Common Fields</h3>
<h4><a name="AMI1.4Specification-Actions"></a>4.2.1.1. Actions</h4>
<h5><a name="AMI1.4Specification-GeneralFields"></a>4.2.1.1.1. General Fields</h5>
<p>This section lists fields that apply generally to all actions.</p>
<h6><a name="AMI1.4Specification-Action"></a>4.2.1.1.1.1. Action</h6>
<p><b>Action</b> specifies the action to execute within Asterisk. Each value corresponds to a unique action to execute within Asterisk. The value of the <b>Action</b> field determines the allowed fields within the rest of the message. By convention, the first field in any action is the <b>Action</b> field.</p>
<p><a name="AMI1.4Specification-actionactionid"></a></p>
<h6><a name="AMI1.4Specification-ActionId"></a>4.2.1.1.1.2. ActionId</h6>
<p><b>ActionId</b> 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 <b>ActionId</b> value, allowing a client to associate actions with events that were caused by that action.</p>
<p>It is recommended that clients always provide an <b>ActionId</b> for each action they submit.</p>
<h5><a name="AMI1.4Specification-Channels"></a>4.2.1.1.2. Channels</h5>
<p>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 either the <b>Channel</b> field or the <b>Uniqueid</b> field.</p>
<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>In the past, only the <b>Channel</b> field could be used. As Asterisk can change the name of a channel, the <b>Uniqueid</b> is now the preferred way of initiating an action on a channel.</td></tr></table></div>
<p><a name="AMI1.4Specification-actionchannel"></a></p>
<h6><a name="AMI1.4Specification-Channel"></a>4.2.1.1.2.1. Channel</h6>
<p>The current Asterisk channel name. A channel name is provided by AMI to clients during a <b>NewChannel</b> event. Note that Asterisk channel names can change during the lifetime of the communication path between the endpoint and Asterisk. These channel name changes are indicated by a <b>Rename</b> event.</p>
<p><a name="AMI1.4Specification-actionuniqueid"></a></p>
<h6><a name="AMI1.4Specification-Uniqueid"></a>4.2.1.1.2.2. Uniqueid</h6>
<p>A universal unique identifier that acts as a handle to the channel. Once a communication path between an endpoint and Asterisk is established, a <b>Uniqueid</b> is created as a handle to that communication path. This survives operations within Asterisk that may change the channel object or the channel name.</p>
<h4><a name="AMI1.4Specification-Events"></a>4.2.1.2. Events</h4>
<h5><a name="AMI1.4Specification-GeneralFields"></a>4.2.1.2.1. General Fields</h5>
<p>This section lists fields that apply generally to all events.</p>
<h6><a name="AMI1.4Specification-Event"></a>4.2.1.2.1.1. Event</h6>
<p>The unique name of the event being raised. The value of the <b>Event</b> field determines the rest of the contents of the message. The <b>Event</b> field MUST be the first field in an AMI message.</p>
<h6><a name="AMI1.4Specification-ActionId"></a>4.2.1.2.1.2. ActionId</h6>
<p>If present, the Action's corresponding <a href="#AMI1.4Specification-actionactionid">ActionId</a> that caused this event to be created. If an Action contained an <b>ActionId</b>, any event relating the success or failure of that action MUST contain an <b>ActionId</b> field with the same value.</p>
<h6><a name="AMI1.4Specification-Privilege"></a>4.2.1.2.1.3. Privilege</h6>
<p>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 <a href="#AMI1.4Specification-classauthorizations">class authorizations</a>.</p>
<p><a name="AMI1.4Specification-eventchannels"></a></p>
<h5><a name="AMI1.4Specification-Channels"></a>4.2.1.2.2. Channels</h5>
<p>This section lists fields that apply generally to all events that occur due to interactions upon an Asterisk channel.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>In cases where an event represents interactions on multiple channels, the following fields will be appended with a sequentially increasing integer, beginning with <tt>1</tt>.</td></tr></table></div>
<h6><a name="AMI1.4Specification-Channel"></a>4.2.1.2.2.1. Channel</h6>
<p>The current Asterisk channel name. This corresponds to the <a href="#AMI1.4Specification-actionchannel">Channel</a> field in actions.</p>
<h6><a name="AMI1.4Specification-Uniqueid"></a>4.2.1.2.2.2. Uniqueid</h6>
<p>A universal unique identifier that acts as a handle to the channel. This corresponds to the <a href="#AMI1.4Specification-actionuniqueid">Uniqueid</a> field in actions.</p>
<p><a name="AMI1.4Specification-eventchannelstate"></a></p>
<h6><a name="AMI1.4Specification-ChannelState"></a>4.2.1.2.2.3. ChannelState</h6>
<p>The current state of the channel, represented as an integer value. The valid values are:</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Value </th>
<th class='confluenceTh'> State </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> 0 </td>
<td class='confluenceTd'> Down </td>
<td class='confluenceTd'> Channel is down and available </td>
</tr>
<tr>
<td class='confluenceTd'> 1 </td>
<td class='confluenceTd'> Rsrvd </td>
<td class='confluenceTd'> Channel is down, but reserved </td>
</tr>
<tr>
<td class='confluenceTd'> 2 </td>
<td class='confluenceTd'> OffHook </td>
<td class='confluenceTd'> Channel is off hook </td>
</tr>
<tr>
<td class='confluenceTd'> 3 </td>
<td class='confluenceTd'> Dialing </td>
<td class='confluenceTd'> The channel is in the midst of a dialing operation </td>
</tr>
<tr>
<td class='confluenceTd'> 4 </td>
<td class='confluenceTd'> Ring </td>
<td class='confluenceTd'> The channel is ringing </td>
</tr>
<tr>
<td class='confluenceTd'> 5 </td>
<td class='confluenceTd'> Ringing </td>
<td class='confluenceTd'> The remote endpoint is ringing. Note that for many channel technologies, this is the same as Ring. </td>
</tr>
<tr>
<td class='confluenceTd'> 6 </td>
<td class='confluenceTd'> Up </td>
<td class='confluenceTd'> A communication path is established between the endpoint and Asterisk </td>
</tr>
<tr>
<td class='confluenceTd'> 7 </td>
<td class='confluenceTd'> Busy </td>
<td class='confluenceTd'> A busy indication has occurred on the channel </td>
</tr>
<tr>
<td class='confluenceTd'> 8 </td>
<td class='confluenceTd'> Dialing Offhook </td>
<td class='confluenceTd'> Digits (or equivalent) have been dialed while offhook </td>
</tr>
<tr>
<td class='confluenceTd'> 9 </td>
<td class='confluenceTd'> Pre-ring </td>
<td class='confluenceTd'> The channel technology has detected an incoming call and is waiting for a ringing indication </td>
</tr>
<tr>
<td class='confluenceTd'> 10 </td>
<td class='confluenceTd'> Unknown </td>
<td class='confluenceTd'> The channel is an unknown state </td>
</tr>
</tbody></table>
</div>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Depending on the underlying channel technology, not all states will be used. Channels typically begin in either the Down or Up states.</td></tr></table></div>
<h6><a name="AMI1.4Specification-ChannelStateDesc"></a>4.2.1.2.2.4. ChannelStateDesc</h6>
<p>The text description of the channel state. This will be one of the State descriptions in the table in <a href="#AMI1.4Specification-eventchannelstate">ChannelState</a>.</p>
<h6><a name="AMI1.4Specification-CallerIDNum"></a>4.2.1.2.2.5. CallerIDNum</h6>
<p>The current caller ID number. If the caller ID number is not known, the string "<unknown>" is returned instead.</p>
<h6><a name="AMI1.4Specification-CallerIDName"></a>4.2.1.2.2.6. CallerIDName</h6>
<p>The current caller ID name. If the caller ID name is not known, the string "<unknown>" is returned instead.</p>
<h6><a name="AMI1.4Specification-ConnectedLineNum"></a>4.2.1.2.2.7. ConnectedLineNum</h6>
<p>The current connected line number. If the connected line number is not known, the string "<unknown>" is returned instead.</p>
<h6><a name="AMI1.4Specification-ConnectedLineName"></a>4.2.1.2.2.8. ConnectedLineName</h6>
<p>The current connected line name. If the connected line name is not known, the string "<unknown>" is returned instead.</p>
<p><a name="AMI1.4Specification-eventtag"></a></p>
<h6><a name="AMI1.4Specification-Tag"></a>4.2.1.2.2.9. Tag</h6>
<p>The tags associated with the channel. If more than one tag is associated with the channel, the tags will be in a comma delineated list.</p>
<h5><a name="AMI1.4Specification-Bridges"></a>4.2.1.2.3. Bridges</h5>
<p>Events raised on bridges most often involve one or more channels. As such, the fields in <a href="#AMI1.4Specification-eventchannels">Channels</a> are a subset of the fields in bridge events. If multiple channels in a bridge event is represented, the nomenclature <tt>Channel1</tt>, <tt>Channel2</tt>, <tt>Uniqueid1</tt>, <tt>Uniqueid2</tt>, etc. is used.</p>
<h6><a name="AMI1.4Specification-Bridgetype"></a>4.2.1.2.3.1. Bridgetype</h6>
<p>Whether or not the Bridge being referenced is 'native' or 'core'. A native bridge is one that occurs directly between the endpoint's respective technologies, bypassing Asterisk processing as much as possible. A core bridge implies full decoding of the media in the Asterisk core.</p>
<h6><a name="AMI1.4Specification-BridgeUniqueid"></a>4.2.1.2.3.2. BridgeUniqueid</h6>
<p>A unique identifier for the bridge. <b>BridgeEnter</b> and <b>BridgeLeave</b> events MUST contain a BridgeUniqueid field, which provides a way to determine which bridge a channel has entered/left.</p>
<h5><a name="AMI1.4Specification-ActionResponses"></a>4.2.1.2.4. Action Responses</h5>
<p>When an Action is submitted to AMI, the success or failure of the action is communicated in subsequent events.</p>
<h6><a name="AMI1.4Specification-Response"></a>4.2.1.2.4.1. Response</h6>
<p>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.</p>
<h6><a name="AMI1.4Specification-EventList"></a>4.2.1.2.4.2. EventList</h6>
<p>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".</p>
<p>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".</p>
<p>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.</p>
<h6><a name="AMI1.4Specification-Message"></a>4.2.1.2.4.3. Message</h6>
<p>An optional text message that provides additional contextual information regarding the success or failure of the action.</p>
<h2><a name="AMI1.4Specification-Actions"></a>4.3. Actions</h2>
<p>The supported actions for Asterisk 12 are listed here:</p>
<p><a href="/wiki/display/AST/Asterisk+11+AMI+Actions" title="Asterisk 11 AMI Actions">Asterisk 12 AMI Actions</a></p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>These currently link to the Actions for Asterisk 11. This will be changed to point to documentation for Asterisk 12 when that documentation is available.</td></tr></table></div>
<h2><a name="AMI1.4Specification-Events"></a>4.4. Events</h2>
<p>The supported events for Asterisk 12 are listed here:</p>
<p><a href="/wiki/display/AST/Asterisk+11+AMI+Events" title="Asterisk 11 AMI Events">Asterisk 12 AMI Events</a></p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>These currently link to the Actions for Asterisk 11. This will be changed to point to documentation for Asterisk 12 when that documentation is available.</td></tr></table></div>
<h2><a name="AMI1.4Specification-ChannelInteraction%2FLifetime"></a>4.5. Channel Interaction/Lifetime</h2>
<p>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.</p>
<h3><a name="AMI1.4Specification-BasicChannelLifetime"></a>4.5.1. Basic Channel Lifetime</h3>
<p>All channels begin with a <b>NewChannel</b> event. A <b>NewChannel</b> contains the following fields:</p>
<ul>
<li>The current <a href="#AMI1.4Specification-actionchannel">Channel</a> name</li>
<li>The <a href="#AMI1.4Specification-actionuniqueid">Uniqueid</a> that acts as a handle to the channel for that channel's lifetime</li>
<li>The <a href="#AMI1.4Specification-eventtag">Tag</a> field that lists all tags associated with the channel</li>
</ul>
<p>Channels are disposed of in two ways. The first, and most common, is indicated via a <b>Hangup</b> event. A <b>Hangup</b> signals the termination of the channel associated with the Uniqueid. After the <b>Hangup</b> 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.</p>
<p>The second way a channel can be disposed of is by a failed dial operation. In this case, a <b>DialEnd</b> event will be sent to the AMI client with a DialStatus field with some value other than ANSWER. In this scenario, the channel is implicitly destroyed, and no further events will be raised in relation to the channel with that Uniqueid.</p>
<h3><a name="AMI1.4Specification-ChannelVariables"></a>4.5.2. Channel Variables</h3>
<p>For each channel variable that is changed, a <b>VarSet</b> event is sent to the client. The <b>VarSet</b> event contains the new value of the appropriate channel variable.</p>
<h3><a name="AMI1.4Specification-DTMF"></a>4.5.3. DTMF</h3>
<p>DTMF is indicated via a <b>DTMFBegin</b>/<b>DTMFEnd</b> events. A <b>DTMFEnd</b> event MUST convey the duration of the DTMF tone in milliseconds.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>The combination of <b>DTMFBegin</b>/<b>DTMFEnd</b> events replaces the deprecated <b>DTMF</b> event.</td></tr></table></div>
<h3><a name="AMI1.4Specification-DialplanExecution"></a>4.5.4. Dialplan Execution</h3>
<p>As a channel executes operations in the dialplan, those operations are conveyed via a <b>NewExten</b> event. Each transition to a new combination of context, extension, and priority will trigger a <b>NewExten</b> event.</p>
<div class="panel" style="border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;"><b>Example</b></div><div class="panelContent">
<table><tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: Newexten
Privilege: dialplan,all
Channel: SIP/kermit-00000001
Uniqueid: 550e8400-e29b-41d4-a716-446655440000
...
Context: default
Extension: h
Priority: 1
Application: NoOp
AppData: Ah Snap
</pre>
</div></div></td>
<td><p>Kermit the Frog's SIP channel has been hung up, and he's been tossed rudely into the <em>h</em> extension. This event informs the clients that Kermit's channel is in context <em>default</em>, extension <em>h</em>, priority <em>1</em>, and is about to execute the <em>NoOp</em> application with application data <em>"Ah Snap"</em>.</p></td></tr></table>
</div></div>
<h3><a name="AMI1.4Specification-Dialing"></a>4.5.5. Dialing</h3>
<p>Dial operations always result in two events: a <b>DialBegin</b> event that signals the beginning of the dial to a particular destination, and a <b>DialEnd</b> event that signals the end of the dialing. In parallel dialing situations, <b>DialBegin</b>/<b>DialEnd</b> events MUST be sent for each channel dialed. For each <b>DialBegin</b> event sent, there MUST be a corresponding <b>DialEnd</b> event.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>The pair of <b>DialBegin</b>/<b>DialEnd</b> events replaces the deprecated <b>Dial</b> event. Note that the <b>Dial</b> event signalling the end of dialing would not normally be sent until after bridging was complete; this operation should now occur when the dial operation has determined the status of a particular called channel.</td></tr></table></div>
<p>A <b>DialEnd</b> occurs whenever Asterisk knows the final state of the channel that it was attempting to establish. This is communicated in the DialStatus field.</p>
<div class="panel" style="border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;"><b>Simple Successful Dial</b></div><div class="panelContent">
<p></p>
<table><tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: NewChannel
Channel: SIP/animal-00000001
Uniqueid: 550e8400-e29b-41d4-a716-446655440000
...
Event: DialBegin
Channel: SIP/animal-00000001
Uniqueid: 550e8400-e29b-41d4-a716-446655440000
...
Event: DialEnd
Channel: SIP/animal-00000001
Uniqueid: 550e8400-e29b-41d4-a716-446655440000
DialStatus: ANSWER
...
</pre>
</div></div></td><td><p>In this example, we decide to dial Animal. We create a new channel to between Asterisk and Animal's SIP device, and begin a dial operation. When Animal eats his handset (causing the device to think he merely took it off the hook), the SIP device answers and the dial operation completes. This indicated by a <b>DialEnd</b> event. At this point, the channel is ready for something - it can execute in the dialplan, or be immediately bridged with another channel (which is usually the channel that initiated the dial operation in the first place.)</p></td></tr></table>
</div></div>
<div class="panel" style="border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;"><b>Simple Failed Dial</b></div><div class="panelContent">
<p></p>
<table><tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: NewChannel
Channel: SIP/animal-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440002
...
Event: DialBegin
Channel: SIP/animal-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440002
...
Event: DialEnd
Channel: SIP/animal-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440002
DialStatus: TIMEDOUT
...
</pre>
</div></div></td><td><p>In this example, we decide to dial Animal again. Unfortunately, Animal ate his handset, so we inevitably time out. When we do, a DialEnd event is received indicating the failure.</p></td></tr></table>
</div></div>
<div class="panel" style="border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;"><b>Parallel Dial</b></div><div class="panelContent">
<p></p>
<table><tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: NewChannel
Channel: SIP/animal-00000003
Uniqueid: 550e8400-e29b-41d4-a716-446655440003
...
Event: NewChannel
Channel: SIP/drteeth-00000004
Uniqueid: 550e8400-e29b-41d4-a716-446655440004
...
Event: DialBegin
Channel: SIP/animal-00000003
Uniqueid: 550e8400-e29b-41d4-a716-446655440003
...
Event: DialBegin
Channel: SIP/drteeth-00000004
Uniqueid: 550e8400-e29b-41d4-a716-446655440004
...
Event: DialEnd
Channel: SIP/drteeth-00000004
Uniqueid: 550e8400-e29b-41d4-a716-446655440004
DialStatus: ANSWER
...
Event: DialEnd
Channel: SIP/animal-00000003
Uniqueid: 550e8400-e29b-41d4-a716-446655440003
DialStatus: CANCEL
...
</pre>
</div></div></td><td><p>In this example, we decide to dial Animal and Dr. Teeth. Dr. Teeth immediately answers, and so we cancel the dial to Animal. We can now do something with Dr. Teeth's channel (such as bridge him with his dentist) - however, Animal's channel is implicitly destroyed, as his device never answered.</p></td></tr></table>
</div></div>
<h3><a name="AMI1.4Specification-Bridging"></a>4.5.6. Bridging</h3>
<p>A bridge contains 0 or more channels. When a channel is in a bridge, it has the potential to communicate with other channels within the bridge. Before channels enter a bridge, a <b>BridgeCreate</b> event is sent, indicating that a bridge has been created. When a bridge is destroyed, a <b>BridgeDestroy</b> event is sent. All channels within a bridge must leave a bridge prior to the <b>BridgeDestroy</b> event being sent.</p>
<p>When a channel enters a bridge, a <b>BridgeEnter</b> event is raised. When a channel is put into a bridge, it is implied that the channel can pass media between other channels in the bridge. This is not guaranteed, as other properties on the channel or bridge may restrict media flow. When a channel leaves a bridge, a corresponding <b>BridgeLeave</b> event is raised. A <b>BridgeLeave</b> event MUST mean that the channel that left the bridge can no longer pass media to other channels still in the bridge. This does not necessarily mean that the channel is being hung up; rather, that it is no longer in a communication path with some other set of channels. In some scenarios, a channel may enter a bridge that has no other channels; this could occur when the channel has been put in some hold state (such as in a parking lot).</p>
<p>In all cases, if a channel has a <b>BridgeEnter</b> event, it MUST have a corresponding <b>BridgeLeave</b> event. If a channel is hung up and it is in a bridge, a <b>BridgeLeave</b> event MUST precede the <b>Hangup</b> event.</p>
<p>If a transfer operation begins, a <b>Transfer</b> event MUST be raised for the channels involved in the transfer prior to those channels leaving the bridge or entering another bridge. Similarly, if a channel enters a parking lot, a <b>ParkedCall</b> event MUST be raised for the channel prior to it entering the bridge that represents the parking lot.</p>
<p>If a property of a bridge is changed, such as the type going from a "native" bridge to a "core" bridge, then the <b>BridgeUpdate</b> event is sent with the updated parameters.</p>
<h4><a name="AMI1.4Specification-TwoPartyBridging"></a>4.5.6.1. Two Party Bridging</h4>
<p>Parties are bridged by virtue of them entering a bridge, as indicated by a <b>BridgeEnter</b>. When parties are no longer talking, a <b>BridgeLeave</b> event is sent for each channel that leaves the bridge.</p>
<div class="panel" style="border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;"><b>Example - Two Party Bridge</b></div><div class="panelContent">
<p></p>
<table><tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: BridgeCreate
Bridgetype: core
BridgeUniqueid: 1234
...
Event: BridgeEnter
Bridgetype: core
BridgeUniqueid: 1234
Channel: SIP/kermit-00000001
Uniqueid: 550e8400-e29b-41d4-a716-446655440000
...
</pre>
</div></div></td>
<td>Kermit the Frog's SIP channel enters into Bridge 1234. As a result, the bridge is first created (denoted by the <b>BridgeCreate</b> event), and then Kermit's channel enters the bridge (the <b>BridgeEnter</b> event)</td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: BridgeEnter
Bridgetype: core
BridgeUniqueid: 1234
Channel: SIP/gonzo-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440001
...
</pre>
</div></div></td>
<td><br/>
Gonzo the Great enters the bridge and talks with Kermit. Note that the bridge Gonzo entered is Bridge 1234; by virtue of this being the same bridge Kermit entered, we know that the two can talk.</td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: BridgeLeave
Bridgetype: core
BridgeUniqueid: 1234
Channel: SIP/kermit-00000001
Uniqueid: 550e8400-e29b-41d4-a716-446655440000
...
Event: Hangup
Channel: SIP/kermit-00000001
Uniqueid: 550e8400-e29b-41d4-a716-446655440000
...
</pre>
</div></div></td>
<td>Kermit decided he was tired of Gonzo's pontificating, and hung up on Gonzo. We are first alerted that Kermit has left the bridge; quickly thereafter, we receive the <b>Hangup</b> event indicating that Kermit's channel is dead.</td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: BridgeLeave
Bridgetype: core
BridgeUniqueid: 1234
Channel: SIP/gonzo-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440001
...
Event: Hangup
Channel: SIP/gonzo-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440001
...
Event: BridgeDestroy
Bridgetype: core
BridgeUniqueid: 1234
...
</pre>
</div></div></td>
<td><p>Asterisk is configured to not let Gonzo continue on in the dialplan once his bridge is broken. As such, Gonzo is forcibly ejected from the bridge, and is hung up on after. Because no channels are left in the bridge, the bridge is destroyed.</p></td></tr></table>
</div></div>
<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>In this scenario, it was perfectly acceptable for either Kermit or Gonzo's channels to continue after the bridge was broken. Since this represents the most basic two-party call scenario, once one party decided to hang up, the other party was also hung up on.</td></tr></table></div>
<h4><a name="AMI1.4Specification-Transfers"></a>4.5.6.2. Transfers</h4>
<p>Transfers begin with a <b>Transfer</b> event, which indicates information about the transfer that is about to take place. Subsequently, <b>BridgeLeave</b>/<b>BridgeEnter</b> events are used to indicate which channels are talking at different stages during the transfer.</p>
<div class="panel" style="border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;"><b>Example - Blind Transfer</b></div><div class="panelContent">
<table><tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: BridgeCreate
Bridgetype: core
BridgeUniqueid: 1234
...
Event: BridgeEnter
Bridgetype: core
BridgeUniqueid: 1234
Channel: SIP/kermit-00000001
Uniqueid: 550e8400-e29b-41d4-a716-446655440000
...
</pre>
</div></div></td>
<td>Kermit the Frog's SIP channel enters into Bridge 1234</td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: BridgeEnter
Bridgetype: core
BridgeUniqueid: 1234
Channel: SIP/fozzie-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440001
...
</pre>
</div></div></td>
<td>Fozzie Bear's SIP channel enters into Bridge 1234. At this point, Fozzie and Kermit can talk to each other.</td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: Transfer
Privilege: call,all
TransferMethod: Core
TransferType: Blind
Channel: SIP/fozzie-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440001
TargetChannel: SIP/kermit-00000001
TargetUniqueid: 550e8400-e29b-41d4-a716-446655440000
TransferExten: call_miss_piggy
TransferContext: default
</pre>
</div></div></td>
<td>Fozzie decides he's tired of telling Kermit jokes and blind transfers him off to Miss Piggy via the dialplan extension <tt>call_miss_piggy</tt>. The fact that a transfer is occurring starts off with the <b>Transfer</b> event. This tells the user who initiates the transfer, who is being transferred, and where the transfer target is going.</td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: BridgeLeave
Bridgetype: core
BridgeUniqueid: 1234
Channel: SIP/kermit-00000001
...
</pre>
</div></div></td>
<td>Kermit leaves the bridge with Fozzie.</td></tr>
<tr><td colspan="2"><div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>At this point, the order of the events that affect Fozzie versus Kermit are not defined. Fozzie and Kermit are no longer bridged together, and their respective events may arrive in any order.</td></tr></table></div></td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: BridgeLeave
Bridgetype: core
BridgeUniqueid: 1234
Channel: SIP/fozzie-00000002
...
Event: BridgeDestroy
Bridgetype: core
BridgeUniqueid: 1234
...
</pre>
</div></div></td>
<td>Because Fozzie isn't talking to anyone anymore, he leaves the bridge as well. At this point Asterisk could hang up Fozzie's channel, or, if configured, he could continue on in the dialplan (say, perhaps, to talk to his rubber chicken).</td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: NewChannel
Channel: SIP/miss_piggy-00000003
Uniqueid: 550e8400-e29b-41d4-a716-446655440002
...
Event: DialBegin
Channel: SIP/miss_piggy-00000003
Uniqueid: 550e8400-e29b-41d4-a716-446655440002
...
Event: DialEnd
Channel: SIP/miss_piggy-00000003
Uniqueid: 550e8400-e29b-41d4-a716-446655440002
DialStatus: ANSWER
...
</pre>
</div></div></td>
<td>The act of Kermit entering into extension <tt>call_miss_piggy</tt> causes a new channel to be created between Asterisk and Miss Piggy. Asterisk immediately dials Miss Piggy, who answers.</td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: BridgeCreate
Bridgetype: core
BridgeUniqueid: 1235
...
Event: BridgeEnter
Bridgetype: core
BridgeUniqueid: 1235
Channel: SIP/kermit-00000001
Uniqueid: 550e8400-e29b-41d4-a716-446655440000
...
</pre>
</div></div></td>
<td>Kermit enters into a bridge. Note that the <b>BridgeUniqueid</b> is different than the previous bridge's <b>BridgeUniqueid</b>.</td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: BridgeEnter
Bridgetype: core
BridgeUniqueid: 1235
Channel: SIP/miss_piggy-00000003
Uniqueid: 550e8400-e29b-41d4-a716-446655440002
...
</pre>
</div></div></td>
<td>Miss Piggy enters the bridge. At this point, Kermit and Miss Piggy can converse, and the blind transfer is complete.</td></tr></table>
</div></div>
<h3><a name="AMI1.4Specification-LocalChannels"></a>4.5.7. Local Channels</h3>
<p>Local channels are different than 'normal' channels in Asterisk, in that they have several properties that make them unique:</p>
<ul>
<li>A Local channel never has a physical device that it directly communicates with - it exists as a virtual channel within Asterisk.</li>
<li>A Local channel can communicate with one or more channels, or directly with an Asterisk application.</li>
<li>Local channels can be optimized out of a communication path, causing the state of bridges and channels to change.</li>
<li>A Local channel is actually always two separate channels with a special bridge between them.</li>
</ul>
<table width="100%">
<tr>
<td align="left" >
<table>
<caption align="bottom">
</caption>
<tr>
<td>
<img style="border: none; width: 697px;"
usemap="#gliffy-map-22478874-1128"
src="/wiki/download/attachments/22086004/AMI+Local+Channels+Diagram.png?version=1&modificationDate=1357310830765"
alt=""/>
</td>
</tr>
</table>
</td>
</tr>
</table>
<p>While the Local channel exists as a single concept from the perspective of the dialplan, from the perspective of an AMI client, it is always two channels that are tied together by a special bridge. When the bridge between the Local channel halves is formed, a <b>LocalBridge</b> event is raised denoting that the two are connected.</p>
<h4><a name="AMI1.4Specification-LocalChannelCreation"></a>4.5.7.1. Local Channel Creation</h4>
<p>When a Local channel is created, a <b>NewChannel</b> event is created for each half of the Local channel being created. Each Local channel half has its own Channel field name and its own Uniqueid - for the purposes of an AMI client, they are two separate channels that can be manipulated separately but whose lifetime is tied together. When either Local channel half is hungup, denoted by a <b>Hangup</b> event, the other Local channel half will also be hungup automatically.</p>
<h4><a name="AMI1.4Specification-LocalChannelBridging"></a>4.5.7.2. Local Channel Bridging</h4>
<p>Local channels receive bridge events in the same fashion as other channels. Thus, when they join a bridge, they receive a <b>BridgeEnter</b> event and when they leave a bridge, a corresponding <b>BridgeLeave</b> event. The exception to this is a Local channel bridge, denoted by a <b>LocalBridge</b> event. Once a <b>LocalBridge</b> event occurs, the two Local channel halves can pass frames back and forth between each other. Because the lifetime of the Local channel halves is the same, there is no event representing a Local channel bridge being broken.</p>
<div class="panel" style="border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;"><b>Example - Local Channel between two SIP Channels</b></div><div class="panelContent">
<table><tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: NewChannel
Channel: SIP/miss_piggy-00000003
Uniqueid: 550e8400-e29b-41d4-a716-446655440002
...
</pre>
</div></div></td>
<td>Miss Piggy decides to call Kermit the Frog, and a channel is created between Asterisk and Miss Piggy's SIP device.</td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: NewChannel
Channel: Local/kermit@default-00000001;1
Uniqueid: 550e8400-e29b-41d4-a716-446655440003
...
Event: NewChannel
Channel: Local/kermit@default-00000001;2
Uniqueid: 550e8400-e29b-41d4-a716-446655440004
...
Event: LocalBridge
Channel1: Local/kermit@default-00000001;1
Channel2: Local/kermit@default-00000001;2
Uniqueid1: 550e8400-e29b-41d4-a716-446655440003
Uniqueid2: 550e8400-e29b-41d4-a716-446655440004
LocalOptimization: No
...Event: DialBegin
Channel: Local/kermit@default-00000001;1
Uniqueid: 550e8400-e29b-41d4-a716-446655440003
...
</pre>
</div></div></td>
<td><br/>
Instead of dialing Kermit the Frog directly, a Local channel is created inside Asterisk and Asterisk dials one half of the Local channel. Note that both halves of the Local channel are created first; the Local channel bridges its two halves together; then a <b>DialBegin</b> event indicates that Asterisk is attempting to connect to one half of the Local channel, <tt>Local/kermit@default-00000001;1</tt>.</td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: DialEnd
Channel: Local/kermit@default-00000001;1
Uniqueid: 550e8400-e29b-41d4-a716-446655440003
DialStatus: ANSWER
...
Event: BridgeCreate
Bridgetype: core
BridgeUniqueid: 1234
...
Event: BridgeEnter
Bridgetype: core
BridgeUniqueid: 1234
Channel: SIP/miss_piggy-00000003
Uniqueid: 550e8400-e29b-41d4-a716-446655440002
...
Event: BridgeEnter
Bridgetype: core
BridgeUniqueid: 1234
Channel: Local/kermit@default-00000001;1
Uniqueid: 550e8400-e29b-41d4-a716-446655440003
...
</pre>
</div></div></td>
<td> The dial operation succeeds and Miss Piggy is bridged with one half of the Local channel that will eventually connect her to Kermit. Note that Miss Piggy doesn't realize that any changes have occurred - from her perspective, nothing has really happened, as the Local channel is a virtual channel and we haven't yet dialed Kermit.</td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: NewChannel
Channel: SIP/kermit-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440005
...
Event: DialBegin
Channel: SIP/kermit-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440005
...
Event: DialEnd
Channel: SIP/kermit-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440005
DialStatus: ANSWER
...
Event: BridgeCreate
Bridgetype: core
BridgeUniqueid: 5678
...
Event: BridgeEnter
Bridgetype: core
BridgeUniqueid: 5678
Channel: Local/kermit@default-00000001;2
Uniqueid: 550e8400-e29b-41d4-a716-446655440004
...
Event: BridgeEnter
Bridgetype: core
BridgeUniqueid: 5678
Channel: SIP/kermit-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440005
...
</pre>
</div></div></td><td><p>We dial Kermit, and he foolishly answers. He is now bridged with the second half of the Local channel, <tt>Local/kermit@default-00000001;2</tt>, as both that channel and the SIP channel communicating with his SIP device have corresponding <b>BridgeEnter</b> events.</p>
<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>In those situations where both a Local channel half and a SIP channel are bridged, there is no ordering guaranteed on which channel enters the bridge first - however, both a Local channel half and the SIP channel will be bridged in the same bridge.</td></tr></table></div></td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: BridgeLeave
Bridgetype: core
BridgeUniqueid: 1234
Channel: SIP/miss_piggy-00000003
Uniqueid: 550e8400-e29b-41d4-a716-446655440002
...
Event: Hangup
Channel: SIP/miss_piggy-00000003
Uniqueid: 550e8400-e29b-41d4-a716-446655440002
...
Event: BridgeLeave
Bridgetype: core
BridgeUniqueid: 1234
Channel: Local/kermit@default-00000001;1
Uniqueid: 550e8400-e29b-41d4-a716-446655440003
...
Event: Hangup
Channel: Local/kermit@default-00000001;1
Uniqueid: 550e8400-e29b-41d4-a716-446655440003
...
Event: BridgeDestroy
Bridgetype: core
BridgeUniqueid: 1234
...
Event: BridgeLeave
Bridgetype: core
BridgeUniqueid: 5678
Channel: Local/kermit@default-00000001;2
Uniqueid: 550e8400-e29b-41d4-a716-446655440004
...
Event: Hangup
Channel: Local/kermit@default-00000001;2
Uniqueid: 550e8400-e29b-41d4-a716-446655440004
...
Event: BridgeLeave
Bridgetype: core
BridgeUniqueid: 5678
Channel: SIP/kermit-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440005
...
Event: Hangup
Channel: SIP/kermit-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440005
...
Event: BridgeDestroy
Bridgetype: core
BridgeUniqueid: 5678
</pre>
</div></div></td>
<td><br/>
Miss Piggy, in a fit of frustrated porkine anger, karate chops her SIP phone, causing it to hangup. She leaves the bridge with the Local channel half, <tt>Local/kermit@default-00000001;1</tt>. This causes it to be hungup, as no one else is in the bridge. Because <tt>Local/kermit@default-00000001;1</tt> is hungup, its corresponding other Local channel half, <tt>Local/kermit@default-00000001;2</tt>, leaves the bridge with Kermit's SIP phone and is also hung up. Kermit's SIP channel realizes it's all by itself (it's not easy being green), leaves the bridge it had with its Local channel half, and hangs up as well.</td></tr></table>
</div></div>
<h4><a name="AMI1.4Specification-LocalChannelOptimization"></a>4.5.7.3. Local Channel Optimization</h4>
<p>Local channels have an option wherein they can be optimized away if there are two other channels in the Answered state on either end of the Local channel half. This option is performed on Local channel creation, and is communicated back to the AMI clients in the <b>LocalBridge</b> event in the LocalOptimization field. When a Local channel optimization occurs, a <b>LocalOptimization</b> event is sent that indicates the channels involved in the optimization and any bridges they happen to be in. If, after the Local channel optimization, either bridges contains only a single channel, then a single channel in that bridge is moved to the bridge that had the other channel half.</p>
<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>It is not defined which channel is moved first - in this situation, that is an implementation detail left up to Asterisk. Suffice to say, if a Local channel is optimized away, Asterisk attempts to rebridge the channels left over.</td></tr></table></div>
<div class="panel" style="border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;"><b>Example - Optimizing Local Channel between two SIP Channels</b></div><div class="panelContent">
<table><tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: NewChannel
Channel: SIP/gonzo-00000001
Uniqueid: 550e8400-e29b-41d4-a716-446655440000
...
</pre>
</div></div></td>
<td>Gonzo decides to call Kermit the Frog, and a channel is created between Asterisk and Gonzo's SIP device.</td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: NewChannel
Channel: Local/kermit@default-00000001;1
Uniqueid: 550e8400-e29b-41d4-a716-446655440001
...
Event: NewChannel
Channel: Local/kermit@default-00000001;2
Uniqueid: 550e8400-e29b-41d4-a716-446655440002
...
Event: DialBegin
Channel: Local/kermit@default-00000001;1
Uniqueid: 550e8400-e29b-41d4-a716-446655440001
...
</pre>
</div></div></td>
<td><br/>
Instead of dialing Kermit the Frog directly, a Local channel is created inside Asterisk and Asterisk dials it.</td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: DialEnd
Channel: Local/kermit@default-00000001;1
Uniqueid: 550e8400-e29b-41d4-a716-446655440001
DialStatus: ANSWER
...
Event: BridgeCreate
Bridgetype: core
BridgeUniqueid: 1234
...
Event: BridgeEnter
Bridgetype: core
BridgeUniqueid: 1234
Channel: SIP/gonzo-00000001
Uniqueid: 550e8400-e29b-41d4-a716-446655440000
...
Event: BridgeEnter
Bridgetype: core
BridgeUniqueid: 1234
Channel: Local/kermit@default-00000001;1
Uniqueid: 550e8400-e29b-41d4-a716-446655440001
...
Event: LocalBridge
Channel1: Local/kermit@default-00000001;1
Channel2: Local/kermit@default-00000001;2
Uniqueid1: 550e8400-e29b-41d4-a716-446655440001
Uniqueid2: 550e8400-e29b-41d4-a716-446655440002
LocalOptimization: Yes
...
</pre>
</div></div></td>
<td> The dial operation succeeds and Gonzo is bridged with one half of the Local channel that will eventually connect him (it?) to Kermit. The Local channel itself has also decided to go ahead and bridge the two local halves together, since we have one half of the full chain of channels established. Note that we are told at this point that the Local channel will attempt to optimize itself away, if Kermit answers.</td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: DialBegin
Channel: SIP/kermit-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440003
...
Event: DialEnd
Channel: SIP/kermit-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440003
DialStatus: ANSWER
...
Event: BridgeCreate
Bridgetype: core
BridgeUniqueid: 5678
...
Event: BridgeEnter
Bridgetype: core
BridgeUniqueid: 5678
Channel: Local/kermit@default-00000001;2
Uniqueid: 550e8400-e29b-41d4-a716-446655440002
...
Event: BridgeEnter
Bridgetype: core
BridgeUniqueid: 5678
Channel: SIP/kermit-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440003
...
</pre>
</div></div></td><td><p>We dial Kermit and he answers. He is now bridged with the second half of the Local channel, <tt>Local/kermit@default-00000001;2</tt>.</p>
<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Note that even in the optimizing case, both the Local channel halves and the other channels involved first enter their respective bridges.</td></tr></table></div></td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: LocalOptimization
Channel1: Local/kermit@default-00000001;1
Uniqueid1: 550e8400-e29b-41d4-a716-446655440001
BridgeUniqueid1: 1234
Channel2: Local/kermit@default-00000001;2
Uniqueid2: 550e8400-e29b-41d4-a716-446655440002
BridgeUniqueid2: 5678
...
Event: BridgeLeave
Bridgetype: core
BridgeUniqueid: 5678
Channel: SIP/kermit-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440003
...Event: BridgeEnter
Bridgetype: core
BridgeUniqueid: 1234
Channel: SIP/kermit-00000002
Uniqueid: 550e8400-e29b-41d4-a716-446655440003
...
</pre>
</div></div></td>
<td><p>Asterisk determines that it can optimize away the Local channel. It notifies the AMI client that this is about to occur, which Local channels are involved, and what bridges they are currently in. It starts first by moving Kermit into Gonzo's bridge. From their perspective, nothing has happened - they just now happen to be in the same bridge, instead of having a Local channel pass frames for them.</p>
<p>Note that before this happens, a <b>LocalOptimization</b> event is sent indicating that some shenanigans are about to ensue with the Local channels and by extension, the bridges they are in.</p>
</td></tr>
<tr><td><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Event: BridgeLeave
Bridgetype: core
BridgeUniqueid: 5678
Channel1: Local/kermit@default-00000001;2
Uniqueid1: 550e8400-e29b-41d4-a716-446655440002
...
Event: BridgeLeave
Bridgetype: core
BridgeUniqueid: 1234
Channel1: Local/kermit@default-00000001;1
Uniqueid1: 550e8400-e29b-41d4-a716-446655440001
...
Event: Hangup
Channel1: Local/kermit@default-00000001;1
Uniqueid1: 550e8400-e29b-41d4-a716-446655440001
...
Event: Hangup
Channel1: Local/kermit@default-00000001;2
Uniqueid1: 550e8400-e29b-41d4-a716-446655440002
...Event: BridgeDestroy
Bridgetype: core
BridgeUniqueid: 5678
...
</pre>
</div></div></td>
<td><p>The Local channels now leave their bridges and are hung up. As a result, the bridge with no channels left in it - Bridge 5678 - is destroyed.</p>
</td></tr></table>
</div></div>
<p><a name="AMI1.4Specification-masquerades"></a></p>
<h3><a name="AMI1.4Specification-Masquerades"></a>4.5.8. Masquerades</h3>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Masquerades have changed</b><br />In the past, masquerades occurred rather frequently - most often in any scenario where a transfer occurred or where a <tt>pbx_thread</tt> needed to be associated with a channel. This has now changed. Masquerades now rarely occur, and are never communicated to AMI clients. From the perspective of AMI clients, nothing changes - you still use your handle to a channel to communicate with it, regardless of the presence (or lack thereof) of a masquerade operation.
<p>This note only exists to explicitly call out that fact.</p></td></tr></table></div>
<p><a name="AMI1.4Specification-transporthttp"></a></p>
<h2><a name="AMI1.4Specification-Transports"></a>4.6. Transports</h2>
<p>AMI supports the following transport mechanisms:</p>
<ul>
<li>TCP/TLS</li>
<li>HTTP/HTTPS</li>
</ul>
<p>When clients connect over HTTP/HTTPS, AMI events are queued up for retrieval. Events queued up for a client are automatically retrieved and sent in the response to any POST operation. The <b>WaitEvent</b> action can be used to wait for and retrieve AMI events.</p>
<h1><a name="AMI1.4Specification-SecurityConsiderations"></a>5. Security Considerations</h1>
<p>AMI supports security at the transport level via TLS using OpenSSL.</p>
<p><a name="AMI1.4Specification-classauthorizations"></a></p>
<h2><a name="AMI1.4Specification-ClassAuthorizations"></a>5.1. Class Authorizations</h2>
<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Do not rely on class authorizations for security. While they provide a means to restrict a client's access to sets of functionality, there are often ways of achieving similar functionality through multiple mechanisms. Do <b>NOT</b> assume that because a class authorization has not been granted to a client, that they can't find a way around it. In general, view class authorizations as a coarse grained way of providing sets of filters.</td></tr></table></div>
<p>Events and actions are automatically classified with particular class authorizations. Clients can be configured to support some set of class authorizations, filtering the actions that they can perform and events that they receive. The supported class authorizations are listed below.</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Class Type </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> system </td>
<td class='confluenceTd'> The item is associated with something that reports on the status of the system or manipulates the system in some fashion </td>
</tr>
<tr>
<td class='confluenceTd'> call </td>
<td class='confluenceTd'> The item is associated with calls, i.e., state changes in a call, etc. </td>
</tr>
<tr>
<td class='confluenceTd'> log </td>
<td class='confluenceTd'> The item is associated with the logging subsystem </td>
</tr>
<tr>
<td class='confluenceTd'> verbose </td>
<td class='confluenceTd'> The item is associated with verbose messages </td>
</tr>
<tr>
<td class='confluenceTd'> command </td>
<td class='confluenceTd'> The item is associated with execution of CLI commands through AMI </td>
</tr>
<tr>
<td class='confluenceTd'> agent </td>
<td class='confluenceTd'> The item is associated with Queue Agent manipulation </td>
</tr>
<tr>
<td class='confluenceTd'> user </td>
<td class='confluenceTd'> The item is associated with user defined events </td>
</tr>
<tr>
<td class='confluenceTd'> config </td>
<td class='confluenceTd'> The item is associated with manipulating the configuration of Asterisk </td>
</tr>
<tr>
<td class='confluenceTd'> dtmf </td>
<td class='confluenceTd'> The item is associated with DTMF manipulation </td>
</tr>
<tr>
<td class='confluenceTd'> reporting </td>
<td class='confluenceTd'> The item is associated with querying information about the state of the Asterisk system </td>
</tr>
<tr>
<td class='confluenceTd'> cdr </td>
<td class='confluenceTd'> The item is associated with CDR manipulation </td>
</tr>
<tr>
<td class='confluenceTd'> dialplan </td>
<td class='confluenceTd'> The item is associated with dialplan execution </td>
</tr>
<tr>
<td class='confluenceTd'> originate </td>
<td class='confluenceTd'> The item is associated with originating a channel </td>
</tr>
<tr>
<td class='confluenceTd'> agi </td>
<td class='confluenceTd'> The item is associated with AGI execution </td>
</tr>
<tr>
<td class='confluenceTd'> cc </td>
<td class='confluenceTd'> The item is associated with call completion </td>
</tr>
<tr>
<td class='confluenceTd'> aoc </td>
<td class='confluenceTd'> The item is associated with Advice of Charge </td>
</tr>
<tr>
<td class='confluenceTd'> test </td>
<td class='confluenceTd'> The item is associated with some test action </td>
</tr>
<tr>
<td class='confluenceTd'> message </td>
<td class='confluenceTd'> The item is associated with out of call messaging </td>
</tr>
<tr>
<td class='confluenceTd'> all </td>
<td class='confluenceTd'> The item has all class authorizations associated with it </td>
</tr>
<tr>
<td class='confluenceTd'> none </td>
<td class='confluenceTd'> The item has no class authorization associated with it </td>
</tr>
</tbody></table>
</div>
<h2><a name="AMI1.4Specification-AccessControlLists"></a>5.2. Access Control Lists</h2>
<p>Access Control Lists can be used to filter connections based on address. If an attempt to connect from an unauthorized address is detected, the connection attempt will be rejected.</p>
<h2><a name="AMI1.4Specification-Authorization"></a>5.3. Authorization</h2>
<p>Authorization can be provided via the <b>Login</b> action. If a client fails to provide a valid username/password, the connection attempt and any subsequent actions will be rejected. Events will not be sent until the client provides authorized credentials.</p>
<p>The actions that are excluded from successful login are:</p>
<ul>
<li><b>Login</b></li>
<li><b>Logout</b></li>
<li><b>Challenge</b></li>
</ul>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>The action <b>Logoff</b> has been replaced by a corresponding action <b>Logout</b>. <b>Logoff</b> has been deprecated in favor of <b>Logout</b>.</td></tr></table></div>
<p><a name="AMI1.4Specification-amiconfiguration"></a></p>
<h1><a name="AMI1.4Specification-AMIConfiguration"></a>6. AMI Configuration</h1>
<p>AMI supports the following configuration options. Note that additional configurations MAY be specified; however, these configuration options are valid for Asterisk 12.</p>
<h2><a name="AMI1.4Specification-GeneralSettings"></a>6.1. General Settings</h2>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Option </th>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Description </th>
<th class='confluenceTh'> Default </th>
</tr>
<tr>
<td class='confluenceTd'> enabled </td>
<td class='confluenceTd'> Boolean </td>
<td class='confluenceTd'> Enable AMI </td>
<td class='confluenceTd'> no </td>
</tr>
<tr>
<td class='confluenceTd'> webenabled </td>
<td class='confluenceTd'> Boolean </td>
<td class='confluenceTd'> Enable AMI over HTTP/HTTPS </td>
<td class='confluenceTd'> no </td>
</tr>
<tr>
<td class='confluenceTd'> port </td>
<td class='confluenceTd'> Integer </td>
<td class='confluenceTd'> The port AMI's TCP server will bind to </td>
<td class='confluenceTd'> 5038 </td>
</tr>
<tr>
<td class='confluenceTd'> bindaddr </td>
<td class='confluenceTd'> IP Address </td>
<td class='confluenceTd'> The address AMI's TCP server will bind to </td>
<td class='confluenceTd'> 0.0.0.0 </td>
</tr>
<tr>
<td class='confluenceTd'> tlsenable </td>
<td class='confluenceTd'> Boolean </td>
<td class='confluenceTd'> Enable TLS over TCP </td>
<td class='confluenceTd'> no </td>
</tr>
<tr>
<td class='confluenceTd'> tlsbindaddr </td>
<td class='confluenceTd'> IP Address </td>
<td class='confluenceTd'> The address AMI's TCP/TLS server will bind to </td>
<td class='confluenceTd'> 0.0.0.0:5039 </td>
</tr>
<tr>
<td class='confluenceTd'> tlscertfile </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> The full path to the TLS certificate to use </td>
<td class='confluenceTd'> /tmp/asterisk.pem </td>
</tr>
<tr>
<td class='confluenceTd'> tlsprivatekey </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> The full path to the private key. If no path is specified, <em>tlscertfile</em> will be used for the private key. </td>
<td class='confluenceTd'> /tmp/private.pem </td>
</tr>
<tr>
<td class='confluenceTd'> tlscipher </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> The string specifying which SSL ciphers to use. Valid SSL ciphers can be found at <a href="http://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS" class="external-link" rel="nofollow">http://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS</a> </td>
<td class='confluenceTd'> </td>
</tr>
<tr>
<td class='confluenceTd'> allowmultiplelogin </td>
<td class='confluenceTd'> Boolean </td>
<td class='confluenceTd'> Allow multiple logins for the same user. If set to no, multiple logins from the same user will be rejected. </td>
<td class='confluenceTd'> Yes </td>
</tr>
<tr>
<td class='confluenceTd'> timestampevents </td>
<td class='confluenceTd'> Boolean </td>
<td class='confluenceTd'> Add a Unix epoch <b>Timestamp</b> field to all AMI events </td>
<td class='confluenceTd'> No </td>
</tr>
<tr>
<td class='confluenceTd'> authlimit </td>
<td class='confluenceTd'> Integer </td>
<td class='confluenceTd'> The number of unauthenticated clients that can be connected at any time </td>
<td class='confluenceTd'> </td>
</tr>
</tbody></table>
</div>
<p><a name="AMI1.4Specification-configurationclient"></a></p>
<h2><a name="AMI1.4Specification-ClientSettings"></a>6.2. Client Settings</h2>
<p>Note that the name of the client settings context is the username for the client connection.</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Option </th>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Description </th>
<th class='confluenceTh'> Default </th>
</tr>
<tr>
<td class='confluenceTd'> secret </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> The password that must be provided by the client via the <b>Login</b> action </td>
<td class='confluenceTd'> </td>
</tr>
<tr>
<td class='confluenceTd'> deny </td>
<td class='confluenceTd'> ACL </td>
<td class='confluenceTd'> An address/mask to deny in an ACL. This option may be present multiple times. </td>
<td class='confluenceTd'> </td>
</tr>
<tr>
<td class='confluenceTd'> permit </td>
<td class='confluenceTd'> ACL </td>
<td class='confluenceTd'> An address/mask to allow in an ACL. This option may be present multiple times. </td>
<td class='confluenceTd'> </td>
</tr>
<tr>
<td class='confluenceTd'> acl </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> A Named ACL to apply to the client. </td>
<td class='confluenceTd'> </td>
</tr>
<tr>
<td class='confluenceTd'> setvar </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> A channel variable key/value pair (using the nomenclature VARIABLE=value) that will be set on all channels originated from this client </td>
<td class='confluenceTd'> </td>
</tr>
<tr>
<td class='confluenceTd'> eventfilter </td>
<td class='confluenceTd'> Regular Expression </td>
<td class='confluenceTd'> This option may be present multiple times. This options allows clients to whitelist or blacklist events. A filter is assumed to be a whitelist unless preceeded by a '!'. Evaluation of the filters is as follows:
<ul>
<li>If no filters are configured all events are reported as normal.</li>
<li>If there are white filters only: implied black all filter processed first, then white filters.</li>
<li>If there are black filters only: implied white all filter processed first, then black filters.</li>
<li>If there are both white and black filters: implied black all filter processed first, then white filters, and lastly black filters.</li>
</ul>
</td>
<td class='confluenceTd'> </td>
</tr>
<tr>
<td class='confluenceTd'> read </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> A comma delineated list of the allowed class authorizations applied to events </td>
<td class='confluenceTd'> all </td>
</tr>
<tr>
<td class='confluenceTd'> write </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> A comma delineated list of the allowed class authorizations applied to actions </td>
<td class='confluenceTd'> all </td>
</tr>
<tr>
<td class='confluenceTd'> tag </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> If present, the client will only receive events that are related to channels created in relation to endpoints that are configured with the same tag. See <a href="#AMI1.4Specification-publishsubscribe">Publish/Subscribe</a> for more information. </td>
<td class='confluenceTd'> </td>
</tr>
</tbody></table>
</div>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://wiki.asterisk.org/wiki/users/removespacenotification.action?spaceKey=AST">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://wiki.asterisk.org/wiki/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/AST/AMI+1.4+Specification">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=22086004&revisedVersion=5&originalVersion=4">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/AMI+1.4+Specification?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>