Overview
This document describes the Mizutech VoIP server
public API.
The mizu sever API allows a client program to connect to a server
instance and issue commands not covered by the SIP protocol.
The API can accept commands and send answers in various format defined
by the request or the “format” parameter.
Supported transport protocols:
Ø UDP (up to 1490 bytes
packet size)
Ø TCP (requests must be
ended by CR/LF)
Ø TLS (if enabled)
Ø HTTP (1.0 or 1.1)
Ø HTTPS (if TLS is enabled)
Ø websocket (URI must
contain “mvstwebsock”. Then send the request in websocket as you would send in
HTTP URI)
Ø secure websocket (on
port 443 if TLS is enabled)
Ø Tunnel (if encryption/tunneling
is enabled)
Ø SIP (via special
header if enabled)
Ø SMS (some commands
are available also through SMS: p2p, cb, balance, rating, charge, cli. The SMS
text must contain the parameters)
The API can be used by endusers or to implement various functionalities
from:
Ø Any web application
(from client side JavaScript using the HTTP transport or server side script
such as PHP or .NET)
Ø Any mobile or desktop
application
Ø Manually (for example
via telnet, curl or browser)
Ø Test from your
browser (just copy the API request to your browser URL input box and hit the
Enter button)
Ø MManage -> Server
Console form (all API commands can be sent also here, but without the
authentication parameters as all commands from here will be authenticated as
admin requests)
The API is listening by default on port 80 for both UDP and TCP/HTTP/websocket
(can be changed with the “mainaport” global config option or disabled by
setting the “usemainaport” to false).
A simple key/value protocol is utilized for the request with the
following parts:
Ø the “mvapireq” entry
point string has to be used with all requests. A fix string as “mvapireq”.
Ø apientry (name of the
API function such as “sms”, “balance”). See the “API list” section below.
Ø authentication
parameters (“authid” and “authpwd” or “authmd5”/”authsalt”). See the
“Authentication” section below.
Ø function parameters
(such as “anum”, “bnum”, “txt”, “param1” , “param2”). See the “Parameters”
section below.
Supported data formats:
Ø plain text
Ø URL parameters
(usually with HTTP GET: http://SERVER/mvapireq/?apientry=function¶meter1=value1)
Ø parameters in http
body (usually with HTTP POST)
Ø HTML form (submit)
Ø Ini format
(key=value)
Ø XML
Ø SOAP (SOAP+XML)
Ø RDF
Ø JSON
Ø JSONP (http://SERVERADDRESS/mvapireq/jppget?url=...)
For the response a code and/or a text is sent:
Ø code: 200 means
success, 499 means failure
Ø text: all answers are
suffixed with either “ERROR” or “OK”
By default the answer format is guessed from the request, unless it is
specified by the “format” parameter which can be set to one of the followings
(string in lower case):
Ø text
Ø cleartext
Ø html
Ø xml
Ø soap
Ø json
Ø jsonp (will respond
with javascript callback code)
If the httpstrictresponse is set to 1, then the response code is sent
as html answer code (otherwise you will receive HTTP 200 OK for all requests
and the real API response code will be in the message body).
You can also use the old API
over this new (all functions in the old API should work as is).
Examples
The examples below are for HTTP GET with URL parameters (however you
can also use JSON, XML and other formats). Change domain.com to your server
address:port and use valid values for authentication and for the parameters. In
these examples we are using authkey + authid/authmd5 based authentication,
however you might use others as described below in the “Authentication”
section. KEY means the apiv2key global config setting.
Note: You can generate exact examples valid
for your server from MManage -> Tools -> Utilities -> Generate API
examples menu.
API test (this is the simplest example without authentication
requirements):
http://domain.com/mvapireq/?apientry=apitest1
Request user credit if set as public with no apiv2key set (not
recommended in production):
http://domain.com/mvapireq/?apientry=balance&authid=USRNAME
Request user credit with password in clear text (not recommended in
production):
http://domain.com/mvapireq/?apientry=balance&authkey=KEY&authid=USRNAME&authpwd=PASSWORD
Request user credit with proper authentication (recommended):
http://domain.com/mvapireq/?apientry=balance&authkey=KEY&authid=USRNAME&authmd5=MD5
Initiate callback:
http://domain.com/mvapireq/?apientry=callback&authkey=KEY&authid=USRNAME&authmd5=MD5&anum=PHONE1
Initiate phone to phone call:
http://domain.com/mvapireq/?apientry=p2p&authkey=KEY&authid=USRNAME&authmd5=MD5&anum=PHONE1&bnum=PHONE2
Sending SMS message:
http://domain.com/mvapireq/?apientry=sms&authkey=KEY&authid=USRNAME&authmd5=MD5&anum=PHONE1&bnum=PHONE2&txt=TEXT
Request rate to destination:
http://domain.com/mvapireq/?apientry=rating&authkey=KEY&authid=USRNAME&authmd5=MD5&anum=PREFIX_OR_NUMBER
Recharge with PIN code:
http://domain.com/mvapireq/?apientry=charge&authkey=KEY&authid=USRNAME&authmd5=MD5&anum=PINCODE&now
Add credit: (from trusted IP only)
http://domain.com/mvapireq/?apientry=addcredit&authkey=KEY&authid=USRNAME&authmd5=MD5&pin=USERNAME&credit=AMMOUNT
With raw TCP or UDP you can send in the following format (terminated
with a new line if TCP):
/mvapireq/?apientry=apitest&authkey=KEY&authid=USRNAME&authmd5=MD5
With websocket, you have to use the uri with the “mvstwebsock”
parameter such as:
ws://yourserveraddress/mvstwebsock/
Then send the request within the websocket stream as
it would be TCP
JSONP works also for remote services if the “enablejsonp” global config
option is set to 2.
Parameters
Parameters can be URI encoded. By default the basic ASCII character set
are used.
Parameters can be passed by the parameter names (as listed in the API
list section below []) or using param1, param2 … paramn.
Common parameters are the followings:
Ø authentication
parameters: described below in the “Authentication” section.
Ø param1,param2,param3:
this format can be also usually used. It must be in the same order as
documented in the “API list” section below. If you specify the parameters in
this way, then the parameter order must be: functionname, apikey, username,
password, function parameters (anum, bnum, text)
Ø anum/phone1/from: for
first/from/originating phone number
Ø bnum/phone2/to: for
second/to/target phone number
Ø txt/message: body for
sms, email and others
Ø others: as listed in
the “API list” section below
Keywords
The following keywords are automatically replaced by the Mizu VoIP
client apps:
Ø
KEY: api key
Ø
USERNAME: sip username
Ø
PWD: sip password in clear text (should be used only with https)
Ø
MD5CHECKSUM: mizutech old api: MD5("rD58s:" + username
+ ":" + pwd+":"+additional)
Ø
MD5VALUE: mizutech new api: MD5("ck5Gp" + username +
pwd + apiv2md5salt + usersalt) //the usersalt is optional
Ø
MD5WEB: mizutech web MD5("C8y5:" + username +
":" + pwd+":"+additional);
Ø
MD5NORMAL: MD5(username + pwd + salt)
Ø
MD5SIMPLE: MD5(username + pwd)
Ø
SALT: salt for md5 calculation
Ø
PHONE1, PHONE2, PREFIX_OR_NUMBER, CALLEDNUMBER: caller/called
numbers
Ø
PINCODE: pin code
Ø
AMMOUNT: credit
Security
Before execution, the server will authorize and authenticate each API
request as described in the “Authentication” section below.
Each API has a usage limit to avoid overusing or attacks tied to users,
IP’s and global usage.
For additional security you might use the API over HTTPS (the built-in
TLS proxy can be used for this).
Optionally as a simple encryption/obfuscation, you can also encrypt the
requests with XOR + Base64 encoding. The XOR key can be set by the httpapiencryptkey
global setting. Replace the ‘=’ char with ‘-‘ in the resulting string if any.
Ø If you wish to encrypt
the whole POST URI, then encrypt as described above and pass it as “mcrfs”
parameter.
Ø If you wish to
encrypt the parameters values, then encrypt as described above and prefix them
with “oenc1_” string.
For an extra protection make sure to set the “httpapikey” to a random
value in your global configuration.
Authentication
Each API function requires an authentication which is a
combination of the followings:
Ø ip authentication: if
client ip must be in the allowed list defined by the “apiv2ipauth” global config
Ø api key: usually a “authkey”
parameter have to be sent which have to match the “apiv2key” global config
option (old “httpapikey”)
Ø user authentication:
a valid username/password combination (or pin/did). For the password you can
use the md5 hash and this is strongly recommended instead of the clean text
password. TLS/HTTPS can be also used for better security.
The default API can be divided in the following categories:
Ø Sensitive API: IP
authentication is recommended for these. For example “adduser”
Ø Admin API: for server
administration, such as “info” to request server status details
Ø User API: API for
users (such as “sms” to send SMS or “recharge” to add credit) by default with
api key and username + password or md5 authentication.
Ø Public API: for
example “status” to request a user online status (for these you might allow
username based authentication)
The default API’s are set with optimal authentication (sensitive API’s
requiring admin or ip access, local and same LAN IP’s are trusted which you can
change by adding them to tb_api and set custom authentication), however for
custom API’s make sure that you set the proper authentication depending on the
API sensitivity.
For example some API might request IP+apikey+user authentication, while
there are some API’s which you can set do require no authentication at all (for
example you can set the “status” API to require only a valid username). Usually
(and by default) each api require apikey and user authentication (some API’s
doesn’t require these from trusted sources). For admin requests an admin user
name/password has to be used (unless you change it).
For bulk operations you might set the “trustediplist” global config
option to your IP. For example your web server IP. Multiple IP can be separated
by comma.
The following parameters are defined:
authkey: Defined by the “apiv2key” global config option
(optional)
authid: Account username (but can represent also the user id,
name, pincode or did)
authpwd: Account password in clear text (but can represent also
the pin). This should be used only on trusted links such as on the localhost.
Otherwise better to use the authmd5 parameter.
authsalt: Need to be sent if the authmd5 (below) is used (a
short random number or string)
authmd5: MD5(ck5Gp + authid + authpwd + serversalt + authsalt)
MD5: message-digest algorithm
ck5Gp: hardcoded string “ck5Gp”
authid: account user name
authpwd: account password
serversalt: salt defined by the “apiv2md5salt” global
config option (optional)
authsalt: as sent by the “authsalt” parameter (optional
but highly recommended)
The above string parameters just have to be concatenated (no colon or
space between them).
The authentication can be fine-tuned in the tb_api table. You
can specify settings for existing API’s (for example you can force the balance
requests to be always authenticated) and you can also create new entries with
custom SQL.
The following fields are defined:
Ø fname: function name
(api entry such as “sms”, “adduser” or “mynewcustomapi”)
Ø req_key: 1 if authkey
is required, otherwise 0 (default is 1)
Ø req_ip: 1 if ip is
checked, otherwise 0. If 1, then the allowed IP list can be defined by the “apiv2ipauth”
global config option (default is empty which means only local ip). Local IP is
trusted by default. Private/LAN IP is also trusted by default unless you set
the trustlanip global config to false.
Ø req_user: user
authentication: 0=default,2=disabled,4=srvadmin,6=admins,8=ownwers and
resellers, 10=support,12=all,14=public (default is 6 for admin API and 12 for
user API)
Ø req_user_mode:
defines how to authenticate the user. 0=default, 2=user + pwd or pin (def),
4=user or pwd or pin (less), 6=username/pwd (most). The default is defined by
the “apiv2auth” global config option. Will also check the authentication
setting of the user (so it might result in username only or IP based
authentication)
Ø customsql: custom api
based on an SQL query (in case if you set this for a predefined API, then the
predefined behavior will be lost and the API will use your custom SQL). You can
write any query supported by the SQL engine, including stored procedure usage
if needed
For example if you wish to set an API
as public (with no authentication request) just set create a new record in
tb_api with api entry string for fname, 14 for req_user and 4 for
req_user_mode.
API list
The supported commands (API entries) are listed below.
Parameters in []
Short description in
{}
The best way to learn the usage is to try out the requests quickly from
your browser. Some valid examples can be generated from MMAnage -> Tools
menu -> Utilities -> Generate API examples.
User commands
Commands available for users (authenticated as enduser/reseller/other
user type):
newuseru {public add user} [u_username,u_password,u_name,u_email,u_phone,u_currency,u_country,u_address]
balance {credit request}
callrating {call rating details returning credit, maxduration and
rating} [username, callid]
rating {rate request}
status {self online status. 0=doesn’t
exists,1=offline,2=online,3=calling,4=speaking}
verifyuser [userusername] {request the status of this user. 0=doesn’t
exists,1=offline,2=online,3=calling,4=speaking}
presence_get [userusername/userlist,ptype,domain]
{ will return the presence status of one ore multiple users; ptype have to be
set to 1 if called from timer and 0 when at start; answer: OK: puserlist:
user1:status1,user2:status2 OR ERROR: errordescription }
presence_set [pstatus,ptype] {set presence status; pstatus means status
string, ptype have to be set 0 when called at start, otherwise 1; answer: OK:
xxx or ERROR: xxx (doesn't matter since we have nothing to do with it). Also
offline messages: XOFFMESSAGE:fromuser:textXOFFMESSAGE:fromuser2:text2XOFFMESSAGE:}
sendim [bnum/buserlist,txt] {send chat message}
getconfroom {get/create conference room}
callback [num] {initiate callback call}
p2p [bnum, cnum] {phone to phone call request}
sendfax [from,to,filename]
sendmail [from, to, subject, message] {from can be empty}
sms [anum,bnum,txt] {send sms message}
sendsms [telnumber,message] {send sms message}
sendsmsunicode [telnumber,message] {send sms message}
cli {add pin less number (ANI)}
charge [pin] {recharge using recharge PIN}
cccharge [cardnum,expireyear,expmonth,ccv2,ammount]
transfercredit [username,credit] (user A can send credit to user B)
lockphonenumber {reserve a phone number}
getphonenumber {return a phone number from the free pool)
search {user search}
callbackaccessnumber {return the callbackaccessnumber}
addcallbacknumber {add custom callback number}
changepwd [newpassword,oldpassword]
forgotpasswordquestion [email]
forgotpasswordanswer [email, forgotpasswordanswer]
addcredit [pin] {add credit (Only from trusted IP by default)}
callforward [anum,bnum,cnum]
sendccinfo
Admin commands
Commands available for administrators (authenticated as admin user
and/or trusted IP address based authentication).
General
version {display software version number}
help { show console command list }
reguser [usr] {show registered users/devices}
newuseri {private fast/unrestricted add user from trusted source} [u_username,u_password,u_name,u_email,u_phone,u_currency,u_country,u_address]
newuser {deprecated}
adduser {deprecated}
keepalive {keep alive the connection}
close/exit/quit {close current connection}
Diagnostics
info {show server status and important parameters}
routingtest [ip,caller,called] {will return the destination route as it
would be for real call}
gencdr { generate cdr records: www.mizu-voip.com/portals/0/files/gencdr.pdf
}
routingtest
deviceid {show device id}
fastusers {list cached users}
quickstat {quick statistics}
endpoints {list sip endpoint info}
locks {list of pending loks}
threadlist {thread list}
threads {thread list}
threads2 {thread list}
querylist {list the guid for the current running queries}
lists
shortinfo
tunnelinfo
tunnelinfoex
tunnellist
call
showlog [main/sip/gk/sh/tcp,lines] {show the requested logfile}
log
file {will send the requested file}
logsearch
reports
showcfg {show the config files}
Commands
cmd {exec windows shell command}
asendemail [from, to, subject, message. from can be empty]
asendsms [telnumber,message] {send sms message}
sendamsg {SendAgentMessage: send message to agents
(agentid-all,message) }
voicehere [dbcallid] {start realtime call listening}
voicehere2
bannedlist {list of banned ip's}
delbanned [all] {remove ip from the banned list (ip)}
disccall [dbcallid]
gk {connect to h323 gatekeeper module}
client {switch to the requested client}
db {any database query (select,update,etc) only if authenticated user
type is admin}
setip {set new ip (cardname,ip,mask,gateway,gwmetric)}
timezoneset {set timezone}
putfile [filename, filedata] {will save a file under the server
directory. The filedata should be base64 encoded }
getfile [filename] {will load a file from under the server directory }
Reset
reload {reload current configuration}
vsiprst {restart sip-h323 router}
sipreset {will reset the sip stack}
maintreset {will restart the maintanance thread}
ftprst
webrst
resetp
servicerst {restart the main service}
servicerstdaw
dbreset {reset database connections}
pcrst {restart the PC}
gwrst { restart all gateways }
dbrsttgs
apireload {useful if you added/modified an entry in tb_api)
rulesreload
reloaddialplan
reloadapikeys
reloadnumdircache
logrename
rebill
reindexncache { reindex ccampclient }
calcncache { recalc cache size and mode }
clearnccache { clear next client cache [operatorid] }
upgradeall {selfupgrade all clients (0-vclientgw,1-vclientsrv,2-all)}
Various operations
predectivet [start,stop,restart] {start-stop predective thread}
syncmedia {syncronize media files}
stopcanner {stop number scanner threads}
checkscanner {check number scanner threads}
backupdb
backup {BackupToOtherServer: launch a database backup to the second
server}
finetune {FinetuneService}
normalizechk { check number normalization (called,caller,country) }
syncusers [oop] {syncroonize fast users list with the database}
delobj
[ep/logic/sqlupd/router/pred/check/simall/maint/logger/dbobj/all] {free
objects}
monthlymaint { run monthly maintanance tasks }
weeklymaint { run weekly maintanance tasks }
dailymaint { run daily maintanance tasks }
hourlymaint { run hourly maintanance tasks }
dailyreport { launch the daily report builder thread }
unittest [testtype,threads,testtime,parameter] {start unit tests}
savesettings {write uncommitted settings from db to file}
setini [section,key,value,file] {write to ini file}
getini [section,key,file]] {read from ini file}
saveinifiles {write uncommitted inikeys from db (module,file -or all,
notsaved) }
loadinifiles {load ini to db (module,file -or all)}
toclient { send message to client service (clientip or username,
message) }
togw { send message to gw (clientip or username, message) }
call { sim call each other (origsimid,telnum,duration) }
toip { send message to the specified
(sims,simid,credit,callnum,dialnum) ip }
at { send direct message to the specified engine
(gwname,line,ATcommand) }
updcdrdir
createcdrinfo
setfastregpwd
newuserevent
newusersevent
checkcredits {check charges and creditrequests need}
checkpins {will recheck pincodes}
capcheck { check free capacity (direction -3330630) }
parsegsmcdr { reparse cdrr from the specified logfile }
willstop { no more creditcheck }
checkmails {CheckEmailJobs: check email jobs}
db [txt] {any sql select/insert/update command}
setfield [table, fieldtype, fieldname, fieldvalue,rowid, sync] {update
a field}
getfield [table, retfieldname, filterfieldtype, filterfieldname, filterfieldvalue]
{request a field}
def values:
table:
tb_users
retfieldname:
id
filterfieldtype:
auto guess
filterfieldname:
auto guess (username/callerid/userid)
filterfieldvalue:
mandatory
pputfile [filename, filedata] {will save a file under the mvweb\filestorage
directory. The filedata should be base64 encoded }
pgetfile [filename] {will load a file from under the mvweb\filestorage
directory }
Custom
You can create your custom API by adding rows to tb_api via the
“customsql” field. Iit can contain any sql statement: for SELECT it will
display the rows (max 100) and for UPDATE/INSERT it will execute the query.
Make sure to set the proper values for the authentication fields and
set any name with the “fname” field.
You might prefix the sql with * to execute synchronously (otherwise the
faster async will be used which can’t tell if the query have failed). The following keywords can be used:
Ø
[USERID]: will be replaced with the currently logged in user id
(tb_users.id)
Ø
[USERNAME]: will be replaced with the currently logged in
username
Ø
[SPARAM1]: will be replaced with the supplied sparam1 URL
parameter
Ø
[SPARAM2]: will be replaced with the supplied sparam2 URL
parameter
Ø
…
Ø
[SPARAM99]: will be replaced with the supplied sparam99 URL
parameter
Be aware of SQL injections. Don’t pass these
parameters from user input!
Note: there are also other ways to interact with the Mizu VoIP
server, as described in the “Integration
Guide” (for example working directly with the SQL database).
For more details use the Admin Guide
or contact
our support
Copyright
© MizuTech