Getting Started

• Connecting your SIP device
• Creating provider records
• Dial plans
• Incoming call processing

Connecting your SIP device

Start by creating a SIP account on the SIP Accounts page. A SIP account is what your phone, adapter (ATA) or softphone registers with and places calls from. The password is generated for you and shown once when the account is created; it can be shown again from the SIP Accounts page whenever a device needs reconfiguring.

The settings needed to connect a SIP device are the bare minimum:

• Username: the SIP account's username.
• Password: the SIP account's password.
• Server (or domain, or realm): the SIP account's domain, shown beside it on the SIP Accounts page, for example sipsorcery.com.

You don't need to enter an outbound proxy, auth username and so on. Apart from the three fields above you can normally leave every other setting on your SIP device at its default. Once the device has registered it appears under Current registrations on the SIP Accounts page.

A SIP account with no dial plan can already call the other SIP accounts on the server and receive calls, which is a quick way to check a device is working before going further.

Creating provider records

The next step most people take is to set up one or more SIP provider records. SIP providers are connections to third party SIP services that typically provide incoming and outgoing calls, but they can also be used for services such as voicemail or IVRs.

To create a SIP provider record go to the SIP Providers page and enter the details your SIP provider supplied. The main settings are listed below; the SIP Providers help page covers them all.

• Name: the name you want to use for this provider. Dial plans use it to place calls through the provider, so it's best to keep it short and recognisable.
• Address of record, Authentication username and Password: the account details your provider gave you.
• Registrar: your provider's server.
• Keep this registration active: tick it to register with the provider. In most cases you only need to register if you want to receive incoming calls from the provider. If you only use the provider for outgoing calls you don't need to.
• Contact URI: where the provider should send incoming calls. For calls to reach one of your SIP accounts, use that account's address, for example sip:fred@sipsorcery.com.

Dial plans

Dial plans control how your calls are routed. They can be built with the Simple Wizard, a table of rules edited in the portal, or written as a script in a Ruby-style language that is surprisingly easy to use even for novices. The simplest possible Ruby dial plan is shown below.

# Hello World dial plan example.
sys.Dial("music@iptel.org")

This dial plan forwards every call to a recorded music on hold server run by iptel.org. 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.

# Practical dial plan example.
sys.Log("New outgoing call received to #{req.URI.User}.")

case req.URI.User
  # Speed dials.
  when "100" then sys.Dial("subaccount1@local")
  when "101" then sys.Dial("subaccount2@local")

  # Prefix dialling for providers.
  when /^\*1/ then sys.Dial("${dst:2}@provider1")
  when /^\*2/ then sys.Dial("${dst:2}@provider2")

  # PSTN calls.
  when /^00[1-9]/ then sys.Dial("${dst}@international_pstn_provider")
  when /^[1-9]/ then sys.Dial("${dst}@local_pstn_provider")

  else sys.Respond(404, "Oops no dial plan rule found for destination")
end

An explanation of each part of that dial plan follows.

# Practical dial plan example.

Lines that start with a # are comments and are for information only.

sys.Log("New outgoing call received to #{req.URI.User}.")

sys.Log writes a message to the call's dial plan trace, which you can read for any call on the Call History page. Within the message, #{req.URI.User} includes a value in the text; the req.URI.User value is explained in the next part.

case req.URI.User

This line starts a case statement. It works by trying each of the when expressions in turn and taking the action of the first one that matches. req.URI.User is filled in by the server and holds the destination of the call that started the dial plan. The req part stands for request and represents the SIP request that started the call.

when "100" then sys.Dial("subaccount1@local")

This checks whether the number dialled was 100 and if so dials your SIP account named subaccount1. local means an account on this server. This sort of match is a speed dial: by matching a short number like 100 it lets frequently dialled destinations be abbreviated.

when /^\*1/ then sys.Dial("${dst:2}@provider1")

This one uses a regular expression to match the dialled destination. Regular expressions are an extremely powerful and flexible way to match text. This one matches any destination that starts with *1 and forwards the call through the provider named provider1. ${dst} is the number that was dialled, so if the call was to *1234 then ${dst} is also *1234. The :2 in ${dst:2} removes the first two characters, so ${dst:2} is 234.

when /^[1-9]/ then sys.Dial("${dst}@local_pstn_provider")

This is similar, but it's meant to identify calls for the traditional telephone network, or PSTN, and send them through the right provider. By applying different rules to different numbers, different providers can be used, so for example local, mobile and international calls can each go through a different provider.

else sys.Respond(404, "Oops no dial plan rule found for destination")

The final line of the case statement sends a SIP error response to the caller to say the dial plan didn't have a rule for their call.

Incoming call processing

Outgoing calls are processed by a dial plan. Incoming calls can be processed in two different ways.

When an incoming call is received for one of your SIP accounts, such as sip:fred@sipsorcery.com, the default is to ring every device registered to that account. That means it's very easy to receive calls and have them go straight to a phone or ATA, with no dial plan needed.

When more sophisticated handling is needed, a dial plan can process the call the same way it processes an outgoing one. For that, the SIP account the call arrives for needs an incoming dial plan set, which is done on the SIP Accounts page.

It's often useful to handle calls from different providers differently. Every incoming call is addressed to one of your SIP accounts, so the way to tell providers apart is to give each provider its own account:

• Create a SIP account for each provider's incoming calls and tick Incoming calls only. For this example assume accounts named fred-sipgate and fred-callcentric.
• Set each provider's Contact URI to its account, for example sip:fred-sipgate@sipsorcery.com and sip:fred-callcentric@sipsorcery.com.
• Create a dial plan, for example named fredinplan, with the contents shown below.
• Set the incoming dial plan of both accounts to fredinplan.

Calls from either provider then reach the same dial plan, which can tell them apart by the account they arrived for.

# Incoming dial plan example.
sys.Log("New incoming call received to #{req.URI.User} from #{req.Header.From.ToString()}.")

case req.URI.User
  when "fred-sipgate" then sys.Dial("1234@provider1")
  when "fred-callcentric" then sys.Dial("5678@provider2")
  else sys.Dial("fred@local")
end

The structure of this dial plan is almost the same as the outgoing one in the Dial plans section and the same explanation applies. The difference is that instead of a call from your ATA or phone, it processes a call arriving from one of your providers. By matching the account the call arrived for it can tell which provider sent it and act accordingly.

Earlier versions of SIPSorcery suggested a Contact URI of the form provider.fred@sipsorcery.com for this. The servers now only accept incoming calls addressed to a SIP account, so a call to that address is refused; use an account per provider as above.