Administration

  • UCX Applications
UCX API’s

Overview

UCX currently provides two application programming interfaces (APIs): Asterisk Gateway Interface (AGI) and Asterisk Manager Interface (AMI).

These interfaces serve different purposes:

  • AGI provides an interface between the UCX dialplan and an external program that wants to manipulate a channel in the dialplan. In general, the interface is synchronous – actions taken on a channel from an AGI block and do not return until the action is completed. AGI requires some modification to the dialplan to run and is good for processing inbound calls.
  • AMI provides a mechanism to control where channels execute in the dialplan. Unlike AGI, AMI is an asynchronous, event driven interface. For the most part, AMI does not provide mechanisms to control channel execution – rather, it provides information about the state of the channels and controls about where the channels are executing. It allows remote software to completely control the UCX: get event status updates, make calls, receive calls, route calls, etc.

Both of these interfaces are powerful and opened up a wide range of integration possibilities. Using AGI, remote dialplan execution could be enabled, which allows developers to integrate UCX with PHP, Python, Java, and other applications. Using AMI, the state of UCX could be displayed, calls initiated, and the location of channels controlled. Using both APIs together, complex applications integrated with UCX could be developed.

From release 6.0 onwards, UCX will provide another interface:  Asterisk RESTful Interface (ARI).

ARI is an asynchronous API that allows developers to build communications applications by exposing the raw primitive objects in UCX – channels, bridges, endpoints, media, etc. – through an intuitive REST interface. The state of the objects being controlled by the user are conveyed via JSON events over a WebSocket.

ARI consists of three different pieces that are – for all intents and purposes – interrelated and used together. They are:

  1. A RESTful interface that a client uses to control resources in UCX.
  2. A WebSocket that conveys events in JSON about the resources in UCX to the client.
  3. The Stasis dialplan application that hands over control of a channel from UCX to the client.

All three pieces work together, allowing a developer to manipulate and control the fundamental resources in UCX and build their own communications application.

Asterisk Manager Interface (AMI)

The Asterisk Manager Interface (AMI) is a monitoring and management interface over TCP. With the manager interface, you can control the UCX to: originate calls, check mailbox status, monitor channels, queues and also execute commands.

Protocol Overview

The protocol has the following characteristics:

  1. By default, AMI is available on TCP port 5038.
  2. AMI is a plain text protocol and AMI messages (regardless of message type) are encoded in the same way.
  3. Management communication consists of tags of the form “HEADER: VALUE“, terminated with <CR><LF>.
  4. The end of message is indicated by a blank line (i.e. two <CR>/<LF> in a row).
  5. Before issuing commands to UCX, you must establish a manager session, i.e. login and authenticate as a user. See Asterisk API page on how to create a manager user.
  6. When a message is sent from client to UCX, the first line of the message should have the “Action” header.
  7. When a message is sent from UCX to the client, the first line of the message will have either “Event” or “Response” header.
  8. The order of lines within a message is insignificant.

<CR><LF>
Header1: This is the first value<CR><LF>
Header2: This is the second value<CR><LF>
Header3: This is the last value of this message<CR><LF>
<CR><LF>

NOTE

  • Configuration of the AMI Manager is done through the UCX web interface.
  • To send messages to AMI Manager, use a TCP connection to port 5038. For testing, use a telnet client and send messages manually. In general, use an application that can establish a TCP connection with the UCX server and then use the AMI protocol to do whatever is needed.
  • Messages to AMI Manager should start with <RETURN> and end with <RETURN> <RETURN>. Refer to examples later on in this article.

    • Some Standard AMI Headers

    • Account: – Account Code (Status)
    • AccountCode: – Account Code (cdr_manager)
    • ACL: <Y | N> – Does ACL exist for object ?
    • Action: <action> – Request or notification of a particular action
    • Address-IP: – IPaddress
    • Address-Port: – IP port number
    • Agent: <string> – Agent name
    • AMAflags: – AMA flag (cdr_manager, sippeers)
    • AnswerTime: – Time of answer (cdr_manager)
    • Append: <bool> – CDR userfield Append flag
    • Application: – Application to use
    • Async: – Whether or not to use fast setup
    • AuthType: – Authentication type (for login or challenge) “md5”
    • BillableSeconds: – Billable seconds for call (cdr_manager)
    • CallerID: – Caller id (name and number in Originate & cdr_manager)
    • CallerID: – CallerID number Number or “<unknown>” or “unknown” (should change to “<unknown>” in app_queue)
    • CallerID1: – Channel 1 CallerID (Link event)
    • CallerID2: – Channel 2 CallerID (Link event)
    • CallerIDName: – CallerID name Name or “<unknown>” or “unknown” (should change to “<unknown>” in app_queue)
    • Callgroup: – Call group for peer/user
    • CallsTaken: <num> – Queue status variable
    • Cause: <value> – Event change cause – “Expired”
    • Cause: <value> – Hangupcause (channel.c)
    • CID-CallingPres: – Caller ID calling presentation
    • Channel: <channel> – Channel specifier
    • Channel: <dialstring> – Dialstring in Originate
    • Channel: <tech/[peer/username]> – Channel in Registry events (SIP, IAX2)
    • Channel: <tech> – Technology (SIP/IAX2 etc) in Registry events
    • ChannelType: – Tech: SIP, IAX2, DAHDI, MGCP etc
    • Channel1: – Link channel 1
    • Channel2: – Link channel 2
    • ChanObjectType: – “peer”, “user”
    • Codecs: – Codec list
    • CodecOrder: – Codec order, separated with comma “,”
    • Command: – Cli command to run
    • Context: – Context
    • Count: <num> – Number of callers in queue
    • Data: – Application data
    • Default-addr-IP: – IP address to use before registration
    • Default-Username: – Username part of URI to use before registration
    • Destination: – Destination for call (Dialstring ) (dial, cdr_manager)
    • DestinationContext: – Destination context (cdr_manager)
    • DestinationChannel: – Destination channel (cdr_manager)
    • DestUniqueID: – UniqueID of destination (dial event)
    • Direction: <type> – Audio to mute (read | write | both)
    • Disposition: – Call disposition (CDR manager)
    • Domain: <domain> – DNS domain
    • Duration: <secs> – Duration of call (cdr_manager)
    • Dynamic: <Y | N> – Device registration supported?
    • Endtime: – End time stamp of call (cdr_manager)
    • EventList: <flag> – Flag being “Start”, “End”, “Cancelled” or “ListObject”
    • Events: <eventmask> – Eventmask filter (“on”, “off”, “system”, “call”, “log”)
    • Exten: – Extension (Redirect command)
    • Extension: – Extension (Status)
    • Family: <string> – ASTdb key family
    • File: <filename> – Filename (monitor)
    • Format: <format> – Format of sound file (monitor)
    • From: <time> – Parking time (ParkedCall event)
    • Hint: – Extension hint
    • Incominglimit: – SIP Peer incoming limit
    • Key: Key: – ASTdb Database key
    • LastApplication: – Last application executed (cdr_manager)
    • LastCall: <num> – Last call in queue
    • LastData: – Data for last application (cdr_manager)
    • Link: – (Status)
    • ListItems: <number> – Number of items in Eventlist (Optionally sent in “end” packet)
    • Location: – Interface (whatever that is -maybe tech/name in app_queue )
    • Loginchan: – Login channel for agent
    • Logintime: <number> – Login time for agent
    • Mailbox: – VM Mailbox (id@vmcontext) (mailboxstatus, mailboxcount)
    • MD5SecretExist: <Y | N> – Whether secret exists in MD5 format
    • Membership: <string> – “Dynamic” or “static” member in queue
    • Message: <text> – Text message in ACKs, errors (explanation)
    • Mix: <bool> – Boolean parameter (monitor)
    • MOHSuggest: – Suggested music on hold class for peer (mohsuggest)
    • NewMessages: <count> – Count of new Mailbox messages (mailboxcount)
    • Newname:
    • ObjectName: – Name of object in list
    • OldName: – Something in Rename (channel.c)
    • OldMessages: <count> – Count of old mailbox messages (mailboxcount)
    • Outgoinglimit: – SIP Peer outgoing limit
    • Paused: <num> – Queue member paused status
    • Peer: <tech/name> – “channel” specifier
    • PeerStatus: <tech/name> – Peer status code “Unregistered”, “Registered”, “Lagged”, “Reachable”
    • Penalty: <num> – Queue penalty
    • Priority: – Extension priority
    • Privilege: <privilege> – AMI authorization class (system, call, log, verbose, command, agent, user)
    • Pickupgroup: – Pickup group for peer
    • Position: <num> – Position in Queue
    • Queue: – Queue name
    • Reason: – “Autologoff”
    • Reason: – “Chanunavail”
    • Response: <response> – response code, like “200 OK” “Success”, “Error”, “Follows”
    • Restart: – “True”, “False”
    • RegExpire: – SIP registry expire
    • RegExpiry: – SIP registry expiry
    • Reason: – Originate reason code
    • Seconds: – Seconds (Status)
    • Secret: <password> – Authentication secret (for login)
    • SecretExist: <Y | N> – Whether secret exists
    • Shutdown: – “Uncleanly”, “Cleanly”
    • SIP-AuthInsecure:
    • SIP-FromDomain: – Peer FromDomain
    • SIP-FromUser: – Peer FromUser
    • SIP-NatSupport:
    • SIPLastMsg:
    • Source: – Source of call (dial event, cdr_manager)
    • SrcUniqueID: – UniqueID of source (dial event)
    • StartTime: – Start time of call (cdr_manager)
    • State: – Channel state
    • State: <1 | 0> – Mute flag
    • Status: – Registration status (Registry events SIP)
    • Status: – Extension status (Extensionstate)
    • Status: – Peer status (if monitored) ** Will change name ** “unknown”, “lagged”, “ok”
    • Status: <num> – Queue Status
    • Status: – DND status (DNDState)
    • Time: <sec> – Roundtrip time (latency)
    • Timeout: – Parking timeout time
    • Timeout: – Timeout for call setup (Originate)
    • Timeout: <seconds> – Timeout for call
    • Uniqueid: – Channel Unique ID
    • Uniqueid1: – Channel 1 Unique ID (Link event)
    • Uniqueid2: – Channel 2 Unique ID (Link event)
    • User: – Username (SIP registry)
    • UserField: – CDR userfield (cdr_manager)
    • Val: – Value to set/read in ASTdb
    • Variable: – Variable AND value to set (multiple separated with | in Originate)
    • Variable: <name> – For channel variables
    • Value: <value> – Value to set
    • VoiceMailbox: – VM Mailbox in SIPpeers
    • Waiting: – Count of mailbox messages (mailboxstatus)

    Message Types

    There are 3 types of messages on the AMI:

    • Actions: Only the client can generate Actions and only one Action may be outstanding at any time.
    • Responses: Actions have at least one Response, indicating the result of the executed (or requested) action.
    • Events: There are two kind of events. The ones attached to a particular response for a particular action, and the ones that asterisk generate to inform the connected client about things that are happening in the server (like call events, changes in variables values, agents and other clients that connect/disconnect to/from the server, etc).

    Manager events

    Manager events are one-way messages sent from UCx to AMI clients to report something that has occurred on the system. When connected to the native TCP interface for the AMI, manager events are delivered asynchronously.

    For details on events, see Asterisk 11 AMI Events.

    • AgentCalled
    • AgentCompletePage
    • AgentConnectPage
    • AgentDumpPage
    • Agentlogin
    • Agentlogoff
    • AgentRingNoAnswer
    • Alarm
    • AlarmClearP
    • Bridge
    • BridgeAction
    • BridgeExec
    • ChanSpyStart
    • ChanSpyStop
    • ConfbridgeEnd
    • ConfbridgeJoin
    • ConfbridgeLeave
    • ConfbridgeStartP
    • ConfbridgeTalking
    • DAHDIChannelP
    • DialP
    • DNDState
    • DTMF
    • ExtensionStatus
    • FullyBootedPa
    • Hangup
    • HangupHandlerPop
    • HangupHandlerPush
    • HangupHandlerRun
    • HangupRequest
    • Hold
    • Join
    • Leave
    • LocalBridge
    • LogChannel
    • Masquerade
    • MeetmeEnd
    • MeetmeJoin
    • MeetmeLeave
    • MeetmeMute
    • MeetmeTalking
    • MeetmeTalkRequestP
    • MessageWaiting
    • ModuleLoadReport
    • NewAccountCode
    • NewCallerid
    • Newchannel
    • Newexten
    • NewPeerAccount
    • Newstate
    • OriginateResponse
    • ParkedCall
    • ParkedCallGiveUp
    • ParkedCallTimeOut
    • Pickup
    • PresenceStatus
    • QueueCallerAbandon
    • QueueMemberAddedP
    • QueueMemberPaused
    • QueueMemberPenalty
    • QueueMemberRemoved
    • QueueMemberRinginuse
    • QueueMemberStatus
    • Rename
    • Shutdown
    • SoftHangupRequest
    • SpanAlarm
    • SpanAlarmClearP
    • UnParkedCallP
    • UserEvent
    • VarSet

    Manager actions

    Manager actions are requests from a client that have associated responses that come back from UCx. That is, a manager action may be a request that UCx perform some action and return the result. For example, you can have an AMI action to originate a call or an AMI action requesting for data. For details on the actions, see Asterisk 11 AMI Actions.

    To view a list of manager actions, navigate to PBX > Tools > Asterisk CLI and enter the command: manager show commands.
    You can get more information about a manager command with: manager show command <commandname> .



    Examples

    Login – log a user into the manager interface.

    <RETURN>
    ACTION: Login <RETURN>
    USERNAME: username <RETURN>
    SECRET: password <RETURN>
    <RETURN>

    Originate – originate a call from a channel to an extension.

    <RETURN>
    ACTION: Originate <RETURN>
    CHANNEL: sip/12345 <RETURN>
    EXTEN: 1234 <RETURN>
    CONTEXT: default <RETURN>
    <RETURN>

    MailboxCount – query the number of messages in a mailbox

    <RETURN>
    ACTION: MailboxCount <RETURN>
    MAILBOX: 1234@default <RETURN>
    ACTIONID: 1 <RETURN>
    <RETURN>

    Print Friendly, PDF & Email

    Contents