VoxStack GSM Gateway API

Version: 1.0.0

Author: J oe.Yung


Change Notes
Date Versions Description Author
2013.2.6 1.0.0 GSM Gateway
SMS API
J oe.Yung








1. Configuring AMI in VoxStack GSM Gateway.
1.1 How to configure AMI interface?
Login your gateway with your user account and password, and please follow this
flow to configure: ADVANCED-->Asterisk API. Please change the default to yours.


Concerning the permit option, if you have one more IP addresses, then you
should have junction with them by symbol &. In the demo test, allowing both
servers 172.16.99.16 and 172.16.1.207 to have access to this GSM gateway.

1.2 Defining read/write authorization for various event classes.


In this illustration, you will be able to define custom authorization for various
event classes. Read authorization permits you to receive asynchronous events, in
general. Write authorization permits you to send commands and get back responses.


2. Monitoring and managing your Asterisk over Asterisk Manager
Interface (AMI).
2.1 Using telnet to demonstrate AMI connectivity over TCP socket.
a. Connect to the AMI over a TCP socket on port 5038.
b. Log in using the login action and your user account.
c. Execute the Ping action .

Heres how to get access to the gateway and some responds for the actions from
AMI.
[root@mylinux ~]# telnet 172.16.99.102 5038
Trying 172.16.99.102...
Connected to 172.16.99.102.
Escape character is '^]'.
Asterisk Call Manager/1.1
Action: Login
Username: admin
Secret: admin

Response: Success
Message: Authentication accepted

Event: FullyBooted
Privilege: system,all
Status: Fully Booted

Action: Ping

Response: Success
Ping: Pong
Timestamp: 1360139590.096698

2.2 Introduction of SMS sending command
gsm send syncsms <span> <destination> <message> <timeout> [id]


Options
Synopsis

Execute SMS sending over a specific GSM channel
Description Send short message to outside
Syntax

Action: Command
Command: gsm send syncsms <span> <destination> <message>
<timeout>[id]
Arguments
span Which GSM channel will you select to send SMS
destination What number will be receiving the short message
timeout How long it will try to send SMS before time is up
id Identifier of SMS. id is an optional parameter


2.2 Starting to send SMS over command action by value gsm send
syscsms ... .With regard to the SMS ID, you will be able to set it by
yourself, or take ActionID to be your SMS ID.
Action: Command
ActionID: 2013 //I take ActionID to be my sms ID.
Command: gsm send syncsms 2 13480798079 "Hello,this is GSM Gateway" 30

Response: Follows
Privilege: Command
ActionID: 2013
SPAN:2 SEND SMS TO PHONE:13480798079 SUCCESSFULLY
--END COMMAND--

Event: VarSet
Privilege: dialplan,all
Channel: EXTRA-SMSSEND/3-1
Variable: SMS_SEND_TYPE
Value: pdu
Uniqueid: 1360139896.17

Event: VarSet
Privilege: dialplan,all
Channel: EXTRA-SMSSEND/3-1
Variable: SMS_SEND_SENDER
Value: 13480798079
Uniqueid: 1360139896.17

Event: VarSet
Privilege: dialplan,all
Channel: EXTRA-SMSSEND/3-1
Variable: SMS_SEND_TXT
Value: Hello,this is GSM Gateway
Uniqueid: 1360139896.17

Event: VarSet
Privilege: dialplan,all
Channel: EXTRA-SMSSEND/3-1
Variable: SMS_SEND_PDU
Value:
0031000B813184708970F900000019C8329BFD66D1D1E939283D071DA74DD031
4C2FDFC379
Uniqueid: 1360139896.17

Event: VarSet
Privilege: dialplan,all
Channel: EXTRA-SMSSEND/3-1
Variable: SMS_SEND_ID
Value:
Uniqueid: 1360139896.17

Event: VarSet
Privilege: dialplan,all
Channel: EXTRA-SMSSEND/3-1
Variable: DIALSTATUS
Value: SMS_SEND_END
Uniqueid: 1360139896.17

Event: Newexten
Privilege: dialplan,all
Channel: EXTRA-SMSSEND/3-1
Context: gsm-2
Extension: sms_send_ok
Priority: 1
Application: System
AppData: touch /tmp/sms/S
Uniqueid: 1360139896.17

Event: VarSet
Privilege: dialplan,all
Channel: EXTRA-SMSSEND/3-1
Variable: SYSTEMSTATUS
Value: SUCCESS
Uniqueid: 1360139896.17

Event: Hangup
Privilege: call,all
Channel: EXTRA-SMSSEND/3-1
Uniqueid: 1360139896.17
CallerIDNum: <unknown>
CallerIDName: <unknown>
ConnectedLineNum: <unknown>
ConnectedLineName: <unknown>
Cause: 0
Cause-txt: Unknown


2.3 Introduction of Manager Action Ping.
Options
Synopsis Keepalive command.
Description

A 'Ping' action will ellicit a 'Pong' response. Used to keep the manager
connection open.
Syntax

Action: Ping
[ActionID:] <value>
Arguments
ActionID ActionID for this transaction. Will be returned.

2.4 Completed transaction of AMI when a short message comes in.

Action: Ping

Response: Success
Ping: Pong
Timestamp: 1360140299.655150

Action: WaitEvent


Response: Success
Message: Waiting for Event completed.

Event: WaitEventComplete

Response: Error
Message: Missing action in request

Event: VarSet
Privilege: dialplan,all
Channel: EXTRA-SMS/3-1
Variable: SMSSRC
Value: +8613480798079
Uniqueid: 1360140505.18

Event: VarSet
Privilege: dialplan,all
Channel: EXTRA-SMS/3-1
Variable: SMSTXT
Value: Hello, this is a short message from my mobile phone!
Uniqueid: 1360140505.18

Event: VarSet
Privilege: dialplan,all
Channel: EXTRA-SMS/3-1
Variable: SMSPDU
Value:
0891683108705505F0040D91683184708970F900003120606174922334C8329BFD6
681E8E8F41C949E83C2A039FA2DA783DAE5F93C7C2E83CCF2771BD4CE83DA
6F719A5D06C1D16F773904
Uniqueid: 1360140505.18

Event: VarSet
Privilege: dialplan,all
Channel: EXTRA-SMS/3-1
Variable: SMSTIME
Value: 2013/02/06 16:47:29
Uniqueid: 1360140505.18

Event: VarSet
Privilege: dialplan,all
Channel: EXTRA-SMS/3-1
Variable: SMSTZ
Value: GMT+8
Uniqueid: 1360140505.18

Event: VarSet
Privilege: dialplan,all
Channel: EXTRA-SMS/3-1
Variable: DIALSTATUS
Value: SMS_END
Uniqueid: 1360140505.18

Event: Newexten
Privilege: dialplan,all
Channel: EXTRA-SMS/3-1
Context: gsm-2
Extension: sms
Priority: 1
Application: System
AppData: /my_tools/process_sms "2" "+8613480798079" "2013/02/06 16:47:29"
"Hello, this is a short message from my mobile phone!"
Uniqueid: 1360140505.18

Event: VarSet
Privilege: dialplan,all
Channel: EXTRA-SMS/3-1
Variable: SYSTEMSTATUS
Value: SUCCESS
Uniqueid: 1360140505.18

Event: Hangup
Privilege: call,all
Channel: EXTRA-SMS/3-1
Uniqueid: 1360140505.18
CallerIDNum: +8613480798079
CallerIDName: +8613480798079
ConnectedLineNum: <unknown>
ConnectedLineName: <unknown>
Cause: 0
Cause-txt: Unknown


In the whole transaction, you can find a code segment as the following. This section is
the most important when you would like to monitor the incoming short message.
Asterisk (Gateway core) will report a new event to the client.
Event: Newexten
Privilege: dialplan,all
Channel: EXTRA-SMS/3-1
Context: gsm-2
Extension: sms
Priority: 1
Application: System
AppData: /my_tools/process_sms "2" "+8613480798079" "2013/02/06 16:47:29"
"Hello, this is a short message from my mobile phone!"
Uniqueid: 1360140505.18

Arguments Value & Description
Event Newexten. When a new short message comes in, Asterisk (Gateway
core) will report a new event to you (client).
Priviledge Dialplan. Allowed event
Channel: EXTRA-SMS/3-1. Which channel to be used?
Context: gsm-2. Conext name.
Extension: sms. Transaction type. When the short message comes in, the
gateway will invoke sms extension.
Priority 1. Executed priority while short message coming in.
AppData /my_tools/process_sms "2" "+8613480798079" "2013/02/06
16:47:29" "Hello, this is a short message from my mobile phone!"
Data which will be saved in CDR.
Uniqueid 1360140505.18. Event Identifier

If TCP socket connection is still alive. And you receive both parameters Newexten and
sms, which indicate that there is a new short message comes in. You will be able to
use Ping action to check if your connection is alive or not, and monitor the incoming
short message by these two events.

2.5 AMI over TCP for Windows.
Yes, you can get access to your GSM Gateway over AMI protocol in Windows system.
Please follow thisflow:
Click Start-->Run-->Open, at the input text box, type cmd to enter a Windows
console.


Hit the [Enter], and it will automatically skip to the next illustration.


In this demo, I sent a short message to be outside by action command.

2.6. Using PHP script to send short message over AMI protocol.

Before doing this, please download phpagi target from website:
http://sourceforge.net/projects/phpagi/, and place it to /var/lib/asterisk/agi-bin. Give
execute permission to the file. Based on my experience, if your PHP version is higher
than 5.3, you MUST rename the function goto in phpagi.php.
Heres demo script voxstack_sms.php:
#! /usr/bin/php -q
<?php

include("phpagi-asmanager.php");

$agi=new AGI_AsteriskManager;


$vst_host='YOUR VOXSTACK GSM GATEWAY IP ADDRESS';
$vst_user='admin'; #Corresponding to your GSM gateway API settings
$vst_pwd='admin'; #Corresponding to your GSM gateway API settings
$vst_port=5038; #Corresponding to your GSM gateway API settings



$agi_status=$agi->connect($vst_host.":".$vst_port,$vst_user,$vst_pwd);
if(!$agi_status)
{

$msg="Failed to connected Asterisk,exit..";
exit(0);
}


$type='gsm';

$method='send';

$sync='syncsms';

$span='2';

$destination='YOUR DESTINATION NUMBER';

$message='HelloWorld';

$timeout='30';

$id='1234';

$agi->Command("$type $method $sync $span $destination $message $timeout
$id");



exit(0);

?>

3. Introduction of USSD sending command.
gsm send ussd <span> <message> [timeout]

Options
Synopsis Execute USSD sending over a specific GSM channel
Description Send USSD on a given GSM channel
Arguments
span Which GSM channel will you select to send USSD
message What USSD code will you send
timeout How long it will try to send USSD code before time is up