Skip to end of metadata
Go to start of metadata

This page describes how Party Identification will be supported on Sessions.

Sessions and Party Identification

The Session implementation will be modified to provide access to an IdentificationManager as defined in the existing The access to IdentificationManager will be as a facet of the Session proxy. The facet name will be defined in

As a refresher, the IdentificationManager interface defined in looks like this:

A new class, SipSessionIdentificationManager, will provide the servant for the IdentificationManager interface. It will have the necessary logic to add, update and provide access to the Party Identification class types defined in embedded into SessionCookies attached to a Session, as shown below:

Setting the Caller and Dialed values

So now the question becomes how the cookies get on the Session to begin with.

The approach will be to add configuration items for endpoints as shown below. There are two options shown. The first is to simply set the name and number fields in the endpoint configuration parameters if a single Caller record is adequate. For cases where multiple Caller records should be attached, the second approach is to define a list of references to identity records defined separately from the endpoint.

The configuration handler will create cookies (CallerCookie) for the Caller records and add them as default session cookies on the endpoint. Whenever the endpoint's session factory method is called, these CallerCookie objects will be attached to the new Session.

The Dialed information (which is just the number) will be set based on the "destination" parameter passed into the Session constructor.

Updating the Connected Line information

Based on Mark's discussion below, I propose we define a new type of indication in

This provides the means for the Bridge (via a SessionListener) to be notified of changes in identity of a Session so that IdentificationManager::updateConnectedLine() can be called for the bridged sessions.

Updating Redirecting info

We have two options here. We could add an extension point to the Routing Service for operations that redirect Sessions, and provide a hook that calls the IdentificationManager::updateRedirecting() for the Session being transferred. Or, we accept this is a basic routing service and just always do the updateRedirecting() call. I propose the latter for expediency.


  • Is using cookies to store the party identification actually beneficial? The SessionListener is the only place I see in the Session-related area that we push cookies to someone, and in this instance we also send a reference to the Session itself. The client would probably want to just access the IdentificationManager interface rather than parse through the cookies themselves. (Although it saves an RPC.)
  • Are the two alternative ways of setting the config information overly complicating things? (FYI, My approach to handle the case where a particular config file specified both a list and the two fields would be to add the individual Caller record defined in the endpoint to those in the list.)
  • Should there be be a way to default the party identification to something sensible if it is left off of configuration?
  • When a Session is being created for an outgoing call, do we just use the "destination" field for the Dialed number? Or do we get a cookie back (via an indicate or something) and THEN set the Dialed object? (Or maybe the latter is the ConnectLine information... I bet it is.) (EDIT: Mark answered this and I've incorporated into the above description.)
  • Does this task include handling outgoing interactions to pjsip to insure that the party identification information is sent to a dialed party? (EDIT: Mark pointed out that this is actually covered by another task.)
  • No labels


  1. Addressing the "What's not clear to me points"

    • I think having two ways isnt' really overly complicated. The majority of users will likely just set a callername and callernumber for their endpoints. Those rare few who need to either set multiple identities for one endpoint or set multiple endpoints to use the same identity can make use of the "type=callerid" sections in the config.

    I keep finding myself saying to just get rid of the ability to specify the identity in-line in the endpoint config. The problem is that I know most people will find the other way strange and convoluted and will appreciate the shortcut.

    I would recommend renaming the options to not have the word "caller" in them. This will make it more clear that you're establishing an identity for the endpoint not only when it is calling. For instance, when an endpoint is called, the identification settings can be used to populate the ConnectedLine information of the calling party.

    • I think using the endpoint name as both the caller name and number is sensible. With protocols that provide information about the caller in the call setup message (like SIP) this information could be used.
    • Yeah, you definitely mean ConnectedLine here. The Dialed number is literally the number dialed, and it can differ from where the call actually gets routed to.

    ConnectedLine information can be quite dynamic. So for instance, you could place a call to an endpoint that has an identity configured. Then when Asterisk SCF receives either a ringing or connected indication from the endpoint, the endpoint can send updated connected line information in that indication.

    (Warning, brainstorming out loud):
    So let's say that Alice calls Bob. For simplicity, we'll just work with names here instaead of names and numbers. Alice's endpoint is configured to have the identity "Alice" and Bob's endpoint is configured to have the identity "Bob." Both parties are using SIP.

    When Alice's session is created, the routing service hasn't been contacted yet, and so it's not possible to set any sort of ConnectedLine information for Alice.

    Now, the routing service routes the call to Bob. Bob's session is created, and his identity is set to be "Bob." Alice's session needs to be told of this change. When Alice's session is notified of the change, it can update its ConnectedLine to have an entry for "Bob."

    Now, Bob's phone receives an INVITE, and then sends a 180 Ringing indication. In that 180 Ringing, there is a P-Asserted-Identity header that changes his identity to "Bobby." Alice's session needs to be notified of this change. More specifically, she needs to be notified specifically that Bob's identity has changed, and not that a new identity should be added to her list of connected lines.

    If the 200 OK from Bob's phone or any other messages change his identity again, Alice needs to be informed each time.

    Conversely, Alice's phone could, at any point send a SIP UPDATE or, after the call has been established, either party could send a reINVITE that changes his or her identity. In other words, the need to listen for changes goes both ways on a call.

    It seems like the best way to handle this is to add a SessionListener called something like identityChanged(). The Bridge could use this opportunity to notify all other parties in the bridge that the identity of a party has changed by calling each session's IdentificationManager's updateConnectedLine().

    • If you make the change to the SessionListener I suggested above, then the only place you'd actually need to implement calls to updateConnectedLine is in the bridge when it gets an identityChanged() message. I think implementing that fits in with the task you have.

    As far as when to call identityChanged() is concerned, I think that may be a separate task (HYDRA-597 to be specific). That task, for SIP anyway, will consist of inspecting headers on incoming messages and calling identityChanged() if appropriate. The only part I'd suggest implementing right away would be call to identityChanged() on session creation since that won't require any deep knowledge of SIP to accomplish.

    • I think that falls into the territory of HYDRA-597.

    EDIT: My third bullet point had addressed a now-removed question about when/how to update ConnectedLine information. I think the idea is pretty sound, so I'm keeping it here.

    1. I agree with most of what Mark has said here (and a lot of this has been incorporated into the design already), but I've got one concern: it shouldn't be necessary for a bridge to be involved for two sessions to talk to each other and exchange party identity information. We may want to consider adding one or more operations to the SessionController interface to allow a session to indicate to its controller that its party identification information has changed; since our existing Session implementation also implement SessionController, it's possible for two of them to be directly connected and update each other. If a Bridge is involved, it would be the SessionController for both Sessions, and decide how/when to forward party identification updates between them.

      A minor point: passing the cookies to the SessionListeners would actually save two RPC calls for listeners that want them... one to checkedCast() the Session proxy into an IdentificationManager proxy, and one to invoke one of its methods (assuming that listener only wants one identity list... if it wants more than one, then that's more RPCs).