sipsorcery's blog

Occassional posts about VoIP, SIP, WebRTC and Bitcoin. response times SIP Sorcery Last 3 Hours
daily weekly status

Incoming call processing

One of the biggest enhancements in the sipsorcery service compared to the previous mysipswitch service is the number of different ways of processing incoming calls. The drivers for the enhancements were requests by various mysipswitch users for alternative or more flexible ways to process incoming calls. At this stage I believe pretty much every request in the area has been accommodated but unfortunately a side effect has been a number of sipsorcery users having difficulty getting their calls working as they expect. The intention of this post is to clarify the mechanisms available for incoming calls and how they work.

Before delving into the incoming call processing mechanisms one point that needs to be clarified is the mysipswitch concept of SIP accounts and Extensions. An extension with mysipswitch was a SIP URI (e.g. that could be handed out and that was stored in a separate database table to the SIP accounts and that was looked up if no matching SIP account was found. Extensions were very much a bolt on to mysipswitch to cope with the fact that only a single SIP account could be created oer mysipswitch user. With sipsorcery the single SIP account restriction is gone and with it the need to have a separate concept of an extension. Instead there is now the option to create a SIP account that can be specified as incoming only and which will act the same as the mysipwitch Extensions.

Add incoming only SIP account

Add incoming only SIP account

Now that that’s clarified onto the different options for processing incoming calls.

  • Direct to registered bindings,
  • In Dial Plan,
  • Suffix matching.


The Direct option is the default option and is the simplest. It works by forwarding any incoming calls to a SIP account to any currently registered bindings for that SIP account. To use this option the only thing required is that the In Dial Plan setting on the SIP account is left blank. As an example if I were to create a SIP account called joe.bloggs@sipsorcery.comand set up one of my SIP Providers to forward calls to then to receive those calls all I need to do is register my SIP device with with a username of joe.bloggs. Up to 10 SIP devices can register with the same username and when an incoming call comes in they will all ring with the first one that picks up getting the call.

In Dial Plan

The In Dial plan is as the name suggests and the incoming call will be forwarded to the dialplan specified in the In Dial Plan setting for processing. Within the dialplan the call can be processed in any manner desired. An example of an in dialplan that accomplishes exactly the same as the previous Direct option for incoming call processing is shown below.

[sourcecode language=’ruby’]
sys.Log(“dialplan defaultin starting…”)
sys.Log(“call from #{req.Header.From.FromURI.ToString()} to #{req.URI.User}.”)

In the above dialplan an incoming call to will be sent to the defaultin dialplan for processing. Once there it will print the two log messages and then the call will be forwarded to all the current bindings registered for the SIP Account, i.e. exactly the same behaviour as the Direct option.

Suffix Matching

Another mechanism that was cobbled on, in the same way extensions were, to mysipswitch was the ability to process calls that had an arbitrary suffix with a prefix matching an existing SIP account username. By popular demand the same behaviour has been added to sipsorcery.

As an example of how it works if I owned a SIP account called myextension@sipsorcery.comthen incoming calls to the following SIP URIs will also be accepted and processed in exactly the same way as myextension:


The crucial factor is all the URIs end with note the ‘.’ it is the separator between the suffix and the SIP Acount name.

Calls to other sipsorcery accounts from within a dialplan

With sipsorcery if you placed a call to another sipsorcery SIP Account within a dialplan then that call will honour the In Dial Plan setting on the called SIP Account. For example if I use the forward below in my dialplan:

[sourcecode language=’ruby’]

If the myextension SIP account has an In Dial Plan set then the call will now be sent to that dialplan for processing rather than directly to myextension’s registered bindings. If the In Dial Plan is not set then the Dial command will result in the call being forwarded directly to myextension’s registered bindings.

This is a powerful and potentially dangerous feature since a chain of calls to local accounts or two accounts dialling each could result in a large number of dialplans being simultaneously processed. It is requested that suitable precautions be taken to avoid that happening for anyone that wished to make use of this feature.

One additional point when calling local accounts within a dialplan is that if a forward is attempted to a SIP account from the same dialplan that is configured on its In Dial Plan setting then the dialplan will not be used, doing so would create an infinite loop, and instead the registered bindings will be used.

And Finally…

it’s not directly related to the incoming call processing mechanisms but if you find that calls are not reliably getting through to your SIP device from the sipsorcery server then more than likely your NAT is timing out the connection. The best way around that is to check your device for a NAT keep-alive option and activate it. NAT keep-alives work by sending a small packet every 15 to 30s from a SIP user agent to the server to keep the connection alive through the router. If there is no option on your user agent then you can select the option on the SIP Account at the sipsorcery end. This does the same thing in reverse. It’s not quite as good as NATs will respect traffic originating from the private side better than traffic originating from the public side but it should still help.

In addition the expiry interval on your user agent can be reduced. The sipsorcery SIP registrar uses a default register expiry of 113s, sometimes reducing that to 60s can improve the durability of the connection between your user agent and the sipsorcery server through your NAT.

And that’s it, please feel free to post comments with questions for any clarifications on the subject of incoming call processing but I would request thatyou not post comments with general support questions.