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: Delay call start in seconds,
  • cd: Answered call duration in seconds,
  • rm: Redirect mode, n=Process redirects in a new instance of the same dial plan.
  • ma: Whether to mangle the SDP, true or false (default is true so use this to specify no mangling on a call leg).
  • fd: Sets a custom From header display name for this call leg,
  • fu: Sets a custom From header URI username for this call leg,
  • fh: Sets a custom From header URI host for this call leg,
  • tr: Determines whether transfers (REFER requests) will be accepted: n=Not permitted, p=Pass thru (default), c=Place call (be careful!)

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)

Description:

A popular dial plan function that can be used to initiate calls using Google's Google Voice service. The application works by sending a HTTP request to Google Voice that in turn initiates a 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.

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.

Description:

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 dial plan owner's current dial plan as stored on their web profile.

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