Yeastar S-Series VoIP PBX Developer Guide

• Introduction
• Logging in Yeastar S-Series VoIP PBX
• Enabling AMI on S-Series VoIP PBX
• Logging in S-Series AMI
• AMI Actions and Events
• Establishing a New Call
• Judging the Status of a Call
• Detecting Incoming Call’s Caller ID
• Transferring a Call
• Appendix A：AMI Common Commands
• Appendix B：AMI Common Events

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

Appendix B：AMI Common Events