XMPP API

From OnSIP Developer Wiki
Jump to: navigation, search

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:

Service Architecture

Getting Started

Check out the demo if you have an OnSIP account.

Before you begin

  1. be sure to have an OnSIP account that you have your username/password for
  2. see the Development Tools section below for information on installing Psi and X-Lite
  3. 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

Junction Networks XMPP Component Services

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:

  1. under the General menu item click 'account setup'
  2. the "Psi: Jabber Accounts" pane should open; click "Add"
  3. 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"
  4. you should see the "Psi: Account Properties" pane.
    • jid: <your_sip_address>
    • password: <your_web_admin_password>
  5. Press 'save' and you should see the account appear in the Psi buddy list.
  6. 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.

Personal tools