SIP Subscribe/Notify and Asterisk Hints Explained

The SIP SUBSCRIBE/NOTIFY mechanism – what it is and how it works

The SIP protocol includes a standardised mechanism to allow any SIP client (an IP phone being an example of a SIP client) to monitor the state of another device. Details are provided in the SIP protocol document RFC 3265. Basically, it works like this: If client device A wants to be informed of changes to the status of device B, it sends a SUBSCRIBE request – either directly to device B or to a server that is aware of the state of device B. If the SUBSCRIBE request is successful, then every time device B changes state, device A is sent a SIP NOTIFY message telling it about the event or change of status. This is the mechanism that IP phones use to control BLF lamps. (By the way, it is also the mechanism that Asterisk SLA uses to switch on and switch off the trunk status lamps on participating extension phones).

Message waiting lamps on IP phones are controlled by a very similar mechanism, although the subscribe element is not necessarily explicit. The mechanism is defined in SIP protocol document RFC 3842. The NOTIFY message is sent when the phone first registers with the server and then a further NOTIFY is sent when there is a change in the number of messages or the status of the stored messages.

Hints – How Asterisk supports the SUBSCRIBE/NOTIFY mechanism

Asterisk is like a PBX – it acts as a SIP server and it has awareness of the state of many things including attached phones, queues, voicemail boxes etc. It makes perfect sense that Asterisk should be able to accept SUBSCRIBE requests and then notify the subscribing device whenever there is a change of status in the monitored device. However, the SIP protocols and standards cannot pre-define a name for every possible device or status – instead, the protocol provides a general framework for event notification without defining the actual events or device names. To allow maximum flexibility, Asterisk allows device names to be configured within the dial plan – within the extensions.conf file. For this purpose it uses something called Hints. Hints are simply a user-configurable mapping between an arbitrary name tag and a specific telephony device or application that Asterisk knows about.

When Asterisk receives a SIP SUBSCRIBE request it checks for a hint in the dial plan that matches the name of the device to be monitored. The hint tells Asterisk which physical device this corresponds to. It is best understood by seeing some examples.

Some examples of Asterisk Hints

Hints usually map an extension number (or name) to a device. However, hints can also map to other special internal states (virtual devices) such as the state of a specific call park slot or the state of a specific meetme conference. SLA introduces a new virtual device that is used in a hint to allow subscriptions to the state of a trunk line as defined in the SLA.CONF file.

Here are some examples of Asterisk hints:

Digium introduced a new custom device state in version 1.6 (and with a backport for v1.4) that can be used with hints by prefixing the device name with “Custom:”. If you want to know more about this new feature, please check the Asterisk wiki page describing the function DEVICE_STATE.

Where does Asterisk look for the hints in extensions.conf?

To avoid any possible confusion about the location of these hints, it is recommended that you use the subscribecontext parameter in your sip.conf file to identify the location of all hints within extensions.conf.

There is a little documentation about subscribecontext within the Asterisk wiki:
http://www.voip-info.org/wiki-Asterisk+config+sip.conf
You may find the examples in this link slightly more useful:
http://www.voip-info.org/wiki/view/480i+Busy+lamp+field+BLF+support

Checking and debugging Asterisk hints

At the CLI (Command Line Interface) type “core show hints” to show a list of all defined hints.

To see which subscriptions are active (and the current status for each subscription), type “sip show subscriptions” at the CLI.

If you are having problems with subscriptions not registering properly, it is probably best to use the sip debug mode to display the actual SIP messages being exchanged between your SIP client device and your Asterisk server. Note also that many SIP client devices do not keep re-subscribing. Subscriptions are sometimes only renewed after a very long time interval. Rebooting an IP phone will usually force it to re-subscribe with the Asterisk server.

To enable sip debug mode, type “set sip debug” at the CLI. To switch it off again, type “sip set debug off”.

Asterisk MWI: How to activate the Message Waiting lamp on an IP phone

Asterisk will automatically send NOTIFY messages to your IP phone provided that the IP phone has registered correctly with Asterisk and that Asterisk knows which voicemail box is associated with that extension.

It is easy to check both of the above states using the Asterisk CLI command “sip show peer” followed by the extension number of the phone. The image below shows an edited version of the output that you might see for extension 4003 when it is registered correctly:

If the phone has registered ok then the last line – Reg. Contact – will show a SIP URI similar to the example shown above. If it is not registered then Reg. Contact will be blank. It should also be possible to check the registration state of the phone from the phone’s web interface (or even by looking at the lcd display on the phone).

The line that says “Mailbox: 4003” shows that Asterisk is aware of the link between this phone and the voicemail box number 4003. The voicemail box does not strictly need to be the same number as the extension, but it generally makes things much easier to make MWI and message retrieval work correctly if you do keep them identical.

If the mailbox association is missing, you just need to add a line to the peer definition in sip.conf like this:

For more details about the mailbox parameter, please check the following link:
http://www.voip-info.org/wiki/view/Asterisk+sip+mailbox

It is also possible to link an extension phone and a voicemail box through the user definitions stored in users.conf. In this file the peer definitions are simlar to those in sip.conf, but there are some additional parameters that begin with “has”. For example, “hassip” and “hasvoicemail”. You can probably guess that the following two parameters are the ones you need to set for voicemail:

All that remains to be done now is to configure the IP phone. Unfortunately, the settings on the IP phone differ from one make to another.

Aastra

On the Aastra 53i, you have to associate a Line with the voicemail Message Waiting Indicator – this is an option in Basic Settings>Preferences. There is also a setting in Advanced Settings>Global SIP that allows you to make the phone send an explicit MWI subscription. This option should not be required with Asterisk.

The Aastra 53i does not have a dedicated button for message retrieval, but you can easily program a speed-dial for this job. It would also be possible to use one of the programmable keys as a speed-dial to retrieve voicemail messages, but to do so would be rather wasteful because programmable keys are more versatile than speed-dials and there are not very many on the 53i.

Linksys

The Linksys SPA-941 has a message waiting option on each Ext account. You have to select the Admin login to see these settings, then select one of the Ext tabs, then look for the “Call Feature Settings” section which contains two fields – one to enable MWI and the other to identify the Mailbox ID.

The Linksys phone has a dedicated message retrieval button. You program the number it should dial on the Phone tab in the field called “Voice Mail Number”.

Grandstream

Grandstream phones generally seem to just work with Asterisk MWI without the need to set any parameters on the phone. There is an option to configure a stutter dial tone in the Advanced settings form and an option to explicitly “Subscribe for MWI” in each Account form, but since Asterisk does not generally need an explicit Subscription for MWI, the default settings will usually be adequate.

The field called “Voicemail User ID” determines what number is called when you press the MSG button to retrieve messages, so don’t get confused. It is not the voicemail box number and does not relate to message waiting indication.

Snom 360

As with the Grandstream, you should be able to get MWI working with just the default configuration settings on the phone. However, it is strongly recommended that you keep the mailbox number the same as the extension number – you could have a lot of trouble otherwise. Note that the “Mailbox” field on the Login tab for each Identity is best left blank because Asterisk will tell the Snom phone which number to dial for message retrieval when it sends the Notify containing the message status update. Asterisk gets this number from the “vmexten” parameter which must be configured in sip.conf or in users.conf. Please check the Asterisk wiki for more details:

http://www.voip-info.org/wiki/view/Asterisk+phone+snom
http://www.voip-info.org/wiki/view/Asterisk+sip+mailbox