Active-Calls Pubsub

From OnSIP Developer Wiki

Jump to: navigation, search


Note: Please review the First XMPP API client notes page before beginning any PubSub integration for important notes on configuring and managing subscriptions.


Contents

Overview

Active Calls pubsub allows for subscribing to evented data regarding the current calls of a SIP address. Data returned in the events may be used for call control purposes in the Active Calls command component or for other application specific usage.

PubSub Service JID

pubsub.active-calls.xmpp.onsip.com

Active Calls PubSub

Note: Please see this page regarding any questions you may have with the SIP terminology on this page


Warning: The id attribute of any item element should be considered private data. The only assumption that is safe to make is that the token will remain consistent across a single call for a single SIP UA. No other information, should be derived from the id attribute.

Subscription Request/Response Examples

Subscribe To JID Level

Request to pubsub.active-calls.xmpp.onsip.com 
<iq type='set' id='sub1'
    from='alice@example.com' to='pubsub.active-calls.xmpp.onsip.com'
    xmlns='jabber:client'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <subscribe node='/me/alice@example.com' jid='alice@example.com'/>
    <options>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
          <value>http://jabber.org/protocol/pubsub#subscribe_options</value>
        </field>
        <field var='pubsub#subscription_type'>
          <value>items</value>
        </field>
        <field var='pubsub#subscription_depth'>
          <value>all</value>
        </field>
        <field var='pubsub#expire'>
          <value>2010-11-02T22:00:00.0000000Z</value>
        </field>
      </x>
    </options>
  </pubsub>
</iq>
Pending Response from pubsub.active-calls.xmpp.onsip.com 
<iq from="pubsub.active-calls.xmpp.onsip.com" type="result" to="alice@example.com" id="sub1" >
  <pubsub xmlns="http://jabber.org/protocol/pubsub">
    <subscription node="/me/alice@example.com" subscription="pending" jid="alice@example.com" />
  </pubsub>
</iq>
Subsription Notification from pubsub.active-calls.xmpp.onsip.com 
<message from="pubsub.active-calls.xmpp.onsip.com" to="alice@example.com" >
  <event xmlns="http://jabber.org/protocol/pubsub#event">
    <subscription node="/me/alice@example.com" subscription="subscribed" jid="alice@example.com" />
  </event>
</message>

Events

In the following events the JID alice@example.com is subscribed to the active-call information at node /example.onsip.com/alice. The JID for alice has been authorized through the Auth Component for the OnSIP address alice@example.onsip.com

State Transitions

Each active-call event received represents a state transition for an ongoing call inside OnSIP. The following image depicts the possible state transitions of an ongoing call.

active-call_transitions.png

Event Elements

dialog-state 
indicates the current state of the call. The value may be either created, requested, or confirmed. A created call indicates one where the SIP address represented by the leaf node is the caller, a requested event is where the SIP address represented by the node is the callee, and a confirmed state simply refers to an active call, it is direction agnostic.
to-aor 
address of record of the callee, the to-aor may change between call branches (see branch below). The to-aor will only be found in requested and confirmed events.
call-id 
the SIP call ID of the active call. The call ID will remain the same across all forked branches of the call (see branch below)
from-uri 
the SIP URI of the caller, the from-uri is immutable across all call branches
to-uri 
the SIP URI of the callee, the to-uri is immutable across all call branches. The to-uri will always indicate the location dialed by the caller, i.e. named SIP address, extension, phone number, etc.
from-tag 
the SIP from-tag of the call, the from-tag is immutable across all call branches
to-tag 
the SIP to-tag of the call, the to-tag may vary from branch to branch, however once a branch answers the call, that branches to-tag will be the to-tag of the call. The to-tag will only be set when a call becomes confirmed.
branch 
the branch element can be used to identify forks of the same call to simultaneously ringing SIP endpoints. For instance: if alice@example.com has two SIP UAs registered and receives an inbound call from bob@bar.com, then alice@example.com will receive 2 requested events. Each event will of course have a unique item ID, however the call ID, from-tag, from-uri will both be the same. The key is to look at the branch element, a unique branch ID will exist for each forked leg of a call and there may be N different branches for a call. Once one endpoint answers the call that branch item will be republished as state confirmed, while the other branches that were NOT answered will be retracted. branch will only be set in requested and confirmed events.
call-setup-id 
if the call event is the result of a call create request from the Active-Calls Component then this field will match the return call-setup-id value of the initial call create request for the life of the initial call. The value of this field allows clients to associate pending call setups with the asynchronous active call events.

Item Publication

Call Created

The created event signifies the subscriber "alice" has created a new outbound call. In this example alice@example.onsip.com is calling bob@example.onsip.com 

<message from="pubsub.active-calls.xmpp.onsip.com" to="alice@example.com" >
  <event xmlns="http://jabber.org/protocol/pubsub#event">
    <items node="/example.onsip.com/alice" >
      <item id="b5879e23d6a92cc11f01a29e466f7bd2" >
        <active-call xmlns="onsip:active-calls">
          <dialog-state>created</dialog-state>
          <to-aor/>
          <call-id>NjEwOWU2ZTE5YzUwNjI0MjQ1ZGYwZjE0ZWVkNTA2NDU.</call-id>
          <from-uri>sip:alice@example.onsip.com</from-uri>
          <to-uri>sip:bob@example.onsip.com</to-uri>
          <from-tag>419cce6a</from-tag>
          <to-tag/>
          <branch/>
          <call-setup-id/>
        </active-call>
      </item>
    </items>
  </event>
  <headers xmlns="http://jabber.org/protocol/shim">
    <header name="Collection" >/me/alice@example.com</header>
  </headers>
</message>
Call Requested

The requested event signifies the subscriber "alice" has a new inbound call. In this example bob@example.onsip.com is calling alice@example.onsip.com 

<message from="pubsub.active-calls.xmpp.onsip.com" to="alice@example.com" >
  <event xmlns="http://jabber.org/protocol/pubsub#event">
    <items node="/example.onsip.com/alice" >
      <item id="6859babae582000ff963b29394ddb4b5" >
        <active-call xmlns="onsip:active-calls">
          <dialog-state>requested</dialog-state>
          <to-aor>alice@example.onsip.com</to-aor>
          <call-id>ZDU0YTJhMWEzZWI3NWNmNmRkZTBhN2VmZmRmMGNkNGQ.</call-id>
          <from-uri>sip:bob@example.onsip.com</from-uri>
          <to-uri>sip:alice@example.onsip.com</to-uri>
          <from-tag>53498145</from-tag>
          <to-tag/>
          <branch>z9hG4bK7bb6.4c45a015.0</branch>
          <call-setup-id/>
        </active-call>
      </item>
    </items>
  </event>
  <headers xmlns="http://jabber.org/protocol/shim">
    <header name="Collection" >/me/alice@example.com</header>
  </headers>
</message>
Call Confirmed

The confirmed event signifies the a previous call (either created or requested) has been answered and a SIP session is established. 

<message from="pubsub.active-calls.xmpp.onsip.com" to="alice@example.com" >
  <event xmlns="http://jabber.org/protocol/pubsub#event">
    <items node="/example.onsip.com/alice" >
      <item id="b5879e23d6a92cc11f01a29e466f7bd2" >
        <active-call xmlns="onsip:active-calls">
          <dialog-state>confirmed</dialog-state>
          <to-aor>alice@example.onsip.com</to-aor>
          <call-id>ZDU0YTJhMWEzZWI3NWNmNmRkZTBhN2VmZmRmMGNkNGQ.</call-id>
          <from-uri>sip:bob@example.onsip.com</from-uri>
          <to-uri>sip:alice@example.onsip.com</to-uri>
          <from-tag>53498145</from-tag>
          <to-tag>as11173b9d</to-tag>
          <branch>z9hG4bK7bb6.4c45a015.0</branch>
          <call-setup-id/>
        </active-call>
      </item>
    </items>
  </event>
  <headers xmlns="http://jabber.org/protocol/shim">
    <header name="Collection" >/me/alice@example.com</header>
  </headers>
</message>

Item Retraction

Item retraction signifies the end of the call due to one party hanging up or some other termination condition. 

<message from="pubsub.active-calls.xmpp.onsip.com" to="alice@example.com" >
  <event xmlns="http://jabber.org/protocol/pubsub#event">
    <items node="/example.onsip.com/alice" >
      <retract id="b5879e23d6a92cc11f01a29e466f7bd2" />
    </items>
  </event>
  <headers xmlns="http://jabber.org/protocol/shim">
    <header name="Collection" >/me/alice@example.com</header>
  </headers>
</message>

Call Create Event Flow

The following series of requests define a successful call create request made by JID alice@example.com. The call create setups up a call from sip:alice@example.onsip.com to sip:bob@example.onsip.com.

Please note due to various SIP user-agent implementations around how blind transfers are accepted Retracton 1 may occur before OR after Created Event.

1.) Requested Event

Initial call setup leg FROM sip:call-setup@onsip.com TO sip:alice@example.onsip.com. Note the call-setup-id value here. This value was returned in the call create ad-hoc response and will be propagated throuhgout both call legs. 

<message from="pubsub.active-calls.xmpp.onsip.com" type="headline" to="alice@example.com" >
  <event xmlns="http://jabber.org/protocol/pubsub#event">
    <items node="/example.onsip.com/alice" >
      <item id="8385a53483c235913008fc646a276de8" >
        <active-call xmlns="onsip:active-calls">
          <dialog-state>requested</dialog-state>
          <call-id>585ee3c92ce663df-30596@66.227.100.25</call-id>
          <from-uri>sip:call-setup@onsip.com;id=7DVyQUvE</from-uri>
          <to-uri>sip:alice@example.onsip.com</to-uri>
          <to-aor>alice@example.onsip.com</to-aor>
          <from-tag>f45c8f8c0758403c109fecafdfc5419f-cbaf</from-tag>
          <to-tag/>
          <branch>z9hG4bK5769.95290655.0</branch>
          <call-setup-id>7DVyQUvE</call-setup-id>
        </active-call>
      </item>
    </items>
  </event>
  <header name="Collection" >/me/alice@example.com</header>
</message>
2.) Confirmed Event 1

Confirmed event upon sip:alice@example.onsip.com answering initial call leg 

<message from="pubsub.active-calls.xmpp.onsip.com" type="headline" to="alice@example.com" >
  <event xmlns="http://jabber.org/protocol/pubsub#event">
    <items node="/example.onsip.com/alice" >
      <item id="8385a53483c235913008fc646a276de8" >
        <active-call xmlns="onsip:active-calls">
          <dialog-state>confirmed</dialog-state>
          <call-id>585ee3c92ce663df-30596@66.227.100.25</call-id>
          <from-uri>sip:call-setup@onsip.com;id=7DVyQUvE</from-uri>
          <to-uri>sip:alice@example.onsip.com</to-uri>
          <to-aor>alice@example.onsip.com</to-aor>
          <from-tag>f45c8f8c0758403c109fecafdfc5419f-cbaf</from-tag>
          <to-tag>d4063345</to-tag>
          <branch>z9hG4bK5769.95290655.0</branch>
          <call-setup-id>7DVyQUvE</call-setup-id>
        </active-call>
      </item>
    </items>
  </event>
  <header name="Collection" >/me/alice@example.com</header>
</message>
3.) Created Event

After sip:alice@example.onsip.com answers initial call leg, sip:alice@example.onsip.com is referred to sip:bob@example.onsip.com for the second call leg. 

<message from="pubsub.active-calls.xmpp.onsip.com" type="headline" to="alice@example.com" >
  <event xmlns="http://jabber.org/protocol/pubsub#event">
    <items node="/example.onsip.com/alice" >
      <item id="27484b2de810250e0b3c056ace0e4399" >
        <active-call xmlns="onsip:active-calls">
          <dialog-state>created</dialog-state>
          <call-id>MTI1NzJiMWRhNTQ1NTFjZjdmMmRkNDBkN2M0NWRlZDQ.</call-id>
          <from-uri>sip:alice@example.onsip.com</from-uri>
          <to-uri>sip:bob@example.onsip.com</to-uri>
          <to-aor/>
          <from-tag>af141272</from-tag>
          <to-tag/>
          <branch/>
          <call-setup-id>7DVyQUvE</call-setup-id>
        </active-call>
      </item>
    </items>
  </event>
  <header name="Collection" >/me/alice@example.com</header>
</message>
4.) Retraction 1

Initial call leg between sip:call-setup@onsip.com and sip:alice@example.onsip.com is torn down. 

<message from="pubsub.active-calls.xmpp.onsip.com" type="headline" to="alice@example.com" >
  <event xmlns="http://jabber.org/protocol/pubsub#event">
    <items node="/example.onsip.com/alice" >
      <retract id="8385a53483c235913008fc646a276de8" />
    </items>
  </event>
  <header name="Collection" >/me/alice@example.com</header>
</message>
5.) Confirmed Event 2

sip:bob@example.onsip.com has answered the call from sip:alice@example.onsip.com 

<message from="pubsub.active-calls.xmpp.onsip.com" type="headline" to="alice@example.com" >
  <event xmlns="http://jabber.org/protocol/pubsub#event">
    <items node="/example.onsip.com/alice" >
      <item id="27484b2de810250e0b3c056ace0e4399" >
        <active-call xmlns="onsip:active-calls">
          <dialog-state>confirmed</dialog-state>
          <call-id>MTI1NzJiMWRhNTQ1NTFjZjdmMmRkNDBkN2M0NWRlZDQ.</call-id>
          <from-uri>sip:alice@example.onsip.com</from-uri>
          <to-uri>sip:bob@example.onsip.com</to-uri>
          <to-aor>bob@example.onsip.com</to-aor>
          <from-tag>af141272</from-tag>
          <to-tag>8D8F5F05-7B8E5CFC</to-tag>
          <branch>z9hG4bKbe08.13f48d53.0</branch>
          <call-setup-id>7DVyQUvE</call-setup-id>
        </active-call>
      </item>
    </items>
  </event>
  <header name="Collection" >/me/alice@example.com</header>
</message>
6.) Retraction 2

Call leg two, between sip:bob@example.onsip.com and sip:alice@example.onsip.com has ended. 

<message from="pubsub.active-calls.xmpp.onsip.com" type="headline" to="alice@example.com" >
  <event xmlns="http://jabber.org/protocol/pubsub#event">
    <items node="/example.onsip.com/alice" >
      <retract id="27484b2de810250e0b3c056ace0e4399" />
    </items>
  </event>
  <header name="Collection" >/me/alice@example.com</header>
</message>
Retrieved from "http://wiki.onsip.com/docs/Active-Calls_Pubsub"
Personal tools