Overview
This page is a rough guide to get you configuring chan_sip and Asterisk to accept subscriptions for presence (in this case, Extension State) and notify the subscribers of state changes.
Requirements
You should understand the basics of
- Device State and Extension State and Hints
- Configuring SIP peers in sip.conf
General Process
Overview
It is best to consider this configuration in the context of a very simplified use case. It should illustrate the overall concept, as well as the ability for Extension State to aggregate Device States.
The case is that our administrator wants the user device of SIP/Alice to display the presence of Bob. Bob has two devices, SIP/Bob-mobile and SIP/Bob-desk. He could be on either device at any one time, so we want to map them both to the same Hint. That way, when Alice subscribes to the Hint, she'll get the aggregated Extension State of Bob's devices. That means if either of Bobs phones are busy, then the extension state will be busy. Then Alice knows that Bob is busy without having to have a separate light for each of Bob's phones.
Figure 1 should illustrate the overall relationships of the different elements involved.
Then following down the page you can find detail on configuring the three major elements, SIP configuration options, hints in dialplan, and configuring a phone to subscribe.
Configure SIP options
Since this is not a guide on configuring SIP peers, we'll show a very simple sip.conf with only enough configuration to point out where you might set specific chan_sip State and Presence Options .
[general] callcounter=yes [Alice] type=friend subscribecontext=default allowsubscribe=yes [Bob-mobile] type=friend busylevel=1 [Bob-desk] type=friend busylevel=1
We are setting one option in the general section, and then a few options across the three SIP peers involved.
callcounter and busylevel are the most essential options. callcounter needs to be enabled for chan_sip to provide accurate device. busylevel=1 says we want the device states of those peers to show busy if they have at least one call in progress. The subscribecontext option tells Asterisk which dialplan context to look for the hint. allowsubscribe says that we will allow subscriptions for that peer. It is really set to yes by default, but we are defining it here to demonstrate that you could allow and disallow subscriptions on a per-peer basis if you wanted.
|
This diagram is purposefully simplified to only show the relationships between the
elements involved in this configuration.
Configure Hints
Hints are configured in Asterisk dialplan (extensions.conf). This is where you map Device State identifiers or Presence State identifiers to a hint, which will then be subscribed to by one or more SIP User Agents.
For our example we need to define a hint mapping 6001 to Bob's two devices.
[default] exten = 6001,hint,SIP/Bob-mobile&SIP/Bob-desk
Defining the hint is pretty straightforward and follows the syntax discussed in the Extension State and Hints section.
Notice that we put it in the context we set in subscribecontext in sip.conf earlier. Otherwise we would need to make sure it is in the same context that the SIP peer uses (defined with "context").
If you have restarted Asterisk to load the hints, then you can check to make sure they are configured with "core show hints"
*CLI> core show hints -= Registered Asterisk Dial Plan Hints =- 6001@default : SIP/Bob-mobile&SIP/B State:Unavailable Watchers 0
You'll see the state changes to Idle or something else if you have your sip.conf configured properly and the two SIP devices are at least available.
Configure Subscriber
You should configure your SIP User Agent (soft-phone, hard-phone, another phone application like Asterisk) to subscribe to the hint. In this case that is SIP/Alice and we want her phone to subscribe to 6001.
The process will be different for every phone, and keep in mind that some phones may not support Asterisk's state notification. With most phones it'll be a matter of adding a "contact" to a contact list, buddy list, or address book and then making sure that SIP presence is enabled in the options.
If you want to submit a guide for a specific phone, feel free to comment on this page or submit it to the Asterisk issue tracker.
Operation
Typically as soon as you add the contact or subscription on the phone then it will attempt to SUBSCRIBE to Asterisk.
If you haven't done so, restart Asterisk and then restart the SIP User Agent client doing the subscribing.
The flow of SIP messaging can differ based on configuration, but typically looks like this for a peer that requires authentication:
SIP/Alice Asterisk ---------------------------------------- SUBSCRIBE ---> <--- 401 Unauthorized SUBSCRIBE(w/ Auth) ---> <--- 200 OK <--- NOTIFY 200 OK --->
In the expanding frame below is a SIP trace of a successful subscription for reference. You could see this on your own system by running "sip set debug on" and then watching for the subscription. You might have to restart your phone again or re-add a contact to see it.
Once the subscription has taken place, there is a command to list them. "sip show subscriptions"
*CLI> sip show subscriptions Peer User Call ID Extension Last state Type Mailbox Expiry 10.24.17.254 Alice ZjE2ZDAwYThiOTA 6001@default Unavailable pidf+xml <none> 001800 1 active SIP subscription
From this point onward, Asterisk should send out a SIP NOTIFY to the Alice peer whenever state changes for any of the devices mapped to the hint 6001. Alice's phone should then reflect that state on its display.
Attachments:





