XMPP API
From OnSIP Developer Wiki
Contents |
Overview
Introduction
The OnSIP XMPP API is an XMPP/PubSub based API that allows developers to receive push notifications for various events inside the OnSIP system. Events include information regarding current call state and user agent state for SIP addresses inside of OnSIP. The other side of the API, the Ad-Hoc commands, allow for connected XMPP clients to perform realtime call control for active calls inside of OnSIP.
We always write APIs for our own internal projects and then open our APIs to any customer or third party developer. Existing applications written on top of the XMPP API include the my.OnSIP portal and the OnSIP TAPI driver.
RFC & XEP Implementations
The Junction Networks XMPP API implements features from the following list of XMPP standards:
- RFC 3920: XMPP Core
- RFC 3921: XMPP Instant Messaging and Presence
- XEP 0004: Data Forms
- XEP 0030: Service Discovery
- XEP 0050: Ad-Hoc Commands
- XEP 0060: Publish-Subscribe (PubSub)
- XEP 0147: XMPP URI Scheme Query Components
- XEP 0144: Roster Item Exchange
- XEP 0248: PubSub Collection Nodes
Service Architecture
Getting Started
Check out the demo if you have an OnSIP account.
Before you begin
- be sure to have an OnSIP account that you have your username/password for
- see the Development Tools section below for information on installing Psi and X-Lite
- be familiar with foundation concepts of XMPP, XMPP Service Discovery, and XMPP PubSub
Once you have acclimated yourself with the above concepts continue onto the Development Tools section for a description of which tools we suggest you install to begin working with the XMPP API.
After you have installed the necessary tools visit the appropriate page for the Junction Networks XMPP service you are developing against. The XMPP API services listed below are broken out by service type, either PubSub or commands.
Creating Your First Client
Read the following page for useful information about creating your first XMPP API client.
Junction Networks PubSub
Please be sure to be comfortable with XMPP Pubsub and Pubsub collection nodes (see above) before trying to tackle this.
General PubSub Architecture
----------------------------------------------------------------- | PubSub Node Descriptions | ----------------------------------------------------------------- | Node Name | Leaf | Collection | Redirect | ----------------------------------------------------------------- | | | / X | | /<sipdomain> | X | | /<sipdomain>/<user> X | | | | | | | | /me/<jid> X <--| | | | /me/<jid>/<sipdomain> X <--| | | | |---------------------------------------------------------------|
-------------------------------------------------------------------------------------------------------------------- | PubSub Node Tree | -------------------------------------------------------------------------------------------------------------------- | | | ------------- ------------- | | ( /me/<jid-A> ) ( /me/<jid-B> ) | | ------------- ------------- | | / \ \ | | / \ \ | | / \ \ | | --------------------------- --------------------------- --------------------------- | | ( /me/<jid-A>/<sip-domain-1> ) ( /me/<jid-A>/<sip-domain-2> ) ( /me/<jid-B>/<sip-domain-2> ) | | --------------------------- --------------------------- --------------------------- | | / \ / \ | | / \ / \ | | / \ / \ | | ------------------------- ------------------------- ------------------------- | | ( /<sip-domain-1>/<user-a> ) ( /<sip-domain-2>/<user-b> ) ( /<sip-domain-2>/<user-c> ) | | ------------------------- ------------------------- ------------------------- | | | | | | | |-- <item-1> |-- <item-1> |-- <item-1> | | |-- <item-2> |-- <item-2> |-- <item-2> | | |-- ... |-- ... |-- ... | | |-- <item-N> |-- <item-N> |-- <item-N> | | | --------------------------------------------------------------------------------------------------------------------
Handling Redirects
<iq type='set' id='subroot1'
from='bob@example.com' to='pubsub.any-service.xmpp.onsip.com'
xmlns='jabber:client'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscribe node='/'
jid='bob@example.com'/>
</pubsub>
</iq>
<iq from="pubsub.any-service.xmpp.onsip.com" type="error" xml:lang="en" to="bob@example.com/bob-client" id="subroot1" >
<pubsub xmlns="http://jabber.org/protocol/pubsub">
<subscribe node="/" jid="bob@example.com" />
</pubsub>
<error type="modify" code="302" >
<redirect xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
<text xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">xmpp:pubsub.any-service.xmpp.onsip.com?;node=/me/bob@example.com</text>
</error>
</iq>
<iq type='set' id='subroot2'
from='bob@example.com' to='pubsub.any-service.xmpp.onsip.com'
xmlns='jabber:client'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscribe node='/junctionnetworks.com'
jid='bob@example.com'/>
</pubsub>
</iq>
<iq from="pubsub.any-service.xmpp.onsip.com" type="error" xml:lang="en" to="bob@example.com/bob-client" id="subroot2" >
<pubsub xmlns="http://jabber.org/protocol/pubsub">
<subscribe node="/junctionnetworks.com" jid="bob@example.com" />
</pubsub>
<error type="modify" code="302" >
<redirect xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
<text xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">xmpp:pubsub.any-service.xmpp.onsip.com?;node=/me/bob@example.com/junctionnetworks.com</text>
</error>
</iq>
PubSub Services
- pubsub.active-calls.xmpp.onsip.com
- pubsub.user-agents.xmpp.onsip.com
- pubsub.voicemail.xmpp.onsip.com
- pubsub.preferences.xmpp.onsip.com
- pubsub.directories.xmpp.onsip.com
- pubsub.recent-calls.xmpp.onsip.com
Junction Networks XMPP Component Services
- commands.auth.xmpp.onsip.com
- commands.active-calls.xmpp.onsip.com
- commands.user-agents.xmpp.onsip.com
- commands.voicemail.xmpp.onsip.com
- commands.preferences.xmpp.onsip.com
- commands.directories.xmpp.onsip.com
- commands.recent-calls.xmpp.onsip.com
- commands.rosters.xmpp.onsip.com
OnSIP XMPP API Client Libraries
Development Tools
Below are a few tools useful when developing against the XMPP API:
Psi
Psi XMPP Client After downloading and installing Psi setup your OnSIP jabber account:
- under the General menu item click 'account setup'
- the "Psi: Jabber Accounts" pane should open; click "Add"
- give your account a name (it doesn't matter what you call it), be sure the "register new account" box is UNCHECKED, and click "Add"
- you should see the "Psi: Account Properties" pane.
- jid: <your_sip_address>
- password: <your_web_admin_password>
- Press 'save' and you should see the account appear in the Psi buddy list.
- Right click the account name and in the menu choose "Status" > "Online"
That should get you signed online. You can close any of the panes that pop up asking you to publish your personal information, they are irrelevant at this time.
(note: If you have the Psi XML console open when you execute this last step, or any other jabber request, you can view the XML requests and response between Psi and the server. The XML console should be available under the 'Tools' menu item)
X-Lite
X-Lite Softphone Follow this knowledgebase article for detailed instructions on setting up your X-Lite client.
