A samples based guide to working with OnSIP's XMPP API for call events. What we are featuring in this doc are the necessary steps to have XMPP PubSub notify us of call events. When we say call events we are talking about the following:
REQUESTED for incoming calls
CREATED For outgoing calls
CONFIRMED For calls answered (including the case of a call being answered by voicemail)
RETRACT Call hangup
Additionally, towards the end of this document there is an xml snippet for creating / setting up a call.
This tool will allow you to insert xml stanzas directly into a utility window (Tools -> XML Console). The idea is that whatever jabber framework is used to develop against OnSIP's XMPP API, the stanza's generated by that framework should roughly look like the snippets below.
NOTE: Before starting, you need to make sure that in the 'Psi: Account Properties' window under Accounts, you checked off 'Use hostname as resource' and explicitly set the resource to psi. That's in order to make these samples work
A working implementation of OnSIP's XMPP API can be found in this javascript based click-2-call Chrome Extension
- Connect to XMPP Server
- Authorize - authorization needs to be done hourly
- Subscribe / Configure - If not already subscribed to the node, then call Subscribe. Otherwise configure to resubscribe or update subscription.
I typically re-subscribe whenever I re-authorize, so about once an hour.
Request
<iq to='commands.auth.xmpp.onsip.com' type='set' id='5020' xmlns='jabber:client'>
<command xmlns='http://jabber.org/protocol/commands' node='authorize-plain'>
<x xmlns='jabber:x:data' type='submit'>
<field var='sip-address'>
<value>hiro@example.onsip.com</value>
</field>
<field var='password'>
<value>webpassword12345</value>
</field>
<field var='auth-for-all'>
<value>true</value>
</field>
<field var='jid'>
<value>hiro@example.onsip.com/psi</value>
</field>
</x>
</command>
</iq>
Response
<iq from="commands.auth.xmpp.onsip.com" type="result" id="5020" to="hiro@example.onsip.com/psi" >
<command xmlns="http://jabber.org/protocol/commands" status="completed" node="authorize-plain" sessionid="bc78d31e1078dd54d1f8d786d36fa9b1" >
<note type="info" >JID 'hiro@example.onsip.com' has been authorized to access resources for SIP Address(es) 'hiro@example.onsip.com,hiro_marketing@example.onsip.com,hiro_support@example.onsip.com,camp_land_1@example.onsip.com,camp_land_2@example.onsip.com' until 2012-11-13T16:09:58Z</note>
<x xmlns="jabber:x:data" type="result" >
<field type="fixed" var="expires" >
<value>2012-11-13T16:09:58Z</value>
</field>
<field type="fixed" var="sip" >
<value>hiro@example.onsip.com</value>
</field>
<field type="fixed" var="sip" >
<value>hiro_marketing@example.onsip.com</value>
</field>
<field type="fixed" var="sip" >
<value>hiro_support@example.onsip.com</value>
</field>
<field type="fixed" var="sip" >
<value>hiro_land_1@example.onsip.com</value>
</field>
<field type="fixed" var="sip" >
<value>camp_land_2@example.onsip.com</value>
</field>
</x>
</command>
</iq>
Request
<iq to='pubsub.active-calls.xmpp.onsip.com' type='set' id='5017' xmlns='jabber:client'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscribe node='/me/hiro@example.onsip.com' jid='hiro@example.onsip.com/psi'/>
</pubsub>
</iq>
Response
<iq from="pubsub.active-calls.xmpp.onsip.com" type="result" id="5017" to="hiro@example.onsip.com/psi" >
<pubsub xmlns="http://jabber.org/protocol/pubsub">
<subscription subscription="pending" jid="hiro@example.onsip.com/psi" />
</pubsub>
</iq>
<message from="pubsub.active-calls.xmpp.onsip.com" to="hiro@example.onsip.com/psi" >
<event xmlns="http://jabber.org/protocol/pubsub#event">
<subscription node="/me/hiro@example.onsip.com" subscription="subscribed" jid="hiro@example.onsip.com/psi" />
</event>
</message>
http://xmpp.org/extensions/xep-0060.html#subscriber-configure
Request
<iq to='pubsub.active-calls.xmpp.onsip.com' type='set' id='5021' xmlns='jabber:client'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<options node='/me/hiro@example.onsip.com' jid='hiro@example.onsip.com/psi' subid='548C825398B51'>
<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#expires'>
<value>Wed Nov 14 2012 12:50:00 GMT-0500 (EST)</value>
</field>
</x>
</options>
</pubsub>
</iq>
Response
<iq from="pubsub.active-calls.xmpp.onsip.com" type="result" id="5021" to="hiro@example.onsip.com/psi" />
Request
<iq to='pubsub.active-calls.xmpp.onsip.com' type='get' id='5016' xmlns='jabber:client'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscriptions node='/me/hiro@example.onsip.com'/>
</pubsub>
</iq>
Response
<iq from="pubsub.active-calls.xmpp.onsip.com" type="result" id="5016" to="hiro@example.onsip.com/psi" >
<pubsub xmlns="http://jabber.org/protocol/pubsub">
<subscriptions>
<subscription subscription="subscribed" subid="548C825398B51" jid="hiro@example.onsip.com/psi" />
</subscriptions>
</pubsub>
</iq>
Request
<iq type='set' to='pubsub.active-calls.xmpp.onsip.com' id='unsub1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<unsubscribe node='/me/hiro@example.onsip.com' subid="548C825398B51" jid="hiro@example.onsip.com/psi" />
</pubsub>
</iq>
Does not require any sort of authorization or subscription. This is an adhoc command. Once executed, your phone will ring.
When working on a Click-2-Call type of application:
In Click-2-Call, the end user of an application will click a phone number in an application such as a website. That application will send an XMPP request like the one below to intiate the call setup. Upon receipt of this request, our SIP Servers will execute a call setup by calling out to all of the end user's registered phones with the caller id showing call setup. When the end user picks up the phone, the call is then made to the phone number that was selected in the application.
Given this workflow, an application that is also subscribed to call events will recieve the incoming call setup event. To suppress call setup notifications from the end user, it's possible for custom built applications to utilize the call-setup-id field in the submission below. The value in the call-setup-id field will be delivered back down to the client in an incoming active call event subscription. The logic in the end user's application should compare the call-setup-id in this ad hoc command with the call-setup-id received in the incoming active call event. If the call setup ids match, then it's part of the call setup and the notification can be suppressed, otherwise the call is a legitimate incoming call from another user agent.
Request
<iq to='commands.active-calls.xmpp.onsip.com' type='set' id='5018' xmlns='jabber:client'>
<command xmlns='http://jabber.org/protocol/commands' node='create'>
<x xmlns='jabber:x:data' type='submit'>
<field var='to'>
<value>sip:18008013381@junctionnetworks.com</value>
</field>
<field var='from'>
<value>sip:hiro@example.onsip.com</value>
</field>
<field var='call-setup-id'>
<value>1352821510415667</value>
</field>
</x>
</command>
</iq>
Response
<iq from="commands.active-calls.xmpp.onsip.com" type="result" id="5018" to="hiro@example.onsip.com/psi" >
<command xmlns="http://jabber.org/protocol/commands" status="completed" node="create" sessionid="9d0aa91699f9c443c3c8626d8abb7067" >
<x xmlns="jabber:x:data" type="result" >
<field type="fixed" var="call-setup-id" >
<value>1352821510415667</value>
</field>
</x>
</command>
</iq>