Help & Support

Dial Plans

Simple Wizard Dial Plan Help
Dial Plan Variables

Introduction

SIP Sorcery dial plans are what control how calls are processed. A dial plan is required for outgoing calls to be processed, without it the SIP Sorcery server would not know how you wanted your calls to be forwarded. A dial plan is optional for incoming calls. If a SIP account does not have an incoming dial plan specified then the default behaviour is to forward the call to all registered bindings for that account.

The SIP Sorcery dial plans are written as Ruby scripts. The SIP Sorcery application server exposes a wide range of functions that can be called in dial plan scripts to place calls, send emails, send instant messages, retrieve and set values from a database and many more.

List of Dial Plan Functions

sys.Dial

Usage:

DialPlanAppResult sys.Dial(string dialString)
DialPlanAppResult sys.Dial(string dialString, int ringTimeout)
DialPlanAppResult sys.Dial(string dialString, int ringTimeout, int answeredCallLimit)

Description:

The most important dial plan function. Initiates a call to one or more SIP end points and when the first call is answered will bridge it with the SIP user agent that initiated the application. The Dial command takes a dial string as a parameter and it controls the order, delay and other types of behaviours for the forwarded call requests. The syntax of the dial string is best demonstrated by an example:

  • A call will be placed to 123@provider1,
  • After a 5 second delay a call will be placed to 456@provider2,
  • If both calls fail a call will be placed to 789@provider3.

If at any point one of the forwards answered all other forwards are cancelled and the dialplan execution terminates. The additional options that can be used on each call leg are:

  • dt=integer: Delay call start in seconds,
  • cd=integer: Answered call duration in seconds,
  • rm=n or m: Redirect mode, if no redirect option is specified then the a new anonymous forward will be generated for the redirect URI.
    • n=Process redirects in a new instance of the same dial plan,
    • m=Manual and will not do anything with the redirect leaving it up to the dialplan to decide.
  • ma=true or false: Whether to mangle the SDP, true or false (default is true so set ma=false to specify no SDP mangling on a call leg).
  • fd=string: Sets a custom From header display name for this call leg,
  • fu=string: Sets a custom From header URI username for this call leg,
  • fh=string: Sets a custom From header URI host for this call leg,
  • tr=n or p or c: Determines whether transfers (REFER requests) will be accepted:
    • n=Not permitted,
    • p=Pass thru (default),
    • c=Place call (be careful!).

Addtional examples of using the sys.Dial with various dial string options are shown below.

sys.Respond

Usage:

sys.Respond(int statusCode, string reason)
sys.Respond(int statusCode, string reason, string customHeaders)

Description:

This dial plan function is used to send a SIP response back to the caller. If the response is a informational or 1xx response the dial plan will continue execution after the function. If the response is a final response, which is a status code of 200 or greater, than the dial plan will terminate after the function. The statusCode parameter must be set to a valid SIP status code (see RFC 3261 Response Codes). The reason parameter for this function is optional and if it is ommitted or set to nil then the default reason for the SIP status code will be used. The customHeaders parameter is also optional and can contain a list of headers delimited by the pipe or '|' character which the server will attempt to append to the SIP response, certain critical headers cannot be overwritten and if they are in the list they will be ignored.

A special case is redirect or 3xx response. In that case the sys.Respond function will treat the first header item in the customHeaders list as a SIP URI and place it in the Contact header of the response. An example of using sys.Respond to send a redirect response is shown below.

sys.Log

Usage:

sys.Log(string logMessage)

Description:

Logs a message that will be displayed on the console and email traces. This is an essential function to provide troubleshooting or general information about the state of a dial plan as it processes a call.

sys.GoogleVoiceCall

Usage:

sys.GoogleVoiceCall(string emailAddress, string password, string forwardingNumber, string destinationNumber, string fromUserToMatch, int phoneType, int callbackTimeout)
sys.GoogleVoiceSMS(string emailAddress, string password, string destinationNumber, string message)

Description:

A popular dial plan function that can be used to initiate calls or sned an SMS using Google's Google Voice service. The application works by sending a HTTP request to Google Voice that in turn initiates a callback or sends an SMS. In the case of the callback the incoming call leg must reach the same SIP Sorcery account that the Google Voice call is being placed for. Once the incoming callback is received it will be matched to the SIP call leg that initiated it.

  • The emailAddress and password are the credentials used to login to the Google Voice portal.
  • The forwardingNumber is the number to request the Google Voice callback on. Whatever this number is it needs to get the call to SIPSorcery.
  • The destinationNumber is the number that will be passed to the callback as the outgoing leg and is the external number that will be called.
  • The fromUserToMatch is used to match the incoming callback to the SIP call that initiated the dial plan execution. By specifying this field sipsorcery will look at the From URI user, in a SIP From header of From: "Joe Bloggs" <sip:12345678@somehost.com> the From URI user is 12345678, to match the calls.
  • The phone type used by GoogleVoice. If not specified defaults to (Mobile=2):
    • 1 - Home
    • 2 - Mobile
    • 3 - Work
  • The callback timeout in seconds which is the amount of time the sipsorcery dialplan will wait for the GoogleVoice callback before giving up and continuing with the next dialplan command. The timeout must be between 5 and 60s and if not specified a default value of 30s is used.

When placing a Google Voice call if an error is received stating "Could not find _rnr_se key on your Google Voice account page, callback cannot proceed" then Google Voice is rejecting the call based on the SIP Sorcery server's IP address. Google allows the IP addresses that can access an account to be reset by visiting this link https://accounts.google.com/DisplayUnlockCaptcha and following the instructions.

sys.WebGet

Usage:

string sys.WebGet(string url)

Description:

Sends an HTTP GET request and returns the result to the dialplan.

Database Functions

Usage:

sys.DBWrite(string key, string value) # Writes a keyed value to the database.
string sys.DBRead(string key) # Reads a keyed value from the database.
sys.DBDelete(string key) # Deletes a keyed value from the database.
List<string> sys.DBGetKeys() # Retrieves a list of all the current user's keys.
sys.StartTransaction() # Starts a new database transaction. Useful it multiple database read and write operations need to be combined.
sys.CommitTransaction() # Commits a database transaction.
sys.RollbackTransaction() # Rollsback a database transaction.

Description:

Additional functions to use an external database:

The dbType parameter in the following functions indicates the type of the external database and the options supported are: MSSQL, Postgresql and MySQL. The connection string should be the same as one that would be used with the .Net framework of which examples can be found here: MSSQL, Postgresql and MySQL.

The external databasse functions do NOT allow arbitrary queries to be executed. They operate the same manner as the SIPSorcery specific functions and rely on a table called dialplandata with the specific schema shown below.

sys.DBWrite(string dbType, string dbConnStr, string key, string value) # Writes a keyed value to the database.
string sys.DBRead(string dbType, string dbConnStr, string key) # Reads a keyed value from the database.
sys.DBDelete(string dbType, string dbConnStr, string key) # Deletes a keyed value from the database.

SIP Header and Request manipulation functions

Usage:

sys.SetCustomSIPHeader(string header, string value) # Sets a custom SIP header that will be added to all subsequent calls.
sys.RemoveCustomSIPHeader(string header) # Removes the custom SIP header from the list.
sys.ClearCustomSIPHeaders() # Clears all custom SIP headers from the list.
sys.PrintCustomSIPHeaders() # Prints custom SIP headers to the monitoring console.
sys.SetFromHeader(string fromName, string fromUser, string fromHost) # Sets the SIP Fromheader that will be used for all subsequent calls.
sys.ClearFromHeader() # Resets the From SIP header.
sys.SetCustomContent(string contentType, string content) # Sets the Content-Type SIP header and the body that will be used for all subsequent call requests.
sys.ClearCustomBody() # Resets the custom Content-Type SIP header and the body.

Description:

The SetFromHeader method is the most useful of the above methods as the SIP From header is what typically translates to caller ID on a SIP call. By customising the SIP From header the caller ID displayed on the callee's phone can be modified. However most SIP Providers use the SIP From header for authentication and modifying it, and in particular the fromUser parameter can cause the call to fail. When caller ID manipulation is required it's recommended to start by only modifying the fromName parameter and only if that doesn't have the desired effect look at modifying the fromUser parameter; the fromHost should only need to be set in rare circumstances.

sys.Email

Usage:

sys.Email(string to, string subject, string body)

Description:

Sends an email the address specified in the to parameter.

SIP Account, Call and Domain query functions

Usage:

int sys.GetCurrentCallCount() # Returns the number of calls currently in progress.
List<SIPDialogueAsset> sys.GetCurrentCalls() # Returns a list of currently active calls.
bool sys.DoesSIPAccountExist(string username, string domain) # Returns true if the specified SIP Account exists on the system, false otherwise.
string GetCanonicalDomain(string host) # Test whether a string represents a domain serviced by SIP Sorcery. Returns the canonical domain for the host string if it is or nil if not.
SIPRegistrarBinding[] GetBindings(string username, string domain) # Gets an array of the registered contacts for a specified SIP account. You must be the owner of the SIP account.
bool sys.IsAvailable(string username, string domain) # Checks whether the specified SIP account is online (has any current bindings).

Description:

Timezone functions

Usage:

string sys.GetTimezone()
int sys.GetTimezoneOffsetMinutes()

Description:

sys.GetTimezone returns a string representation of the timezone that has been set in the owner's web settings.

sys.GetTimezoneOffsetMinutes returns the number of minutes offset from Coordinated Universal Time (UTC) the dial plan owner's timezone is.

Google Contacts functions

Usage:

string sys.GoogleContactLookup(string oAuthToken, string lookup)

Description:

sys.GoogleContactLookup attempts a lookup with the Google Contacts API.

The oAuthToken MUST be acquired by using the Google Authorisation process to grant permission to the SIPSorcery-DialPlan application, this allows contact lookups on your behalf. The authorisation is initiated by logging into your SIPSorcery account and going to the Settings page. Click on the "Get Google OAuth Token" button and at the end of the process copy and paste the token into your SIPSorcery dialplan. This should only need to be done once. If you invalidate the token from within your Google account in which it will need to be re-done.

The lookup value can be anything but typically some part of an incoming caller's ID would be used such as req.Header.From.FromURI.User or req.Header.From.FromName. The function will only return the top result from the lookup and will return nil if there are no results found.

Callback

Usage:

sys.Callback(string dest1, string dest2)
sys.Callback(string dest1, string dest2, int delaySeconds)
sys.Callback(string dest1, string dest2, int delaySeconds, int ringTimeoutLeg1, int ringTimeoutLeg2)
sys.Callback(string dest1, string dest2, int delaySeconds, int ringTimeoutLeg1, int ringTimeoutLeg2, string customHeadersCallLeg1, string customHeadersCallLeg2)

Description:

The Callback application is used to create a call between two separate parties rather than one between the original caller and a single forwarded destination.

The Callback application works by dialling the first call leg and if the leg is answered a call will be placed to the second leg and then if the second leg is answered the two calls will be bridged together. One weakness with this approach is that the first call leg can left listening to dead air while the second call leg is placed. Typically the first call leg should be to a party who is aware they are pariticpating in a callback and knows to hang on the line.

The additional parameters that can be used with the Callback application can control the timing or tailor the requests that are sent to each of the call legs:

  • dest1: The SIP URI that represents the first call leg for the callback,
  • dest2: The SIP URI that represents the second call leg for the callback,
  • delaySeconds: A delay in seconds before placing the first call. An example of where this may be useful is giving someone a chance to hangup their phone if they are calling themselves back,
  • ringTimeoutLeg1: The amount of time to ring the first call leg before giving up and cancelling the callback. If 0 the max timeout of 180s will be used,
  • ringTimeoutLeg2: The amount of time to ring the second call leg before giving up and cancelling the callback. If 0 the max timeout of 180s will be used,
  • customHeadersCallLeg1: A string delimited by the | character that contains a list of custom SIP headers to add to the INVITE request sent for the first call leg,
  • customHeadersCallLeg1: A string delimited by the | character that contains a list of custom SIP headers to add to the INVITE request sent for the second call leg.