Getting Started
New accounts are set up with a single SIP account that will allow you to register your device and place outgoing calls to a music on hold system. The configuration parameters required to connect your SIP device to the SIPSorcery servers are the bare minimum.
- Username: The username you signed up with
- Password: The password you signed up with
- Server: sipsorcery.com
Note that you don't need to enter an outbound proxy, auth username etc. etc. Apart from the 3 fields above you can normally leave all other settings on your SIP device set to their defaults.
The next step most people will want to take is to set up one or more SIP provider records. SIP providers are connections to 3rd party SIP services that typically provide inbound and outbound calls but can also be used for services such as voicemail or IVRs.
To create a SIP provider record click on the SIP provider tab and enter the details that have been supplied from your SIP provider. Normally there is no need to enter any advanced settings. The settings that are required are listed below.
- Provider Type: The options are SIP or Google Voice. The SIP option creates a standard entry to integrate with a 3rd part SIP provider. The Google Voice option creates an entry that can be used to place calls via Google's Google Voice service. In order to use Google Voice you will need to create a connection with at least one SIP provider more details can be found in the SIPSorcery Recipes section under the Google Voice recipe.
- Provider Name: The name you want to use for this provider entry. You will most likely need to use the provider name in your dial plan so it's best to keep it as short and recognisable as possible.
- Username: The username for the SIP provider account.
- Password: The password for the SIP provider account.
- Register: Tick this checkbox if you would like to register with your SIP provider. In most cases you only need to register with your provider if you want to receive incoming calls from them. If you are only using the provider for outgoing calls you don't need to register and should leave this box empty.
- Register Contact: If you do tick the register checkbox then you will need to enter a SIP address that will be used as the destination for your provider to send incoming calls to. A default SIP address will be entered for you which is your_username@sipsorcery.com. This address will result in incoming calls being forwarded to your main SIPSorcery SIP account. You are free to change this address and can enter any valid SIP address including ones that are external to SIPSorcery.
SIPSorcery dial plans are what control how your calls are routed. SIPSorcery dial plans can be created through a wizard or by writing a Ruby script; Ruby is a modern powerful scripting language that is surprisingly easy to use even for novices. The simplest possible Ruby dial plan is shown below.
This dial plan will forward every call to a recorded music on hold server run by iptel.org (the home of the famous SER SIP server). It's not a very useful dial plan but it does make it easy to test that your ATA or phone is correctly connected to SIPSorcery.
An example of a more practical Ruby dial plan is shown below.
An explanation of each section in the above dial plan follows.
# Practical dial plan example.
Lines that start with a # are comments and are for informational purposes only.
sys.Log("New outgoing call received to #{req.URI.User}.")
sys.Log is a method or function that can be called within a dial plan to print a log message to the SIPSorcery console. Within the log message the #{req.URI.User} represents a variable to include in the log message, the req.URI.user object will be explained in the next section.
case req.URI.User
This line is the start of a case or switch statement. It works by attempting to match expressions within the case statement to make a decision on some kind of action to take. The req.URI.User portion represents a variable that is pre-populated by the SIPSorcery server and that contains the destination of the call that initiated the dial plan. The req bit stands for request and represents the initiating SIP request.
when "100" then sys.Dial("subaccount1@sipsorcery.com")
This line is one of the expressions for the case statement. It checks if the number dialled was equal to 100 and if so takes the action of dialling subaccount1@sipsorcery.com. This sort of match is a form of speed dial. By matching on a short number like 100 it allows frequently dialled destinations to be abbreviated.
when /^\*1/ then sys.Dial("${EXTEN:2}@provider1")
This line is also one of the expressions in the case statement but unlike the previous one it uses a regular expression to match the dialled destination. Regular expressions are an extremely powerful and flexible way to do text pattern matching. In this case the regular expression will match any destinations that start with a prefix *1 and when matched with forward the call to ${EXTEN:2}@provider1. The ${EXTEN} pattern represents the number that was dialled so for example if the original call was *1234 then ${EXTEN} would also be *1234. The :2 at the end of ${EXTEN:2} indicates that the first two characters should be trimmed from the start so ${EXTEN:2} would be 234.
when /^[1-9]/ then sys.Dial("${EXTEN}@local_pstn_provider")
This line is similar to the previous one but in this case it's intent is to identify calls that are for the traditional telephone network or PSTN and forward them through the appropriate provider. The key point is that by applying different rules to PSTN numbers different providers can be used. So for example different providers can be used for local landline calls, mobile calls and international calls.
else sys.Respond(404, "Oops no dial plan rule found for destination")
This is the final line of the case statement and its purpose is to send a SIP error response to the caller to indicate that the dial plan did not contain a matching rule for their call.
Unlike outgoing calls which are always processed by a dialplan incoming calls can be processed in two different ways.
When an incoming call is received for a SIPSorcery SIP account such as sip:myaccount@sipsorcery.com the default behaviour is to forward the call to all the ATAs and phones that are registered to the myaccount@sipsorcery.com SIP account. This means it's very easy to receive calls and have them forwarded straight to a phone or ATA as no dial plan script or intervention is required.
When more sophisticated incoming call processing is required it is possible to use a dial plan to process the call in the same manner as an outgoing call. For this to work the SIPSorcery SIP account the incoming call is received for needs to have an incoming dial plan set. The SIP account tab allows all the properties of a SIP account to be managed including the incoming and outgoing dial plan.
For incoming calls it's often desirable to have calls from different providers processed in different ways. The quickest way to achieve that is using an incoming dial plan. The steps are outlined below.
- If you don't want to change the behaviour of your main SIP account then create a new SIP account for receiving incoming calls and check the incoming only checkbox. This is the account that the incoming dial plan will need to be set on in a subsequent step. For this example assume the SIP account was created with a username of fredsin.
- For each provider that you would like to process incoming calls for set the register contact to provider_name.fredsin@sipsorcery.com. So for example if you had a provider named sipgate and callcentric the register contacts for them would be sipgate.fredsin@sipsorcery.com and callcentric.fredsin@sipsorcery.com respectively (note if you update the Register Contact on an already registering provider it can take up to 30 seconds for the new binding to apply, this is to avoid over loading providers with registration requests).
- Create a new dial plan, it can be called anything but for this example we'll call it fredsinplan. The contents of the dial plan are shown below.
- Set the incoming dial plan for the fredsin SIP account to fredsinplan.
Those steps will result in calls for each of the providers being sent to the fredsinplan dial plan where they can be processed as required.
The structure of this dial plan is almost identical to the outgoing dial plan in the Dial Plans section and the explanation for it applies as well. The difference is now that instead of processing an outgoing call from your ATA or phone the call is now an incoming one from one of your SIP providers. By matching on the call destination it's possible to determine which provider forwarded the call and different actions can be taken appropriately.