<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/Private+Representation+of+Party+Information">Private Representation of Party Information</a></h2>
<h4>Page <b>added</b> by <a href="https://wiki.asterisk.org/wiki/display/~mjordan">Matt Jordan</a>
</h4>
<br/>
<div class="notificationGreySide">
<p><em>This page was written by Thomas Arimont of <a href="http://www.datus.com/" class="external-link" rel="nofollow">DATUS AG</a>, Germany</em><br/>
<em>Minor editing by Matt Jordan</em><br/>
<em>Private Representation of Caller, Connected and Redirecting Party IDs</em><br/>
<em>Feature implemented in Asterisk 11 by Thomas Arimont, <a href="http://www.datus.com/" class="external-link" rel="nofollow">DATUS AG</a>, Germany</em></p>
<h1><a name="PrivateRepresentationofPartyInformation-Overview"></a>Overview</h1>
<p>Asterisk already offers a lot of techniques to set and modify party names and numbers of different kinds. There are a number of dialplan functions - <a href="/wiki/display/AST/Asterisk+11+Function_CALLERID" title="Asterisk 11 Function_CALLERID">CALLERID</a>, <a href="/wiki/display/AST/Asterisk+11+Function_CONNECTEDLINE" title="Asterisk 11 Function_CONNECTEDLINE">CONNECTEDLINE</a>, <a href="/wiki/display/AST/Asterisk+11+Function_REDIRECTING" title="Asterisk 11 Function_REDIRECTING">REDIRECTING</a> - that allow you to read and write a wide range of parameters for Asterisk. However, prior to Asterisk 11 it is quite difficult to modify a party number or name which can only be seen by exactly one particular instantiated channel resp. subscriber.</p>
<p>One example where a modified party number or name on one channel is spread over several channels are <a href="/wiki/display/AST/Call+Completion+Supplementary+Services+%28CCSS%29" title="Call Completion Supplementary Services (CCSS)">supplementary services</a> like call transfer or pickup. To implement these features Asterisk internally copies (has to copy) Caller and Connected IDs from one channel to another.</p>
<p>Another example are extension subscriptions. The monitoring entities (watchers) are notified of state changes and - if desired - of party numbers or names which represent the involved call parties. Also in this case the provided party numbers or names are (have to be) taken from the Caller or Connected ID of the corresponding Asterisk channels.</p>
<p>One major feature where a private representation of party names is essentially needed, i.e., where a party name shall exclusively be signalled to only one particular user, is a private user-specific name resolution for party numbers. A lookup in a private destination-dependent telephone book shall provide party names which cannot be seen by any other user at any time.</p>
<p>Asterisk 11 now provides a mechanism by which private party identification information can be signalled to a particular device.</p>
<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>For more information on advanced manipulation of Party Identification in Asterisk, see <a href="/wiki/display/AST/Manipulating+Party+ID+Information" title="Manipulating Party ID Information">Manipulating Party ID Information</a>. Note that it is <b>highly</b> recommended that you are intimately familiar with manipulating party information in Asterisk before reading further.</td></tr></table></div>
<p>This feature is supported in the following channel drivers:</p>
<ul>
<li>SIP (chan_sip)</li>
<li>mISDN (chan_misdn)</li>
<li>PRI (chan_dahdi).</li>
</ul>
<h1><a name="PrivateRepresentationofPartyInformation-FeatureDescription"></a>Feature Description</h1>
<p>This feature defines additional private number and name elements for Caller ID, Connected ID, and Redirecting IDs inside Asterisk channels. The private number and private name elements can be read or set by the user using the respective Asterisk dialplan functions for those elements.</p>
<p>When a channel initiates a call, if it receives an internal connected line update event or an internal redirecting update event, it first checks if there is a valid Connected ID or Redirecting ID private name or number element present. If this is the case it uses this private representation for protocol signalling. If there is no valid private name or number present, then the valid 'regular' non-private name or number element is used instead.</p>
<h2><a name="PrivateRepresentationofPartyInformation-AutomaticInvalidationofPrivateInformation"></a>Automatic Invalidation of Private Information</h2>
<p>Once a private name or number on a channel is set and (implicitly) made valid, it is generally used for any further protocol signalling until it is rewritten or invalidated. To simplify the invalidation of private IDs all internally generated connected/redirecting update events and also all connected/redirecting update events which are generated by channels – receiving regarding protocol information - automatically trigger the invalidation of private IDs.</p>
<p>This explicitly takes place when one of the following conditions occurs:</p>
<ul>
<li>an internal Asterisk channel masquerading is processed (blind and attended transfers, pickup, parking)</li>
<li>Extra connected line update events are internally generated during a SIP specific attended transfer</li>
<li>Extra connected line update events are generated during a call pickup</li>
<li>Connected line update events are generated in the SIP channel due to receipt of corresponding SIP protocol elements (remote party id header, p-asserted-identity header)</li>
<li>Redirecting update events are generated in the SIP channel due to receipt of corresponding SIP protocol elements (diversion header)</li>
<li>Connected line update events are generated in the DAHDI/PRI or mISDN channel due to receipt of corresponding ISDN protocol elements (display IE, connected number IE)</li>
<li>Redirecting update events are generated in the DAHDI/PRI or mISDN channel due to receipt of corresponding ISDN protocol elements (redirecting/redirection IE, divleginfo facility IE)</li>
</ul>
<h2><a name="PrivateRepresentationofPartyInformation-ManualInvalidationofPrivateInformation"></a>Manual Invalidation of Private Information</h2>
<p>In some cases the invalidation of private IDs cannot be done automatically and therefore it is a job the user has to do by applying appropriate and explicit dialplan commands. This is done by setting the <tt>priv-nam-valid</tt> item to <tt>0</tt>.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Example</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">same => n,Set(CONNECTEDLINE(priv-name-valid)=0)</pre>
</div></div>
<p>As an example of where manual invalidation is necessary, consider the case when a private connected name is set towards a particular caller, and after this a blind transfer is executed by the callee to another target where only a 'regular' non-private connected name is set. Because of the priority of the still valid private connected name id on the caller's channel the 'regular' non-private connected name will not become visible to the caller. To solve this issue the user should in general explicitly invalidate the private connected name/number when setting a 'regular' non-private connected name/number.</p>
<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>The user is advised to do the setting of private ids directly on the particular channel which is transmitting the corresponding protocol elements. Using the forward inheritance of the CALLERID, CONNECTLINE and REDIRECTING channel variables can lead to unexpected results.</td></tr></table></div>
<h1><a name="PrivateRepresentationofPartyInformation-RecommendedMechanismforSettingPrivateIdentity"></a>Recommended Mechanism for Setting Private Identity</h1>
<p>The setting of private calling party numbers or names <b>shall</b> be done by using the <a href="/wiki/display/AST/Pre-Dial+Handlers" title="Pre-Dial Handlers">Pre-Dial CALLEE</a> subroutine (<a href="/wiki/display/AST/Asterisk+11+Application_Dial" title="Asterisk 11 Application_Dial">Dial</a> application option 'b'). The setting of private <a href="/wiki/display/AST/Asterisk+11+Function_REDIRECTING" title="Asterisk 11 Function_REDIRECTING">REDIRECTING</a> ids towards the redirected-to party <b>shall</b> also be done using the <a href="/wiki/display/AST/Pre-Dial+Handlers" title="Pre-Dial Handlers">Pre-Dial CALLEE</a> subroutine. Since the setting of the private <a href="/wiki/display/AST/Asterisk+11+Function_CALLERID" title="Asterisk 11 Function_CALLERID">CALLERID</a> in the <a href="/wiki/display/AST/Pre-Dial+Handlers" title="Pre-Dial Handlers">Pre-Dial CALLEE</a> subroutine has to be made by using the <a href="/wiki/display/AST/Asterisk+11+Function_CONNECTEDLINE" title="Asterisk 11 Function_CONNECTEDLINE">CONNECTEDLINE</a> setter function, the setter function for CALLERID is not used at all in this scenario.</p>
<p>The setting of any kind of private connected numbers or names as well as private <tt>REDIRECTING</tt> IDs towards a caller shall be done by using the system subroutines<br/>
<a href="/wiki/display/AST/Manipulating+Party+ID+Information" title="Manipulating Party ID Information">CONNECTED_LINE_SEND_SUB</a> resp. <a href="/wiki/display/AST/Manipulating+Party+ID+Information" title="Manipulating Party ID Information">REDIRECTING_SEND_SUB</a>.</p>
<p>If not using the private number and name representation feature at all, i.e., if using only the 'regular' CALLERID, CONNECTEDLINE and REDIRECTING related function datatypes, the current characteristics of Asterisk's manipulation of party identification is not affected by the new extended functionality.</p>
<h1><a name="PrivateRepresentationofPartyInformation-DialplanManipulation"></a>Dialplan Manipulation</h1>
<p>To grant access to the private name and number representation out of the asterisk dialplan, the read and write functions of the three Asterisk defined functions <a href="/wiki/display/AST/Asterisk+11+Function_CALLERID" title="Asterisk 11 Function_CALLERID">CALLERID</a>, <a href="/wiki/display/AST/Asterisk+11+Function_CONNECTEDLINE" title="Asterisk 11 Function_CONNECTEDLINE">CONNECTEDLINE</a> and <a href="/wiki/display/AST/Asterisk+11+Function_REDIRECTING" title="Asterisk 11 Function_REDIRECTING">REDIRECTING</a> are extended by the following datatypes. The formats of these additional datatypes are equivalent to the corresponding regular 'non-private' already existing datatypes:</p>
<h3><a name="PrivateRepresentationofPartyInformation-CALLERIDAST%3AAsterisk11FunctionCALLERID%3A"></a><a href="/wiki/display/AST/Asterisk+11+Function_CALLERID" title="Asterisk 11 Function_CALLERID">CALLERID</a>:</h3>
<ul>
<li><tt>priv-all</tt></li>
<li><tt>priv-name</tt></li>
<li><tt>priv-name-valid</tt></li>
<li><tt>priv-name-charset</tt></li>
<li><tt>priv-name-pres</tt></li>
<li><tt>priv-num</tt></li>
<li><tt>priv-num-valid</tt></li>
<li><tt>priv-num-plan</tt></li>
<li><tt>priv-num-pres</tt></li>
<li><tt>priv-subaddr</tt></li>
<li><tt>priv-subaddr-valid</tt></li>
<li><tt>priv-subaddr-type</tt></li>
<li><tt>priv-subaddr-odd</tt></li>
<li><tt>priv-tag</tt></li>
</ul>
<h3><a name="PrivateRepresentationofPartyInformation-CONNECTEDLINEAST%3AAsterisk11FunctionCONNECTEDLINE%3A"></a><a href="/wiki/display/AST/Asterisk+11+Function_CONNECTEDLINE" title="Asterisk 11 Function_CONNECTEDLINE">CONNECTEDLINE</a>:</h3>
<ul>
<li><tt>priv-name</tt></li>
<li><tt>priv-name-valid</tt></li>
<li><tt>priv-name-pres</tt></li>
<li><tt>priv-name-charset</tt></li>
<li><tt>priv-num</tt></li>
<li><tt>priv-num-valid</tt></li>
<li><tt>priv-num-pres</tt></li>
<li><tt>priv-num-plan</tt></li>
<li><tt>priv-subaddr</tt></li>
<li><tt>priv-subaddr-valid</tt></li>
<li><tt>priv-subaddr-type</tt></li>
<li><tt>priv-subaddr-odd</tt></li>
<li><tt>priv-tag</tt></li>
</ul>
<h3><a name="PrivateRepresentationofPartyInformation-REDIRECTINGAST%3AAsterisk11FunctionREDIRECTING%3A"></a><a href="/wiki/display/AST/Asterisk+11+Function_REDIRECTING" title="Asterisk 11 Function_REDIRECTING">REDIRECTING</a>:</h3>
<ul>
<li><tt>priv-orig-name</tt></li>
<li><tt>priv-orig-name-valid</tt></li>
<li><tt>priv-orig-name-pres</tt></li>
<li><tt>priv-orig-name-charset</tt></li>
<li><tt>priv-orig-num</tt></li>
<li><tt>priv-orig-num-valid</tt></li>
<li><tt>priv-orig-num-pres</tt></li>
<li><tt>priv-orig-num-plan</tt></li>
<li><tt>priv-orig-subaddr</tt></li>
<li><tt>priv-orig-subaddr-valid</tt></li>
<li><tt>priv-orig-subaddr-type</tt></li>
<li><tt>priv-orig-subaddr-odd</tt></li>
<li><tt>priv-orig-tag</tt></li>
<li><tt>priv-from-name</tt></li>
<li><tt>priv-from-name-valid</tt></li>
<li><tt>priv-from-name-pres</tt></li>
<li><tt>priv-from-name-charset</tt></li>
<li><tt>priv-from-num</tt></li>
<li><tt>priv-from-num-valid</tt></li>
<li><tt>priv-from-num-pres</tt></li>
<li><tt>priv-from-num-plan</tt></li>
<li><tt>priv-from-subaddr</tt></li>
<li><tt>priv-from-subaddr-valid</tt></li>
<li><tt>priv-from-subaddr-type</tt></li>
<li><tt>priv-from-subaddr-odd</tt></li>
<li><tt>priv-from-tag</tt></li>
<li><tt>priv-to-name</tt></li>
<li><tt>priv-to-name-valid</tt></li>
<li><tt>priv-to-name-pres</tt></li>
<li><tt>priv-to-name-charset</tt></li>
<li><tt>priv-to-num</tt></li>
<li><tt>priv-to-num-valid</tt></li>
<li><tt>priv-to-num-pres</tt></li>
<li><tt>priv-to-num-plan</tt></li>
<li><tt>priv-to-subaddr</tt></li>
<li><tt>priv-to-subaddr-valid</tt></li>
<li><tt>priv-to-subaddr-type</tt></li>
<li><tt>priv-to-subaddr-odd</tt></li>
<li><tt>priv-to-tag</tt></li>
</ul>
<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Mixing of private and public id elements is valid.</td></tr></table></div>
<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 presentation and the numbering plan datatypes of private ids become visible when a private id number or name is valid.</td></tr></table></div>
<h1><a name="PrivateRepresentationofPartyInformation-ExampleDialplans"></a>Example Dialplans</h1>
<h3><a name="PrivateRepresentationofPartyInformation-Settingtheprivatecallingname"></a>Setting the private calling name</h3>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">[incoming_context]
; (optionally) Setting the public calling name as usual
exten => 10,1,ExecIf($[${CALLERID(num)}=20]?
Set(CALLERID(name)=Peter Public):)
exten => 10,n,ExecIf($[${CALLERID(num)}=30]?
Set(CALLERID(name)=Mark Public):)
;using the Dial() b-option to execute a pre-dial subroutine on the target channel
exten => 10,n,Dial(SIP/10, ,b(privatecallingname))
exten => 10,n,Hangup()
; setting the private calling name (on target/dialed-to channel only)
; Since the Pre-dial CALLEE subroutine is acting on the target channel the
; CONNECTEDLINE parameter has to be set instead of the CALLERID parameter
; This might look strange at first sight but the CALLERID of the dialing channel ; becomes the CONNECTEDLINE of the dialed-to channel since the the Dial()-
; application copies the caller id of the dialing channel to the connected id of the
; target channel
exten => 10,n(privatecallingname), NoOp()
exten => 10,n,ExecIf($[${CONNECTEDLINE(num}=20]?
Set(CONNECTEDLINE(priv-name,i)=Peter Private):)
exten => 10,n,ExecIf($[${CONNECTEDLINE(num}=30]?
Set(CONNECTEDLINE(priv-name,i)=Mark Private):)
; Of course in a more general approach the private calling name should be determined
; by a database lookup instead. For this purpose the database would have to provide
; user-specific (identified by the called party number, i.e. ${EXTEN}) private party
; names of the calling party (identified by the calling party number,
; i.e. ${CONNECTEDLINE(num)})
exten => 10,n,Return()</pre>
</div></div>
<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>The setting of a private redirecting-from name (if an internal diversion shall be indicated to the forwarded-to party) can be done similar in the same context.</td></tr></table></div>
<h3><a name="PrivateRepresentationofPartyInformation-Settingtheprivateconnectedname"></a>Setting the private connected name</h3>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">[globals]
CONNECTED_LINE_SEND_SUB = connectedline,s,1
CONNECTED_LINE_SEND_SUB_ARGS =,
[incoming context]
; Setting the public connected name or/and number as usual
exten => 10,1,Set(CONNECTEDLINE(name,i)=Donald Public)
exten => 10,1,Set(CONNECTEDLINE(num,i)=10)
; Generally invalidate the private connected name and number in case it is not
; explicitly set somewhere later. This prevents the technology channel which is
; receiving the internal connectedline update event from using a former set private
; connected id representation
exten => 10,n,Set(CONNECTEDLINE(priv-name-valid,i)=0)
exten => 10,n,Set(CONNECTEDLINE(priv-num-valid,i)=0)
exten => 10,n,Set(CONNECTEDLINE(source)=answer)
exten => 10,n,Dial(SIP/10, ,)
exten => 10,n,Hangup()
[connectedline]
exten => s,1, NoOp()
exten => s,n,GotoIf($[${CHANNEL(channeltype)}=Local]?out:)
; The following setting is done on the technology channel which signals
; the connected name by its corresponding protocol elements
; e.g., only signal the private connected name of callee '10' to caller '20'
exten => s,n,GotoIf($[${CALLERID(num)}!=20]?out:)
exten => s,n,GotoIf($[${CONNECTEDLINE(num)}!=10]?out:)
exten => s,n,Set(CONNECTEDLINE(priv-name)=Donald Private)
; Of course in a more general approach the private connected name should be
; determined by a database lookup instead. For this purpose the database would have
; to provide user-specific (identified by the destination of the connectedline update
; event, i.e. ${CALLERID(num)}) private party names which represents the
; originator of the connectedline update event (i.e. identified by
; ${CONNECTEDLINE(num)})
exten => s,n(out),Return()</pre>
</div></div>
<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Setting the private <tt>redirecting-from</tt> or <tt>redirecting-to</tt> names (if an internal diversion shall be indicated to the <tt>forwarded-to</tt> party or a diversion signalling shall be manipulated towards an involved subscriber) can be done similar using the <tt>REDIRECTING_SEND_SUB</tt> subroutine.</td></tr></table></div>
</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/Private+Representation+of+Party+Information">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/Private+Representation+of+Party+Information?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>