Description
MyPBX is an IPPBX based on asterisk, the asterisk manager interface (AMI) is supported also, which allows developer to connect to MyPBX via TCP/IP connection. The default port is 5038(TCP), you can connect using any terminal like putty or your own software. When the connection is established, you can send commands and read the response or events to realize the feature you want.
Figure 1
Protocol’s specification:
1.Before execute any command, a connection should be established and get accessed
2.The terminal can send any command and receive any response any time when the connection is established well.
3.The commands sent by terminal should starts with ‘Action’, the package sent back from server will starts with ‘Response’ or ‘Event’. Response package means the response for the commands it received. Event package means the events happens in server side, it will be broadcasted automatically to any terminal connected via AMI.
4.The sequence of the commands sent by terminal makes no difference; you can arrange them as your wish.
5.CR/LF is used to divide the packages line by line, two CR/LF means to end this command and it will be sent to server side.
Note: before login via AMI, please login MyPBX’s web interface to enable AMI first, you can get the page in ‘System<System<preference<AMI settings’. You can also design the exact permitted IP range to access AMI.
Figure 2
In this example, the user name is ‘admin’, password is ‘password’.
1 Examples to execute commands
1.1 How to login MyPBX’s AMI
Any connection package sent to MyPBX’s AMI port (5038), there will be a response displayed there, the content is ‘Asterisk Call Manager/1.1’.
In this example, MyPBX’s IP address is 192.168.5.142, the terminal software is putty.exe, and you can get this software via this link: www.yeastar.com/download/tools/putty.exe.
Open putty.exe, input the IP address, port, and choose ‘Raw’ as the connection type.
Figure 3
Click ‘Open’ to get the login page.
Figure 4
Then you can login using command, here are the details.
Action: Login
Username: admin
Secret: password
Then press enter key twice to get accessed
Figure 5
The server send the response message:
Resopnse: Success
Message: Authentication accepted
Note:
1. Username and Password means the user name and password in AMI settings page.
2. After authenticated successfully, you will see many events packages sent from server(MyPBX) side,you can ignore thoese if not needed
1.2 How to establish a new call
We can originate a new call through the terminal side using command ‘originate’, and there are some differences between SIP extension and analog extension.
Here are the commands to originate a call from extension 503 to 12806012345.
Action: originate // fixed command ‘originate’ to establish a call.
Context: DLPN_DialPlan503 //Context: DLPN_DialPlan is the fixed prefix of each extension’s dial plan.
Channel: SIP/503 // The channel to dial this call, for SIP extensions, the format must be SIP/extension. As for analog phone, the value must be DAHDI/analog port number, you can get the port number in ‘Line status’ of MyPBX’s web interface.
Exten: 13806012345 // Exten is the number you want to dial.
Priority: 1 // fixed priority to dial.
Timeout: 30000 // the time out value, for example 30000ms.
CallerID: 503 // caller id number displayed at 503 side before dial out
ActionID: 1 // It’s a signature used to identify the request and response between terminal and server.
Figure 6
Here is another example for you to dial from extension 601(analog phone) to number 13806012345
Action: originate
Context: DLPN_DialPlan601
Channel: DAHDI/5
Exten: 13806012345
Priority: 1
Timeout: 30000
CallerID: 601
ActionID: 1
1.3 How to define if the call is finished
After the call is establish by command ‘originate’ in putty, there are many messages sent back from MyPBX for the whole events and response message. Among them, the Event: NewChannel means the call is being established, while Event:Cdr means the call is ended. The Uniqueid is the same in these Events.
Event: Newchannel
Privilege: call,all
Channel: SIP/503-00000000
ChannelState: 0
ChannelStateDesc: Down
CallerIDNum:
CallerIDName:
AccountCode:
Exten:
Context: DLPN_DialPlan503
Uniqueid: 1372066072.1
Event: Cdr
Privilege: cdr,all
AccountCode:
Source: 503
Destination: 13806012345
DestinationContext: DLPN_DialPlan503
CallerID: 503
Channel: SIP/503-00000000
DestinationChannel: SIP/trunk-sps-test1-00000001
LastApplication: Dial
LastData: SIP/trunk-sps-test1/13806012345,,tTkKWwXx
StartTime: 2013-06-24 01:27:52
AnswerTime:
EndTime: 2013-06-24 01:28:11
Duration: 19
BillableSeconds: 0
Disposition: NO ANSWER
AMAFlags: DOCUMENTATION
UniqueID: 1372066072.1
UserField: Outbound
1.4 How to detect the caller ID of incoming call
When you got the Event:Dial from server, we can get the destination number from Header ‘Destination’, if the value is extension number, it means the incoming call, the caller ID exist in Header ‘CallerIDNum’.
Note: There are multiply types in destination Header:
1. SIP/474-000079de, it means the destination number is 474
2. IAX2/306-0000801a, it means the destination number is 306
3. DAHDI/65-0000801c,it means the destination number is analog port, please execute command ‘Action: Command’, command: core show channel 65 to get the exact analog trunk or analog extension, if it’s analog extension, it means the incoming call.
4. SIP/trunk-test1/1112233-0000802c，IAX2/trunk-test2/1112233-0000802c，
SIP/trunk-sps-test3/111222-0000802c, it means to dial out via trunk, not incoming call.
For example:
Event: Dial
Privilege: call,all
SubEvent: Begin
Channel: SIP/470-000079dd
Destination: SIP/474-000079de
CallerIDNum: 470
CallerIDName: 470
UniqueID: 1372066112.31203
DestUniqueID: 1372066112.31204
Dialstring: 474
It means the call comes from 470 to a SIP extension 474.
1.5 How to detect the transferred call
Command ‘redirect’ is used for transferred calls. In this example, extension 303 dials 305 first, 305 rings until time out, the call is transferred to extension 306.
When 30 dial 305, we can get this in AMI:
Event: Dial
Privilege: call,all
SubEvent: Begin
Channel: SIP/303-0000000a
Destination: SIP/305-0000000b
CallerIDNum: 303
CallerIDName: 303
UniqueID: 1380352766.10
DestUniqueID: 1380352766.11
Dialstring: 305
MyPBX will detect the ring in 305, the channel number is SIP/305-0000000b, which will be used to transfer to 306 in command ‘redirect’
Here it’s:
Action: redirect
ActionID: #10001
Channel: SIP/305-0000000b
Context: DLPN_DialPlan306
Exten: 306
Priority: 1
2 Common commands
Warning：Command Action is a little special, the event replied from server just brings ‘Enter’ (\n) instead of ‘Enter+Wrap’ (\r\n), if your program only analyses (\r\n), the event package will be abandoned.
For example:
Response: Follows\r\n
Channel Location State Application(Data)\n
SIP/x7065551212b-1af (None) Ringing AppDial((Outgoing Line))\n
SIP/x7065551212c-2aa 29@default:2 Ring Dial(SIP/x7065551212b)\n
2 active channels\n
1 active call\r\n
--END COMMAND--\r\n
\r\n
3 Common Events
[Finish]
1 Comments