Core

Asterisk provides a rich collection of features by default, the standard set of which are described here.

Members

All of the following objects should be accessed as part of the ami.core namespace, regardless of the modules in which they are defined.

Constants

AUTHTYPE_MD5

Uses MD5 authentication when logging into AMI

EVENTMASK_ALL

Turns on all events with the ami.core.Events action

EVENTMASK_NONE

Turns off all events with the ami.core.Events action

EVENTMASK_CALL

Turns on call events with the ami.core.Events action

EVENTMASK_LOG

Turns on log events with the ami.core.Events action

EVENTMASK_SYSTEM

Turns on system events with the ami.core.Events action

FORMAT_SLN

Selects the sln audio format

FORMAT_G723

Selects the g723 audio format

FORMAT_G729

Selects the g729 audio format

FORMAT_GSM

Selects the gsm audio format

FORMAT_ALAW

Selects the alaw audio format

FORMAT_ULAW

Selects the ulaw audio format

FORMAT_VOX

Selects the vox audio format

FORMAT_WAV

Selects the wav audio format

ORIGINATE_RESULT_REJECT

Remote extension rejected (hung up) without answering

ORIGINATE_RESULT_RING_LOCAL

Local extension rang, but didn’t answer

ORIGINATE_RESULT_RING_REMOTE

Remote extension rang, but didn’t answer

ORIGINATE_RESULT_ANSWERED

Remote extension answered

ORIGINATE_RESULT_BUSY

Remote extension was busy

ORIGINATE_RESULT_CONGESTION

Remote extension was unreachable

ORIGINATE_RESULT_INCOMPLETE

Remote extension could not be identified

Actions

class ami.core.AbsoluteTimeout(channel, seconds=0)

Bases: _Request

Causes Asterisk to hang up a channel after a given number of seconds.

Requires call

__init__(channel, seconds=0)

Causes the call on channel to be hung up after seconds have elapsed, defaulting to disabling auto-hangup.

class ami.core.AGI(channel, command, command_id=None)

Bases: _Request

Causes Asterisk to execute an arbitrary AGI application in a call.

Upon successful execution, an ‘AsyncAGI’ event is generated.

Requires call

__init__(channel, command, command_id=None)

channel is the call in which to execute command, the value passed to the AGI dialplan application. command_id is an optional value that will be present in the resulting event, and can reasonably be set to a sequential digit or UUID in your application for tracking purposes.

class ami.core.Bridge(channel_1, channel_2, tone=False)

Bases: _Request

Bridges two channels already connected to Asterisk.

Requires call

__init__(channel_1, channel_2, tone=False)

channel_1 is the channel to which channel_2 will be connected. tone, if True, will cause a sound to be played on channel_2.

class ami.core.Challenge(authtype='MD5')

Bases: _Request

Asks the AMI server for a challenge token to be used to hash the login secret.

The value provided under the returned response’s ‘Challenge’ key must be passed as the ‘challenge’ parameter of the Login object’s constructor:

login = Login(username='me', secret='password', challenge=response.get('Challenge'))
__init__(authtype='MD5')

authtype is used to specify the authentication type to be used.

class ami.core.ChangeMonitor(channel, filename)

Bases: _Request

Changes the filename associated with the recording of a monitored channel. The channel must have previously been selected by the Monitor action.

Requires call

__init__(channel, filename)

channel is the channel to be affected and filename is the new target filename, without extension, as either an auto-resolved or absolute path.

class ami.core.Command(command)

Bases: _Request

Sends an arbitrary shell command to Asterisk, returning its response as a series of lines in the ‘data’ attribute.

Requires command

__init__(command)

command is the command to be executed.

class ami.core.CoreShowChannels

Bases: _Request

Asks Asterisk to list all active channels.

Any number of ‘CoreShowChannel’ events may be generated in response to this request, followed by one ‘CoreShowChannelsComplete’.

Requires system

__init__()

action is the type of action being requested of the Asterisk server.

class ami.core.CreateConfig(filename)

Bases: _Request

Creates an empty configuration file, intended for use before UpdateConfig().

Requires config

__init__(filename)

filename is the name of the file, with extension, to be created.

class ami.core.DBDel(family, key)

Bases: _Request

Deletes a database value from Asterisk.

Requires system

__init__(family, key)

family and key are specifiers to select the value to remove.

class ami.core.DBDelTree(family, key=None)

Bases: _Request

Deletes a database tree from Asterisk.

Requires system

__init__(family, key=None)

family and key (optional) are specifiers to select the values to remove.

class ami.core.DBGet(family, key)

Bases: _Request

Requests a database value from Asterisk.

A ‘DBGetResponse’ event will be generated upon success.

Requires system

__init__(family, key)

family and key are specifiers to select the value to retrieve.

class ami.core.DBPut(family, key, value)

Bases: _Request

Stores a database value in Asterisk.

Requires system

__init__(family, key, value)

family and key are specifiers for where to place value.

class ami.core.Events(mask)

Bases: _Request

Changes the types of unsolicited events Asterisk sends to this manager connection.

__init__(mask)

Mask is one of the following…

  • EVENTMASK_ALL

  • EVENTMASK_NONE

…or an iterable, like a tuple, with any combination of the following…

  • EVENTMASK_CALL

  • EVENTMASK_LOG

  • EVENTMASK_SYSTEM

If an empty value is provided, EVENTMASK_NONE is assumed.

class ami.core.ExtensionState(extension, context)

Bases: _Request

Provides the state of an extension.

If successful, a ‘Status’ key will be present, with one of the following values as a string:

  • -2: Extension removed

  • -1: Extension hint not found

  • 0: Idle

  • 1: In use

  • 2: Busy

If non-negative, a ‘Hint’ key will be present, too, containing string data that can be helpful in discerning the current activity of the device.

Requires call

__init__(extension, context)

extension is the extension to be checked and context is the container in which it resides.

class ami.core.GetConfig(filename)

Bases: _Request

Gets the contents of an Asterisk configuration file.

The result is recturned as a series of ‘Line-XXXXXX-XXXXXX’ keys that increment from 0 sequentially, starting with ‘Line-000000-000000’.

A sequential generator is provided by the ‘get_lines()’ function on the response.

Requires config

get_lines()

Provides a generator that yields every line in order.

__init__(filename)

filename is the name of the config file to be read, including extension.

class ami.core.Getvar(variable, channel=None)

Bases: _Request

Gets the value of a channel or global variable from Asterisk, returning the result under the ‘Value’ key.

Requires call

__init__(variable, channel=None)

variable is the name of the variable to retrieve. channel is optional; if not specified, a global variable is retrieved.

class ami.core.Hangup(channel)

Bases: _Request

Hangs up a channel.

On success, a ‘Hangup’ event is generated.

Requires call

__init__(channel)

channel is the ID of the channel to be hung up.

class ami.core.ListCommands

Bases: _Request

Provides a list of every command exposed by the Asterisk Management Interface, with synopsis, as a series of lines in the response’s ‘data’ attribute.

__init__()

action is the type of action being requested of the Asterisk server.

class ami.core.ListCategories(filename)

Bases: _Request

Provides a list of every category in an Asterisk configuration file, as a series of lines in the response’s ‘data’ attribute.

Requires config

__init__(filename)

filename is the name of the file, with extension, to be read.

class ami.core.LocalOptimizeAway(channel)

Bases: _Request

Allows a bridged channel to be optimised in Asterisk’s processing logic. This function should only be invoked after explicitly bridging.

Requires call

__init__(channel)

channel is the channel to be optimised.

class ami.core.Login(username, secret, events=True, challenge=None, authtype='MD5')

Bases: _Request

Authenticates to the AMI server.

__init__(username, secret, events=True, challenge=None, authtype='MD5')

username and secret are the credentials used to authenticate.

events may be set to False to prevent unsolicited events from being received. This is normally not desireable, so leaving it True is usually a good idea.

If given, challenge is a challenge string provided by Asterisk after sending a Challenge action, used with authtype to determine how to authenticate. authtype is ignored if the challenge parameter is unset.

class ami.core.Logoff

Bases: _Request

Logs out of the current manager session, permitting reauthentication.

__init__()

action is the type of action being requested of the Asterisk server.

class ami.core.ModuleLoad(load_type, module=None)

Bases: _Request

Loads, unloads, or reloads modules.

Requires system

__init__(load_type, module=None)

load_type is one of the following:

  • ‘load’

  • ‘unload’

  • ‘reload’: if module is undefined, all modules are reloaded

module is optionally the name of the module, with extension, or one of the following for a built-in subsystem:

  • ‘cdr’

  • ‘dnsmgr’

  • ‘enum’

  • ‘extconfig’

  • ‘http’

  • ‘manager’

  • ‘rtp’

class ami.core.Monitor(channel, filename, format='wav', mix=True)

Bases: _Request

Starts monitoring (recording) a channel.

Requires call

__init__(channel, filename, format='wav', mix=True)

channel is the channel to be affected and filename is the new target filename, without extension, as either an auto-resolved or absolute path.

format may be any format Asterisk understands, defaulting to FORMAT_WAV:

  • FORMAT_SLN

  • FORMAT_G723

  • FORMAT_G729

  • FORMAT_GSM

  • FORMAT_ALAW

  • FORMAT_ULAW

  • FORMAT_VOX

  • FORMAT_WAV: PCM16

mix, defaulting to True, muxes both audio streams associated with the channel after recording is complete, with the alternative leaving the two streams separate.

class ami.core.MuteAudio(channel, input=False, output=False, muted=False)

Bases: _Request

Starts or stops muting audio on a channel.

Either (or both) directions can be silenced.

Requires system

__init__(channel, input=False, output=False, muted=False)

channel is the channel to be affected and muted indicates whether audio is being turned on or off. input (from the channel) and output (to the channel) indicate the subchannels to be adjusted.

class ami.core.Originate_Application(channel, application, data=(), timeout=None, callerid=None, variables={}, account=None, async_=True)

Bases: _Originate

Initiates a call that answers, executes an arbitrary dialplan application, and hangs up.

Requires call

__init__(channel, application, data=(), timeout=None, callerid=None, variables={}, account=None, async_=True)

channel is the destination to be called, expressed as a fully qualified Asterisk channel, like “SIP/test-account@example.org”.

application is the name of the application to be executed, and data is optionally any parameters to pass to the application, as an ordered sequence (list or tuple) of strings, escaped as necessary (the ‘,’ character is special).

timeout, if given, is the number of milliseconds to wait before dropping an unanwsered call. If set, the request’s timeout value will be set to this number + 2 seconds, removing the need to set both variables. If not set, the request’s timeout value will be set to ten minutes.

callerid is an optinal string of the form “name”<number>, where ‘name’ is the name to be displayed (on supporting channels) and ‘number’ is the source identifier, typically a string of digits on most channels that may interact with the PSTN.

variables is an oprional dictionary of key-value variable pairs to be set as part of the channel’s namespace.

account is an optional account code to be associated with the channel, useful for tracking billing information.

async_ should always be True. If not, only one unanswered call can be active at a time.

class ami.core.Originate_Context(channel, context, extension, priority, timeout=None, callerid=None, variables={}, account=None, async_=True)

Bases: _Originate

Initiates a call with instructions derived from an arbitrary context/extension/priority.

Requires call

__init__(channel, context, extension, priority, timeout=None, callerid=None, variables={}, account=None, async_=True)

channel is the destination to be called, expressed as a fully qualified Asterisk channel, like “SIP/test-account@example.org”.

context, extension, and priority, must match a triple known to Asterisk internally. No validation is performed, so specifying an invalid target will terminate the call immediately.

timeout, if given, is the number of milliseconds to wait before dropping an unanwsered call. If set, the request’s timeout value will be set to this number + 2 seconds, removing the need to set both variables. If not set, the request’s timeout value will be set to ten minutes.

callerid is an optinal string of the form “name”<number>, where ‘name’ is the name to be displayed (on supporting channels) and ‘number’ is the source identifier, typically a string of digits on most channels that may interact with the PSTN.

variables is an oprional dictionary of key-value variable pairs to be set as part of the channel’s namespace.

account is an optional account code to be associated with the channel, useful for tracking billing information.

async_ should always be True. If not, only one unanswered call can be active at a time.

class ami.core.Park(channel, channel_callback, timeout=None)

Bases: _Request

Parks a call for later retrieval.

Requires call

__init__(channel, channel_callback, timeout=None)

channel is the channel to be parked and channel_callback is the channel to which parking information is announced.

If timeout, a number of milliseconds, is given, then channel_callback is given channel if the call was not previously retrieved.

class ami.core.ParkedCalls

Bases: _Request

Lists all parked calls.

Any number of ‘ParkedCall’ events may be generated in response to this request, followed by one ‘ParkedCallsComplete’.

__init__()

action is the type of action being requested of the Asterisk server.

class ami.core.PauseMonitor(channel)

Bases: _Request

Pauses the recording of a monitored channel. The channel must have previously been selected by the Monitor action.

Requires call

__init__(channel)

channel is the channel to be affected.

class ami.core.Ping

Bases: _Request

Pings the AMI server. The response value has a ‘RTT’ attribute, which is the number of seconds the trip took, as a floating-point number, or -1 in case of failure.

__init__()

action is the type of action being requested of the Asterisk server.

class ami.core.PlayDTMF(channel, digit)

Bases: _Request

Plays a DTMF tone on a channel.

Requires call

__init__(channel, digit)

channel is the channel to be affected, and digit is the tone to play.

class ami.core.QueueAdd(interface, queue, membername=None, penalty=0, paused=False)

Bases: _Request

Adds a member to a queue.

Upon success, a ‘QueueMemberAdded’ event will be generated.

Requires agent

__init__(interface, queue, membername=None, penalty=0, paused=False)

Adds the device identified by interface to the given queue.

membername optionally provides a friendly name for logging purposes, penalty establishes a priority structure (lower priorities first, defaulintg to 0) for call escalation, and paused optinally allows the interface to start in a disabled state.

class ami.core.QueueLog(queue, event, interface=None, uniqueid=None, message=None)

Bases: _Request

Adds an arbitrary record to the queue log.

Requires agent

__init__(queue, event, interface=None, uniqueid=None, message=None)

queue is the queue to which the event is to be attached.

interface optionally allows the event to be associated with a specific queue member.

uniqueid’s purpose is presently unknown.

message’s purpose is presently unknown.

class ami.core.QueuePause(interface, paused, queue=None)

Bases: _Request

Pauses or unpauses a member in one or all queues.

Upon success, a ‘QueueMemberPaused’ event will be generated for all affected queues.

Requires agent

__init__(interface, paused, queue=None)

interface is the device to be affected, and queue optionally limits the scope to a single queue. paused must be True or False, to control the action being taken.

class ami.core.QueuePenalty(interface, penalty, queue=None)

Bases: _Request

Changes the penalty value associated with a queue member, in one or all queues.

Requires agent

__init__(interface, penalty, queue=None)

Changes the penalty value associated with interface in all queues, unless queue is defined, limiting it to one.

class ami.core.QueueReload(queue=None, members='yes', rules='yes', parameters='yes')

Bases: _Request

Reloads properties from config files for one or all queues.

Requires agent

__init__(queue=None, members='yes', rules='yes', parameters='yes')

Reloads parameters for all queues, unless queue is defined, limiting it to one.

members is ‘yes’ (default) or ‘no’, indicating whether the member-list should be reloaded.

rules is ‘yes’ (default) or ‘no’, indicating whether the rule-list should be reloaded.

parameters is ‘yes’ (default) or ‘no’, indicating whether the parameter-list should be reloaded.

class ami.core.QueueRemove(interface, queue)

Bases: _Request

Removes a member from a queue.

Upon success, a ‘QueueMemberRemoved’ event will be generated.

Requires agent

__init__(interface, queue)

Removes the device identified by interface from the given queue.

class ami.core.QueueStatus(queue=None)

Bases: _Request

Describes the status of one (or all) queues.

Upon success, ‘QueueParams’, ‘QueueMember’, and ‘QueueEntry’ events will be generated, ending with ‘QueueStatusComplete’.

__init__(queue=None)

Describes all queues in the system, unless queue is given, which limits the scope to one.

class ami.core.QueueSummary(queue=None)

Bases: _Request

Describes the Summary of one (or all) queues.

Upon success, ‘QueueSummary’ event will be generated, ending with ‘QueueSummaryComplete’.

__init__(queue=None)

Describes all queues in the system, unless queue is given, which limits the scope to one.

class ami.core.Redirect(channel, context, extension, priority)

Bases: _Request

Redirects a call to an arbitrary context/extension/priority.

Requires call

__init__(channel, context, extension, priority)

channel is the destination to be redirected.

context, extension, and priority, must match a triple known to Asterisk internally. No validation is performed, so specifying an invalid target will terminate the call immediately.

class ami.core.Reload(module=None)

Bases: _Request

Reloads Asterisk’s configuration globally or for a specific module.

Requires call

__init__(module=None)

If given, module limits the scope of the reload to a specific module, named without extension.

class ami.core.SendText(channel, message)

Bases: _Request

Sends text along a supporting channel.

Requires call

__init__(channel, message)

channel is the channel along which to send message.

class ami.core.SetCDRUserField(channel, user_field)

Bases: _Request

Sets the user-field attribute for the CDR associated with a channel.

Requires call

__init__(channel, user_field)

channel is the channel to be affected, and user_field is the value to set.

class ami.core.Setvar(variable, value, channel=None)

Bases: _Request

Sets a channel-level or global variable.

Requires call

__init__(variable, value, channel=None)

value is the value to be set under variable.

channel is the channel to be affected, or None, the default, if the variable is global.

class ami.core.SIPnotify(channel, headers={})

Bases: _Request

Sends a SIP NOTIFY to the remote party on a channel.

Requires call

__init__(channel, headers={})

channel is the channel along which to send the NOTIFY.

headers is a dictionary of key-value pairs to be inserted as SIP headers.

class ami.core.SIPpeers

Bases: _Request

Lists all SIP peers.

Any number of ‘PeerEntry’ events may be generated in response to this request, followed by one ‘PeerlistComplete’.

Requires system

__init__()

action is the type of action being requested of the Asterisk server.

class ami.core.SIPqualify(peer)

Bases: _Request

Sends a SIP OPTIONS to the specified peer, mostly to ensure its presence.

Some events are likely raised by this, but they’re unknown at the moment.

Requires system

__init__(peer)

peer is the peer to ping.

class ami.core.SIPshowpeer(peer)

Bases: _Request

Provides detailed information about a SIP peer.

The response has the following key-value pairs:

  • ‘ACL’: True or False

  • ‘Address-IP’: The IP of the peer

  • ‘Address-Port’: The port of the peer, as an integer

  • ‘AMAflags’: “Unknown”

  • ‘Callgroup’: ?

  • ‘Callerid’: “Linksys #2” <555>

  • ‘Call-limit’: ?

  • ‘Channeltype’: “SIP”

  • ‘ChanObjectType’: “peer”

  • ‘CID-CallingPres’: ?

  • ‘Context’: The context associated with the peer

  • ‘CodecOrder’: The order in which codecs are tried

  • ‘Codecs’: A list of supported codecs

  • ‘Default-addr-IP’: ?

  • ‘Default-addr-port’: ?

  • ‘Default-Username’: ?

  • ‘Dynamic’: True or False, depending on whether the peer is resolved by static IP or authentication

  • ‘Language’: The language preference (may be empty) of this peer

  • ‘LastMsgsSent’: ?

  • ‘MaxCallBR’: The maximum bitrate in kbps supported by the peer, as an integer

  • ‘MD5SecretExist’: True or False, depending on whether an MD5 secret is defined

  • ‘ObjectName’: The internal name of the peer

  • ‘Pickupgroup’: ?

  • ‘Reg-Contact’: The registration contact address for this peer

  • ‘RegExpire’: Time in seconds until SIP registration expires, as an integer

  • ‘RegExtension’: ?

  • ‘SecretExist’: True or False, depending on whether a secret is defined.

  • ‘SIP-AuthInsecure’: True or False

  • ‘SIP-CanReinvite’: True or False, depending on whether the peer supports REINVITE

  • ‘SIP-DTMFmode’: The DTMF transport mode to use with this peer, “rfc2833” or ?

  • ‘SIP-NatSupport’: The NATting workarounds supported by this peer, “RFC3581” or ?

  • ‘SIP-PromiscRedir’: True or False, depending on whether this peer is allowed to arbitrarily redirect calls

  • ‘SIP-Useragent’: The User-Agent of the peer

  • ‘SIP-UserPhone’: True or False, (presumably) depending on whether this peer is a terminal device

  • ‘SIP-VideoSupport’: True or False

  • ‘SIPLastMsg’: ?

  • ‘Status’: ‘Unmonitored’, ‘OK (d+ ms)’

  • ‘ToHost’: ?

  • ‘TransferMode’: “open”

  • ‘VoiceMailbox’: The mailbox associated with the peer; may be null

Requires system

__init__(peer)

peer is the identifier of the peer for which information is to be retrieved.

class ami.core.SIPshowregistry

Bases: _Request

Lists all SIP registrations.

Any number of ‘RegistryEntry’ events may be generated in response to this request, followed by one ‘RegistrationsComplete’.

Requires system

__init__()

action is the type of action being requested of the Asterisk server.

class ami.core.Status(channel)

Bases: _Request

Lists the status of an active channel.

Zero or one ‘Status’ events are generated, followed by a ‘StatusComplete’ event.

Requires call

__init__(channel)

channel is the channel for which status information is to be retrieved.

class ami.core.StopMonitor(channel)

Bases: _Request

Stops recording a monitored channel. The channel must have previously been selected by the Monitor action.

Requires call

__init__(channel)

channel is the channel to be affected.

class ami.core.UnpauseMonitor(channel)

Bases: _Request

Unpauses recording on a monitored channel. The channel must have previously been selected by the Monitor action.

Requires call

__init__(channel)

channel is the channel to be affected.

class ami.core.UpdateConfig(src_filename, dst_filename, changes, reload=True)

Bases: _Request

Updates any number of values in an Asterisk configuration file.

Requires config

__init__(src_filename, dst_filename, changes, reload=True)

Reads from src_filename, performing all changes, and writing to dst_filename.

If reload is True, the changes take effect immediately. If reload is the name of a module, that module is reloaded.

changes may be any iterable object countaining quintuples with the following items:

  1. One of the following:

  • ‘NewCat’: creates a new category

  • ‘RenameCat’: renames a category

  • ‘DelCat’: deletes a category

  • ‘Update’: changes a value

  • ‘Delete’: removes a value

  • ‘Append’: adds a value

  1. The name of the category to operate on

  2. None or the name of the variable to operate on

  3. None or the value to be set/added (has no effect with ‘Delete’)

  4. None or a string that needs to be matched in the line to serve as a qualifier

class ami.core.UserEvent(**kwargs)

Bases: _Request

Causes a ‘UserEvent’ event to be generated.

Requires user

__init__(**kwargs)

Any keyword-arguments passed will be present in the generated event, making this usable as a crude form of message-passing between AMI clients.

class ami.core.VoicemailUsersList

Bases: _Request

Lists all voicemail information.

Any number of ‘VoicemailUserEntry’ events may be generated in response to this request, followed by one ‘VoicemailUserEntryComplete’.

Requires system (probably)

__init__()

action is the type of action being requested of the Asterisk server.

Exceptions

exception ami.core.ManagerAuthError

Bases: ManagerError

Indicates that a problem occurred while authenticating