
Proxy Server Communication Documentation

Communication Overview:
  Although the proxy does extend the functionality provided by the Asterisk Manager Interface, care was taken
to try to keep syntax and symantics as close as possible, or at the very least, within the spirit/style of
asterisk.

  A client can at any time send a communication using either XML or Asterisk Native format. The server
will respond by using the communication format preference set at registration time, or if not set, the
server default.
  All text sent to the server is case insensitive, except for specific obvious exceptions such as passwords.
  
General Errors:
  
  General Unknown Error:
  In XML <command action="Unknown" Response="Error">Error Message</command>
    and
  Action: Unkown
  Response: Error
  Message: Error Message
  

Logging In:
  In XML log in would look like this:
  
  cmd: <command action="register" user="username" secret="secret" 
                type="monitor|agent|administrator" format="xml|asterisk" />

  The "format" option is optional, and will default to the server default if not set.
  Two responses are possible:

  <command action="login" response="Success" Message="Authentication accepted" />
    for a successful registration or
  <command action="login" response="Error" Message="Error Message describing why login was not successful" />
    for an unsuccessful one.

  In Asterisk Native format a login would look like this:

  Action: login
  User: <username>
  Secret: <password>
  Type: <Monitor|Agent|Administrator>
  Format: <XML|Asterisk>
  
  The two responses would look like this:

  Action: Login
  Response: Success
  Message: Authentication accepted
       or
  Action: Login
  Response: Error
  Message: Error message describing why login was not successful

-----------------------------------
For the response to any given command, telnet to the ampd proxy, login, and execute the command. Nearly all
commands are direct implementations of the actual Asterisk commands, which can be referenced by executing a
'show manager commands' for a full list, and 'show manager command <command>' for a description of the command
on the Asterisk CLI.

The list of ampd commands and arguments are as follows:
  
List Of Server Commands:
------------------------
AbsoluteTimeout       
  Channel <required>
  Timeout <required>

  Description: Set a absolute timeout on a channel. By absolute, we mean a strict time. a 30 second 
               timeout would be time() + 30;

AgentActivity
  Agent <required>
  
  Description: Shows the activity of an agent. Activities include pause/unpause, login and logout.

AgentCallbackLogin
  Agent <required>
  Exten <required>
  Context <required>
  ackCall
  WrapUpTime

  Description: Logs in an Agent. [NOTE: This function is DEPRECATED as of asterisk 1.4!! You should be using DYNAMIC AGENTS.]

AgentInfo
  Agent <optional>

  Description: Lists all agents, their status and login time (if applicable).

AgentLogoff           Agent, SoftHangUp

  Description: Logs an agent off. [DEPRECATED]

ChannelInfo

  Description: Lists all active channels.

Command
  Command <required>
  
  Description: Executes an arbitraty command as if you were on the Asterisk CLI.

Custom
  CAction <required>
  AsManyOptionsAsYouNeed <optional>
  
  Description: [[ADVANCED]] For people no like/need to build custom modules for asterisk, this allows you to execute those actions through
               the asterisk manager interface without the need to hack AMPD. Use action="custom" to trigger it, and the CAction will be
               automatically changed within AMPD to "Action" when sent to the server. You can also supply as many name: key values as you
               need. The 'custom' command EXPECTS the results of the module to output in asterisk native format (i.e. Name: value), if you
               need a more free-form result output, use CustomFreeForm.

CustomFreeForm
  CAction <required>
  AsManyOptionsAsYouNeed <optional>
  
  Description: [[ADVANCED]] Works exactly like 'custom', except that it treats the output exactly as if you ran the 'command' function, meaning
               it expects an arbitrary string ending with '--END COMMAND--'.

DBDel
  Family <required>
  Key <required>

  Description: Delete a key in the Asterisk internal database.

DBDeltree
  Family <required>
  Key

  Description: Delete a family[/key] and everything under it in the Asterisk internal database.

DBGet
  Family <required>
  Key

  Description: Retrieve a value from the Asterisk internal database.
  
DBPut
  Family <required>
  Key <required>
  Val <required>

  Description: Insert a key => value in the Asterisk internal database.

DBShow

  Description: List the contents of the Asterisk internal database.

ExtensionState
  Exten <required>
  Context <required>

  Description: Checks the status of a device connected to the extension.

Getvar
  Variable <required>
  Channel

  Description: Retrieves the value of a variable. If no channel is specified, it retreives a global variable.

Hangup
  Channel <required>

  Description: Hangs up a given channel rudely.

Login
  username <required>
  secret <required if trust is off>
  format
  type <required>
  agentid <required if type is 'agent'>
  isFlash

  Description: Logs a client in to the proxy server. Format is either XML or Asterisk if specified. isFlash is
               a quick hack for Macromedia flash clients who require a NULL character (or 0 byte) to be sent
               on the wire.

MailboxCount  (untested)
  Mailbox <required>
  Context <required>
  
  Description: Checks a mailbox for new messages.

MailboxStatus
  Mailbox <required>
  Context <required>
  
  Description: Checks a mailbox for status.

Monitor
  Channel <required>
  File
  Format
  Combine
  
  Description: Starts monitoring a given channel.

ChangeMonitor
  Channel <required>
  File <required>
  
  Description: Changes the monitored channel to the filename specified.

StopMonitor
  Channel <required>
  
  Description: Stops monitoring on the given channel.

Originate
  Channel <required>
  Context
  Exten
  Priority
  Application
  Data
  Timeout
  CallerID
  Account
  Async
  Variable
  
  Description: Originate is a bit of a monster. Refer to the asterisk documenation to figure out how it works. Here's a
               breif intro: You can specify either context, exten and priority, OR use the application and data
               to originate a call. Play around with it, you won't hurt much ;)

ParkedCallInfo (untested)
  
  Description: Lists all parked calls.

PeerInfo
  Type <optional> (SIP|IAX2)
  Peer <optional>
  Description: Get a (simplistic) list of peers configured in the asterisk machine. This is mostly here due to the
               SIPpeers command NOT giving Caller ID along with the rest of the info.
               Currently IAX peers are NOT suppored due to improper formatting in the results of the IAXpeers command.

ProfileDelete
  For use by the Asterisk Manager Administrator.

ProfileGet
  For use by the Asterisk Manager Administrator.
  
ProfileList
  For use by the Asterisk Manager Administrator.

ProfileUpdate
  For use by the Asterisk Manager Administrator.

QueueAdd
  Queue <required>
  Interface <required>
  
  Description: Add a 'member' or agent to a queue.

QueueInfo
  Queue <optional>

  Description: List information about all queues.

QueuePause
  Queue <required>
  Interface <required>
  Paused
  
  Description: Pause or Unpause a 'member' or agent in a queue. If pause is NOT specified, it is assumed to be
               ON or TRUE.

QueueRemove
  Queue <required>
  Interface <required>
  
  Description: Remove a 'member' or agent from a queue.

Redirect
  Channel <required>
  Context <required>
  Exten <required>
  Priority <required>
  ExtraChannel
  
  Description: Rudely redirect a channel elsewhere in the dial plan.

Setvar
  Variable <required>
  Value
  Channel
  
  Description: Set a variable. If channel is not set the variable is set globally. If value is not set the
               variable is set to an empty string.

SIPshowpeer
  Peer <required>
  
  Description: Retrieve information about a SIP peer.

ServerVersion

  Description: Retrieve the asterisk server version.

StatisticInfo
  Type
  Queue
  Agent
  
  Description: List current statistics from the proxy server. Type can be either "Queue" or "Agent" if
               specified. If Queue or Agent is specified, it will list statistics on only that queue or agent.

