<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2176/18/9/_/styles/combined.css?spaceKey=AST&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/AST/Presence+State">Presence State</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~mmichelson">Mark Michelson</a>
</h4>
<br/>
<h4>Changes (1)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >Digium phones have built-in support for Asterisk's presence state. [This Video|http://www.youtube.com/watch?v=yMuGMGl4Ww0] provides more insight on how presence can be set and viewed on Digium phones. <br> <br></td></tr>
<tr><td class="diff-changed-lines" >When using Digium phones with the [Digium Phone Module for Asterisk|http://downloads.digium.com/pub/telephony/res_digium_phone/], you can set hints in Asterisk so that when one Digium phone's presence is updated, other Digium phones can be notified of the presence change. The DPMA automatically creates dialplan entries so that when a Digium Phone updates its presence, {{CustomPresence:<line name>}} is updated, where {{<line name>}} is the value set for the {{line=}} option in a {{type=phone}} category. Using the example dialplan from the Overview section, Digium phones that are subscribed to <span class="diff-changed-words">{{<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">3</span><span class="diff-added-chars"style="background-color: #dfd;">2</span>000@default}}</span> will automatically be updated about line 2000's presence whenever line 2000's presence changes. <br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>This page is a work in progress. Please refrain from making comments until this warning is no longer present</td></tr></table></div>
<h1><a name="PresenceState-Overview"></a>Overview</h1>
<p>Asterisk 11 has been outfitted with support for presence states. An easy way to understand this is to compare presence state support to the device state support Asterisk has always had. Like with device state support, Asterisk has a core API so that modules can register themselves as presence state providers, alert others to changes in presence state, and query the presence state of others. The biggest difference between the concepts is that device state reflects the current state of a physical device connected to Asterisk, while presence state reflects the current state of the user of the device. For example, a device may currently be <tt>not in use</tt> but the person is <tt>away</tt>. This can be a critical detail when determining the availability of the person.</p>
<p>Asterisk offers the following presence states:</p>
<ul>
<li><tt>not set</tt>: No presence state has been set for this entity.</li>
<li><tt>unavailable</tt>: This entity is present but currently not available for communications.</li>
<li><tt>available</tt>: This entity is available for communication.</li>
<li><tt>away</tt>: This entity is not present and is unable to communicate.</li>
<li><tt>xa</tt>: This entity is not present and is not expected to return for a while.</li>
<li><tt>chat</tt>: This entity is available to communicate but would rather use instant messaging than speak.</li>
<li><tt>dnd</tt>: This entity does not wish to be disturbed.</li>
</ul>
<p>In addition to the basic presence states provided, presence also has the concept of a subtype and a message. The subtype is a brief method of describing the nature of the state. For instance, a subtype for the <tt>away</tt> status might be "at home". The message is a longer explanation of the current presence state. Using the same <tt>away</tt> example from before, the message may be "Sick with the flu. Out until the 18th".</p>
<p>Like with device state, presence state can be placed in hints. Presence state hints come after device state hints and are separated by a comma (<tt>,</tt>). As an example:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>[default]
exten => 2000,hint,SIP/2000,CustomPresence:2000
exten => 2000,1,Dial(SIP/2000)
same => n,Hangup()
</pre>
</div></div>
<p>This would allow for someone subscribing to the extension state of <tt>2000@default</tt> to be notified of device state changes for device <tt>SIP/2000</tt> as well as presence state changes for device <tt>CustomPresence:2000</tt>. The <tt>CustomPresence</tt> presence state provider will be discussed further on this page.</p>
<p>Also like with device state, there is an Asterisk Manager Interface command for querying presence state. Documentation for the AMI command can be found <a href="/wiki/display/AST/Asterisk+11+ManagerAction_PresenceState" title="Asterisk 11 ManagerAction_PresenceState">here</a>.</p>
<h1><a name="PresenceState-DifferencesBetweenPresenceStateandDeviceStateSupport"></a>Differences Between Presence State and Device State Support</h1>
<p>While the architectures of presence state and device state support in Asterisk are similar, there are some key differences between the two.</p>
<ul>
<li>Asterisk cannot infer presence state changes the same way it can device state changes. For instance, when a SIP endpoint is on a call, Asterisk can infer that the device is being used and report the device state as <tt>in use</tt>. Asterisk cannot infer whether a user of such a device does not wish to be disturbed or would rather chat, though. Thus, all presence state changes have to be manually enacted.</li>
<li>Asterisk does not take presence into consideration when determining availability of a device. For instance, members of a queue whose device state is <tt>busy</tt> will not be called; however, if that member's device is <tt>not in use</tt> but his presence is <tt>away</tt> then Asterisk will still attempt to call the queue member.</li>
<li>Asterisk cannot aggregate multiple presence states into a single combined state. Multiple device states can be listed in an extension's hint priority to have a combined state reported. Presence state support in Asterisk lacks this concept.</li>
</ul>
<h1><a name="PresenceState-%7B%7Bfuncpresencestate%7D%7DAndThe%7B%7BCustomPresence%7D%7DProvider"></a><tt>func_presencestate</tt> And The <tt>CustomPresence</tt> Provider</h1>
<p>The only provider of presence state in Asterisk in Asterisk 11 is the <tt>CustomPresence</tt> provider. This provider is supplied by the <tt>func_presencestate.so</tt> module, which grants access to the <tt>PRESENCE_STATE</tt> dialplan function. The documentation for <tt>PRESENCE_STATE</tt> can be found <a href="/wiki/display/AST/Asterisk+11+Function_PRESENCE_STATE" title="Asterisk 11 Function_PRESENCE_STATE">here</a>.</p>
<p><tt>CustomPresence</tt> is device-agnostic and can be a handy way to set and query presence. A simple use for <tt>CustomPresence</tt> is demonstrated below.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>The following dialplan is meant strictly for demonstration. It is not intended to be used as-is in a production environment.</td></tr></table></div>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>[default]
exten => 2000,1,Answer()
same => n,Set(CURRENT_PRESENCE=${PRESENCE_STATE(Custom:Bob,value)})
same => n,GotoIf($[${CURRENT_PRESENCE}=available]?set_unavailable:set_available)
same => n(set_available),Set(PRESENCE_STATE(CustomPresence:Bob)=available)
same => n,Goto(finished)
same => n(set_unavailable),Set(PRESENCE_STATE(CustomPresence:Bob)=unavailable)
same => n(finished),Playback(queue-thankyou)
same => n,Hangup
exten => 2001,1,GotoIf($[${PRESENCE_STATE(CustomPresence:Bob,value)}!=available]?voicemail)
same => n,Dial(SIP/Bob)
same => n(voicemail)VoiceMail(Bob@default)
</pre>
</div></div>
<p>With this dialplan, a user can dial <tt>2000@default</tt> to toggle Bob's presence between <tt>available</tt> and <tt>unavailable</tt>. When a user attempts to call Bob using <tt>2001@default</tt>, if Bob's presence is currently not <tt>available</tt> then the call will go directly to voicemail.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>One thing to keep in mind with the <tt>PRESENCE_STATE</tt> dialplan function is that, like with <tt>DEVICE_STATE</tt>, state may be queried from any presence provider, but <tt>PRESENCE_STATE</tt> is only capable of setting presence state for the <tt>CustomPresence</tt> presence state provider.</td></tr></table></div>
<h1><a name="PresenceState-DigiumPhoneSupport"></a>Digium Phone Support</h1>
<p>Digium phones have built-in support for Asterisk's presence state. <a href="http://www.youtube.com/watch?v=yMuGMGl4Ww0" class="external-link" rel="nofollow">This Video</a> provides more insight on how presence can be set and viewed on Digium phones.</p>
<p>When using Digium phones with the <a href="http://downloads.digium.com/pub/telephony/res_digium_phone/" class="external-link" rel="nofollow">Digium Phone Module for Asterisk</a>, you can set hints in Asterisk so that when one Digium phone's presence is updated, other Digium phones can be notified of the presence change. The DPMA automatically creates dialplan entries so that when a Digium Phone updates its presence, <tt>CustomPresence:<line name></tt> is updated, where <tt><line name></tt> is the value set for the <tt>line=</tt> option in a <tt>type=phone</tt> category. Using the example dialplan from the Overview section, Digium phones that are subscribed to <tt>2000@default</tt> will automatically be updated about line 2000's presence whenever line 2000's presence changes.</p>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://wiki.asterisk.org/wiki/users/removespacenotification.action?spaceKey=AST">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://wiki.asterisk.org/wiki/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/AST/Presence+State">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=21463121&revisedVersion=5&originalVersion=4">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/Presence+State?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>