Yeastar S-Series VoIP PBX Developer Guide

Introduction

The Asterisk Manager Interface (AMI) is a system monitoring and management interface provided by Asterisk. It allows live monitoring of events that occur in the system, as well enabling you to request that Asterisk performs some action.

Yeastar S-Series VoIP PBX supports AMI and the default port is 5038 (TCP).

 

Protocol Behavior

The protocol has the following characteristics:

  • Before issuing commands to Asterisk, you must establish a manager session.
  • Packets may be transmitted in either direction at any time after authentication.
  • The first line of a packet will have a key of "Action" when sent from the client to Asterisk, but "Event" or "Response" when sent from Asterisk to the client.
  • The order of lines within a packet is insignificant, so you may use your favorite programming language's native unordered dictionary type to efficiently store a single packet.
  • CR/LF is used to delimit each line and a blank line (two CR/LF in a row) indicates the end of the command which Asterisk is now expected to process.

More information about Asterisk Manager Interface.

 

Logging in Yeastar S-Series VoIP PBX

Enabling AMI on S-Series VoIP PBX

Before logging in S-Series  VoIP PBX via AMI, You need to enable AMI feature on S-Series VoIP PBX Web interface first.

1. Go to “Settings->Security->Service” page, enable AMI.
2. Specify the AMI username and password.
3. Add permitted IP range to access AMI.
4. Click “Save” and “Apply”.

Logging in S-Series AMI


In order to access the Asterisk Manager functionality, a user needs to establish a session by opening a TCP/IP connection to the listening port (usually 5038) of the Asterisk instance and logging into the manager using the 'Login' action.

In this example, S-Series VoIP PBX‘s IP address is 192.168.9.174. We use putty software to log in S-Series VoIP PBX AMI.
Download Putty Here

1. Launch putty software.
2. Enter S-Series VoIP PBX’s IP address, AMI port and choose Raw input the IP address, port, and choose Connection Type to ‘Raw’.

3. Click “Open”, you will see the figure shows as below.

4. Enter the following commands. The username and secret are AMI username and password that we set on S-Series IPPBX web.
Action: Login
Username: admin
Secret: password

5. Press “Enter” key twice to connect to S-Series IPPBX. 

6. S-Series IPPBX will respond with the following command:
Response: Success
Message: Authentication accepted

 

AMI Actions and Events

Note:
The sequence in the response event doesn't send a carriage return - line feed (\r\n), it only sends a line-feed (\n), if you write a handler who wait for a carriage return - line feed, the result sequence is ignored and send the respond that you mention.

Example:
Response: Follows\r\n
Channel Location State Application(Data)\n
PJSIP/x7065551212b-1af (None) Ringing AppDial((Outgoing Line))\n
PJSIP/x7065551212c-2aa 29@default:2 Ring Dial(PJSIP/x7065551212b)\n
2 active channels\n
1 active call\r\n
--END COMMAND--\r\n
\r\n

Establishing a New Call


You can originate a new call through the terminal side using command ‘originate’, and there are some differences between SIP extension and analog extension.

Below are the commands to originate a call from extension 1000 to 1001.

Action: originate
Context: DLPN_DialPlan1000 //Context: DLPN_DialPlan is the fixed prefix of each
                                          extension’s dial plan.//
Channel: PJSIP/1000         // The channel to dial this call, for SIP extensions, the format must be                                                     PJSIP/extension. For analog phone, the value must be DAHDI/analog port                                             number, you can get the port number in ‘PBX Monitor’ of S-Series IPPBX’s                                             web interface.//
Exten: 1001                    // Exten is the number you want to dial.//
Priority: 1                     // Fixed priority to dial.//
Timeout: 30000             // The time out value, for example 30000ms.//
CallerID: 1000              // Caller id number displayed at 1000 side before dial out//
ActionID: 1                  // It’s a signature used to identify the request and response between terminal and                                     server.//

Below is another example for you to dial from extension 1002(analog phone) to number 1003.

Action: originate
Context: DLPN_DialPlan1002
Channel: DAHDI/5
Exten: 1003
Priority: 1
Timeout: 30000
CallerID: 1002
ActionID: 1

Judging the Status of a Call


A NewChannel is triggered when a new channel is created, an Event:Cdr log will be generated if the call ends. The Uniqueid is the same in a new channel.

Event: Newchannel
Privilege: call,all
Channel: PJSIP/1000-00000003
ChannelState: 0
ChannelStateDesc: Down
CallerIDNum: 1000
CallerIDName: 1000
ConnectedLineNum: <unknown>
ConnectedLineName: <unknown>
Language: en
AccountCode:
Context: DLPN_DialPlan1000
Exten: s
Priority: 1
Uniqueid: 1480401231.4
Linkedid: 1480401231.4

Event: Cdr
Privilege: cdr,all
AccountCode:
Source: 1000
Destination: 1001
DestinationContext: DLPN_DialPlan1000
CallerID: "1000" <1000>
Channel: PJSIP/1000-00000003
DestinationChannel: PJSIP/1001-00000004
LastApplication: Dial
LastData: PJSIP/1001,30,tTKkWwXxg,,1
StartTime: 2016-11-28 22:33:56
AnswerTime: 2016-11-28 22:33:56
EndTime: 2016-11-28 22:34:11
Duration: 14
BillableSeconds: 14
Disposition: ANSWERED
AMAFlags: DOCUMENTATION
UniqueID: 1480401231.4
UserField:

Detecting Incoming Call’s Caller ID


When the S-Series IPPBX responds with an “Event:DialBegin”, we can find the destination number from Header “DestChannel”, and find the incoming call’s caller ID from the Header “CallerIDNum”.

There are multiply types in destination Header:

  • PJSIP/474-000079de
    The destination number is 474.
  • IAX2/306-0000801a
    The destination number is 306.
  • DAHDI/65-0000801c
    The destination number is analog port 65.
    Execute the following command to check the analog port:
    Action: Command
    command: core show channel 65
  • SIP/trunk-test1/1112233-0000802c
    It means dialing out via SIP register trunk “test1”.
  •  IAX2/trunk-test2/1112233-0000802c
    It means dialing out via IAX trunk “test2”.
  • SIP/trunk-sps-test3/111222-0000802c
    It means dialing out via SIP peer trunk “sps-test3”.

The following example shows a call comes from 1000 to a PJSIP extension 1001.

Event: DialBegin
Privilege: call,all
Channel: PJSIP/1000-00000003
ChannelState: 6
ChannelStateDesc: Up
CallerIDNum: 1000
CallerIDName: 1000
ConnectedLineNum: 1000
ConnectedLineName: <unknown>
Language: en
AccountCode:
Context: macro-realstexten
Exten: s
Priority: 9
Uniqueid: 1480401231.4
Linkedid: 1480401231.4
DestChannel: PJSIP/1001-00000004
DestChannelState: 0
DestChannelStateDesc: Down
DestCallerIDNum: 1001
DestCallerIDName: 1001
DestConnectedLineNum: 1000
DestConnectedLineName: 1000
DestLanguage: en
DestAccountCode:
DestContext: DLPN_DialPlan1001
DestExten: 1001
DestPriority: 1
DestUniqueid: 1480401236.5
DestLinkedid: 1480401231.4
DialString: 1001/sip:1001@192.168.9.11:64292;rinstance=ebcb18cbc5ef1744

Transferring a Call


Use command ‘redirect’ to transfer calls. The following example shows how to transfer a call.

1. Extension 1000 calls to extension 1001.
Event: DialBegin
Privilege: call,all
Channel: PJSIP/1000-00000008
ChannelState: 4
ChannelStateDesc: Ring
CallerIDNum: 1000
CallerIDName: 1000
ConnectedLineNum: <unknown>
ConnectedLineName: <unknown>
Language: en
AccountCode:
Context: macro-realstexten
Exten: s
Priority: 9
Uniqueid: 1480404007.15
Linkedid: 1480404007.15
DestChannel: PJSIP/1001-00000009
DestChannelState: 0
DestChannelStateDesc: Down
DestCallerIDNum: 1001
DestCallerIDName: 1001
DestConnectedLineNum: 1000
DestConnectedLineName: 1000
DestLanguage: en
DestAccountCode:
DestContext: DLPN_DialPlan1001
DestExten: 1001
DestPriority: 1
DestUniqueid: 1480404007.16
DestLinkedid: 1480404007.15
DialString: 1001/sip:1001@192.168.9.11:64292;rinstance=ebcb18cbc5ef1744

2. Extension 1001 does not answer the call, the call will be transferred to extension 1002.

Action: redirect
ActionID:
Channel: PJSIP/1000-00000008
Context: DLPN_DialPlan1001
Exten: 1002
Priority: 1

Appendix A:AMI Common Commands

Action

Description

Option

Example and Response()

Remark

Command

Used to send commands in asterisk CLI

Command: command string

Action: Command

ActionID: #10001

command: core show version

 

Response: Follows

Privilege: Command

ActionID: #10001

Asterisk 13.7.0 built by root @ kyo6057 on a i686 running Linux on 2016-10-29 02:36:01 UTC

--END COMMAND--

ActionID can be any value.

Before executing the command, we recommend to get the whole commands by the command ‘core show help’ in asterisk CLI through SSH.

Events

Used to control the event string sent by S-Series PBX

EventMask: on ; send Events

EventMask: off   ;

Stop sending

Action: events

EventMask: off

 

Response: Success

Events: Off

 

Action: events

EventMask: on

 

Response: Success

Events: On

ExtensionState

Used to check extension’s status

Exten: extension number

Context: default

ActionID: optional

Action: ExtensionState

Context: default

Exten: 1000

ActionID: #10002

 

Response: Success

ActionID: #10002

Message: Extension Status

Exten: 1000

Context: default

Hint: PJSIP/1000

Status: 0

StatusText: Idle

Status codes:

-1 = Extension not found

0 = Idle

1 = In Use

2 = Busy

4 = Unavailable

8 = Ringing

16 = On Hold

GetConfig

Retrieve configuration

Filename:users.conf

Action: GetConfig

ActionID: #10003

Filename: users.conf

 

Response: Success

ActionID: 20004#10004

Category-000000: general

Line-000000-000000: userbase=600

Line-000000-000001: hasvoicemail=yes

Line-000000-000002: vmsecret=1234

Line-000000-000003: hassip=no

Line-000000-000004: hasiax=no

Line-000000-000005: hasmanager=no

…  … etc.

The contest left is only partly listed.

Hangup

Call hangup

Channel: channel number

Action: hangup

Channel: PJSIP/305-00000026

ActionID: #10004

 

Response: Success

ActionID: #10004

Message: Channel Hungup

 

Redirect

Transfer the call

Channel: Source channel.

ExtraChannel: Destination channel.

Exten:destination number

Context: source extension’s dial plan

Priority:Priority

ActionID:Optional

Action: redirect

ActionID: #10005

Channel: PJSIP/305-0000000b

Context: DLPN_DialPlan306

Exten: 306

Priority: 1

 

Response: Success

ActionID: #10005

Message: Redirect successful

This command will transfer extension 305’s call to 306.

ListCommands

Show command list

ActionID:Optional

Action: ListCommands

ActionID: #10006

 

Response: Success

ActionID: #10006

WaitEvent: Wait for an event to occur (Priv: <none>)

… …etc

The contest left is only partly listed.

Logoff

 

 

Action: logoff

 

Response: Goodbye

Message: Thanks for all the fish.

 

ParkedCalls

Show parked calls

ActionID:Optional

Action: parkedcalls

ActionID: #10007

 

Response: Success

ActionID: #10007

Message: Parked calls will follow

 

Event: ParkedCall

Exten: 690

Channel: PJSIP/303-00000027

From: PJSIP/305-00000028

Timeout: 38

CallerIDNum: 303

CallerIDName: 303

ActionID: #10007

It shows 303 dials 305 first, then 305 parks the call to 690.

 

Appendix B:AMI Common Events

Event

Description

Example

Remark

Cdr

Used to describe the call detailed record, including time, callerID number, callee number, call duration etc.

Event: Cdr

Privilege: cdr,all

AccountCode:

Source: 303

Destination: 305

DestinationContext: DLPN_DialPlan303

CallerID: "303" <303>

Channel: PJSIP/303-0000000a

DestinationChannel: PJSIP/305-0000000b

LastApplication: VoiceMail

LastData: 305,u

StartTime: 2013-09-27 23:19:26

AnswerTime: 2013-09-27 23:19:39

EndTime: 2013-09-27 23:20:18

Duration: 52

BillableSeconds: 39

Disposition: ANSWERED

AMAFlags: DOCUMENTATION

UniqueID: 1380352766.10

UserField:

 

 

 

Source:Caller ID

Destination:Callee number

Dial

Used to mark a call

Event: Dial

Privilege: call,all

SubEvent: Begin

Channel: PJSIP/303-0000000d

Destination: PJSIP/305-0000000e

CallerIDNum: 303

CallerIDName: 303

UniqueID: 1380352881.14

DestUniqueID: 1380352881.15

Dialstring: 305

 

ExtensionStatus

Used to show extension’s status

Event: ExtensionStatus

Privilege: call,all

Exten: 303

Context: default

Hint: PJSIP/303

Status: 0

Status codes:

-1 = Extension not found

0 = Idle

1 = In Use

2 = Busy

4 = Unavailable

8 = Ringing

16 = On Hold

Hangup

Used to mark a finished call

Event: Hangup

Privilege: call,all

Channel: PJSIP/305-0000000e

Uniqueid: 1380352881.15

CallerIDNum: 305

CallerIDName: <unknown>

Cause: 16

Cause-txt: Normal Clearing

 

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.