VoIP software

StarTrinity VoIP Softswitch Tutorial

Database architecture
Runtime operations and commands, dynamically calculated fields
Default call processing steps
Setting up the VoIP softswitch for the first call - basic steps
Software architecture

Database architecture

The database architecture diagram is the best way to show you concepts and features of our softswitch. There diagram contains alternative names of entities, because there are multiple names for basic concepts in the VoIP industry
Invoices(payments, money movements)
  • originator ID
  • payment date
  • amount, currency
  • status
  • service, payment details
Invoice Templates
  • ID
  • template
  • detail level
Originators / Customers(Accounts / Calling cards / Clients / Companies)
  • ID
  • parent customer ID
  • routing group ID
  • service plan ID
  • max depth of child customers
  • commission size
  • enabled
  • time zone
  • currency
  • balance, max. balance
  • max. credit
  • enable CDR reports
  • enable tariff change notifications
  • billing email
  • technical email
  • company info: name, address, VAT ID, etc.
  • web auth. info, last web auth. date
  • webAPI auth. info, last webAPI auth. date
  • webRTC API auth. info
  • VoIP auth. info
    (IP address(es), user+password)
  • PIN code
  • tech. prefix, CLD auth. mask (DID)
  • last call date
  • codec configuration
  • disconnection reason mapping
  • max. channels count
  • max. call duration
  • prefix to add/remove,
    CLI/CLD translation rule
  • hide own CLI
  • enable call recording
  • block routing loops
  • media proxy mode: auto, always, never
  • packet capture mode: off, SIP, SIP+RTP
  • status / error message
Service plans
  • ID
  • tariff ID
  • billing cycle: week, month, none
  • invoice template ID
  • billing day: [of week/month], on assignment
  • low balance alarm threshold
  • low balance alarm mode: email, sound during call
  • additional service charges
Tariffs / Destination sets(Pricelists)
  • ID
  • enabled
  • applied to: originator, terminator
  • currency
  • grace period / free seconds
  • connection fee
  • min billed duration
  • max loss % (for originators)
Tariff rates / Routes
  • tariff ID
  • enabled
  • prefix
  • min, max digits
  • country, region (automatically detected)
  • rate1, period1, rateN, periodN
  • activation, expiration date
  • priority in routing group (for originators)
Currency exchange rates
  • currency
  • usd per unit
  • when updated
  • source of data
    • manual
    • custom server
Routing groups
  • ID
  • routing policies (ordered list):
    • prefix length
    • least coast
    • weighted distribution (load balancing)
    • routing group item order
    • route priority
    • combination of
      ASR, ACD, PDD
Routing group items
  • ID
  • routing group ID
  • destination set ID
  • terminator ID
  • weight
  • order in routing group
  • activation, expiration date
Suppliers(Vendors / Companies)
  • ID
  • company information
  • web auth. info
  • balance
  • base currency
  • time zone
Terminators / Gateways
  • ID
  • supplier ID
  • enabled
  • host / IP address, SIP port
  • IP address is dynamic (behind NAT)
  • VoIP auth. parameters
  • max. channels count
  • max. call duration
  • prefix to add/remove,
    CLI/CLD translation rule
  • CLD, CLI regular expression
  • custom CLI
  • 100, 18x, 200 response timeouts
  • codec configuration
  • media proxy mode: auto, always, never
  • SIP headers proxy mode
  • packet capture mode:
    none, SIP, SIP+RTP
  • hunt stop SIP codes
  • quality monitoring
    • ACD, ASR, PDD thresholds (optional)
    • statistics window
    • bad quality action:
      make last in route, disable
    • notify on status change
    • retry interval
    • retry batch
  • status / error message
Calls / CDRs
  • SIP Call-ID
  • originator ID
  • terminator ID
  • CLI (caller ID)
  • CLD (called number)
  • created, answered, destroyed time
  • VoIP quality fields
  • billed duration
  • status / error message
  • many other fields
  • ID
  • created date
  • status
  • SIP Call-ID
  • originator ID (who reported)
Custom tables from your database according to custom CallXML script
Tenants / Softswitch owners / Hosted customers
  • ID / email
  • payment processor API settings: PayPal, skrill
  • web administrator password
  • max. channels count
  • custom CallXML script
  • white label logo settings
System settings
  • name
  • value
System log messages
  • severity level
  • date
  • message

Runtime operations and commands, dynamically calculated fields

Originators / Customers(Accounts / Calling cards/ Clients / Companies)
  • generate invoice
  • complete invoice (add funds)
  • make test call
  • check without call: check routing configuration, get rates, limits, CLI/CLD translations
  • traffic statistics
  • number of child accounts / customers / calling cards
  • export / import accounts
  • analyse impact of network delays on billing
Service plans
  • traffic statistics
Tariffs(Destination sets / Pricelists)
  • export / import rates
  • number of routes
  • traffic statistics
Routing groups
  • automatically generate tariff for originator
Routing group items
  • traffic statistics
Suppliers(Vendors / Companies)
  • traffic statistics
Terminators / Gateways
  • traffic statistics
  • analyse impact of network delays on billing
Calls / CDRs
  • terminate current call
  • export / import CDRs
  • query CDRs by syntax expression. e.g. bad / failed calls: SIP error code, dead air audio, one way audio, high jitter, high packet loss, low MOS, small billed duration
Traffic statistics applied to any subset of calls from CDR
  • grouping by originator, terminator, prefix / route, etc
  • number of current calls: ringing, connected, total
  • real capacity chart for terminator based on concurrent calls count and error responses
  • sales / cost / profit
  • billed duration
  • history charts
  • minimum, maximum, average
  • moving averages: based on time, based on N recent calls

Default call processing steps

Call flow in the StarTrinity VoIP softswitch is flexible. Here are default call processing steps:
  • Receive call
  • Authenticate call: identify originator based on IP address, prefix, CLI, PIN code, etc
    • Optionally play IVR menu for calling card user - ask PIN code, destination number
    • Determine root customer or root parent for the current originator
  • Apply trunk capacity rules of the originator (e.g. max. concurrent calls)
  • Extract dialed number (CLD) and caller ID (CLI) from INVITE packet. Apply number translation rules of originator
  • Determine tariff: take it from the root customer's service plan
  • Determine rate for the call to charge the originator: find it by the longest matching prefix with called number
  • Authorize call according to billing rules (e.g. positive balance)
  • Determine routing group for the call. Take it from settings of the root customer
  • Select all destination sets in the routing group which have at least one route matching CLD. From the selected destination sets select route with the longest matching prefix and associated terminator. Example: for CLD = 1234567890 and two destination sets having routes with prefixes 1, 12 and 123, 1234 respectively, the software will select routes with prefixes 12 and 1234. Note: unlike with rates, where only one best matching rate has to be selected, the software selects several routes for the same destination number, but linked to the different terminators.
  • Now we the system has a list of terminators for dialing. Apply additional billing rules (e.g. positive margin), implement routing policy of the routing group
  • Apply terminator trunk capacity rules (e.g. max. concurrent calls, min. interval between calls)
  • Proxy the call to the terminators, try them one-by-one. Apply number translation rules of the terminators
  • Abort the call if billed duration goes over originator's threshold
  • Apply billing rules: decrease balance of originator based on billed duration and rate
  • Measure audio quality of the call, save results to CDR, calculate statistics, send alerts/reports (if configured)
The call processing logic can be customized by modifying CallXML script - for all or single originator/terminator. For example you can send request to a database and route call according to result.

Setting up the VoIP softswitch for the first call - basic steps

  • Setup termination (supplier) side
    • Suppliers -> Add new supplier (company which is responsible for VoIP termination)
      -> Add new terminator into previously created supplier (a way to connect to the supplier, SIP trunk). Enter SIP connection parameters.
    • Destination sets -> Add new destination set (tariff for supplier, list of available country codes with prices, routes)
      -> Add new route into the new destination set or import routes from supplier's pricelist file
    • Routing groups -> Add new routing group -> Add new item that links the routing group with previously created terminator and destination set
  • Setup origination (customer) side
    • Tariffs -> Add new tariff (list of country codes and prices to charge clients) ->Add new rate into the new tariff
    • Service plans -> Add new service plan (service options like billing cycle), select previously created tariff
    • Originators -> Add new originator (company or user which sends VoIP traffic to you), select service plan and routing group. Enter SIP connection parameters
  • Make the first test call from the originator
    • CDRs -> look at the call history, see if the new call is there. Check status field
    • If there is a problem, go to CDRs -> "..." (details) -> SIP trace. Also check system log

Web API methods

The software has a HTTP-based application programming interface (API). Main methods are described here:
  • GET /API/MainViewModel/Originators/CreateOriginator?originatorId=xxx&parentOriginatorId=xxx&maxChannelsCount=xxx&webUiUserId=xxx&webUiPassword=xxx&authUser=xxx&authPassword=xxx&balance=xxx&maxCredit=xxx&customCallerId=xxxx - creates originator, is used for new user sign up at VoIP originator's website
  • GET /API/MainViewModel/Originators/GetBalance?originatorId=xxx - returns originator's balance
  • GET /API/MainViewModel/Originators/AddBalance?originatorId=xxx&value=10 - add some value to originator's balance
  • GET /API/MainViewModel/CreateCall?url=http%3A%2F%2Fyour_server%2Fget_script.aspx&user=usr&password=pass - downloads CallXML script from your web server with specified auth. user and password, creates an outgoing call with the downloaded script
  • POST /API/MainViewModel/CreateCall_Post - creates an outgoing call with the uploaded script. Returns Call-ID SIP header of the created SIP call in JSON format: {'status': 'OK', 'sipCallId': 'the_new_call_id'}. CURL example: curl http://X.X.X.X:19019/API/MainViewModel/CreateCall_Post -uadmin:admin --digest -X POST -d "@my_file.xml" -H "Content-Type:text/plain;charset=UTF-8"
  • GET /API/MainViewModel/CreateSingleCallCommand - creates an outgoing call using currently pre-configured script
  • GET /API/MainViewModel/CurrentCallExists?callerId=XXX&calledId=YYY - checks existence of current call, returns 'true' or 'false'
  • GET /API/MainViewModel/DestroyCall?sipCallId=XXX - destroys current SIP call by SIP Call-ID header
  • GET /API/MainViewModel/GetCurrentCallsCount?optionalCallXmlVariable1=XXX&optionalCallXmlVariable2=YYY - returns number of current calls, optionally filtered by CallXML variables
  • GET /API/MainViewModel/GetVersion - returns software version information - compilation time (UTC)
  • GET /API/MainViewModel/SetCallXmlVariables?callerId=XXX&calledId=YYY&direction=ZZZ&var1=value1&var2=value2 - sets CallXML variables for current SIP call, returns 'true' if call was found or 'false' if call was not found. The direction parameter of URL query is optional, it can be "in" or "out"
  • GET /API/MainViewModel/Cdr/GetCallsJSON[?sipCallId=XXX] - returns all calls from CDR memory in JSON format. Please consider setting "MaxMemoryCallsCount". The request may contain parameter "sipCallId" if you need to get information about specific call
The API methods by default require authentication - you need to use same credentials as in web UI. To turn off authentication, you can add your IP address into whitelist using setting "WebApiTrustedIpAddresses".
There are more undocumented methods available, you can see them in Fiddler when using the web interface. Please let us know if you need some new API method
Copyright 2011-2017 | Blog | Contact lead developer via LinkedIn | Get support via TeamViewer