Mizu VoIP Server API
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).
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:
Sending SMS message:
Request rate to destination:
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)
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 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
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
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.
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.
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.
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
Commands available for administrators (authenticated as admin user and/or trusted IP address based authentication).
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}
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}
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 }
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)}
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 }
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