Voicemail Pubsub
From OnSIP Developer Wiki
Contents |
Overview
The voicemail pubsub service allows subscribed users to receive updates regarding the status of their voicemail account(s), e.g. added, deleted, or moved voicemail messages.
JID
pubsub.voicemail.xmpp.onsip.com
Subscription Request/Response Examples
There are three node levels that a user can subscribe to:
- /me/jid
- /me/jid/voicemail-domain
- /voicemail-domain/voicemail-user
Different results may be generated depending upon which node is subscribed to.
Please note that subscribing to '/' will redirect your subscribtion request to '/me/jid', while subscribing to '/voicemail-doman' will similarly redirect your subscribtion request to '/me/jid/voicemail-domain'.
Subscribe to /me/jid level
Subscription requests to the /me/jid level will subscribe you to all the voicemail boxes you are authorized for, across all domains.
For example, assume that your jid is foo@example.com. Further, assume that foo@example.com is auth'd for 2 SIP addresses, foo@example.com and manager@acme.com. Each of these SIP addresses is assigned a voicemail box; the voicemail address for foo@example.com is vm_foo@example.com, and the voicemail address for manager@acme.com is vm_manager@acme.com. If you make a subscription request to the node /me/foo@example.com, you will be subscribed to both /example.com/vm_foo and /acme.com/vm_manager.
Subscription Request
<iq type='set' id='sub1'
from='foo@example.com' to='pubsub.voicemail.xmpp.onsip.com'
xmlns='jabber:client'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscribe node='/me/foo@example.com' jid='foo@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
The immediate response from pubsub.voicemail.xmpp.onsip.com will always be a subscription "pending":
<iq from="pubsub.voicemail.xmpp.onsip.com" type="result" to="foo@example.com" id="sub1">
<pubsub xmlns="http://jabber.org/protocol/pubsub">
<subscription node="/me/foo@example.com" subscription="pending" jid="foo@example.com" />
</pubsub>
</iq>
Subscription Notification from PubSub
Upon successful subscription to a node, you will receive a subscription "subscribed" response:
<message from="pubsub.voicemail.xmpp.onsip.com" to="foo@example.com" >
<event xmlns="http://jabber.org/protocol/pubsub#event">
<subscription node="/me/foo@example.com" subscription="subscribed" jid="foo@example.com" />
</event>
</message>
Subscription Failure Notification from PubSub
Upon failure to subscribe to a node, you will receive a subscription "none" response. Subscription failure notifications are generated when you try to subscribe to nodes that you are not auth'd for. IMPORTANT REMINDER: you must first authenticate with pubsub.auth.xmpp.onsip.com before you can subscribe to a node.
<message from="pubsub.voicemail.xmpp.onsip.com" to="foo@example.com" >
<event xmlns="http://jabber.org/protocol/pubsub#event">
<subscription node="/me/foo@example.com" subscription="none" jid="foo@example.com" />
</event>
</message>
Subscribe to /me/jid/voicemail-domain level
Subscription requests to the /me/jid/voicemail-domain level will subscribe you to all the voicemail boxes you are authorized for on that particular domain.
For this example, assume that your jid is foo@example.com. Further, assume that foo@example.com is auth'd for 2 SIP addresses, foo@example.com and bar@example.com. Each of these SIP addresses is assigned a voicemail box; the voicemail address for foo@example.com is vm_foo@example.com, and the voicemail address for bar@example.com is vm_bar@example.com. If you make a subscription request to the node /me/foo@example.com/example.com, you will be subscribed to both /example.com/vm_foo and /example.com/vm_bar.
Request to PubSub
<iq type='set' id='sub1'
from='foo@example.com' to='pubsub.voicemail.xmpp.onsip.com'
xmlns='jabber:client'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscribe node='/me/foo@example.com/example.com' jid='foo@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>
</x>
</options>
</pubsub>
</iq>
The responses from pubsub.voicemail.xmpp.onsip.com for "pending", "subscribed", and "none" will be very similar to the responses documented above for the '/me/foo@example.com' node.
Subscribe to /voicemail-domain/voicemail-user level
Subscription requests to the /voicemail-domain/voicemail-user level will subscribe you to one particular voicemail box.
For this example, assume that your jid is foo@example.com. Further, assume that foo@example.com is auth'd for 2 SIP addresses, foo@example.com and bar@example.com. Each of these SIP addresses is assigned a voicemail box; the voicemail address for foo@example.com is vm_foo@example.com, and the voicemail address for bar@example.com is vm_bar@example.com. If you make a subscription request to the node /example.com/vm_foo, you will be subscribed to only /example.com/vm_foo.
Request to PubSub
<iq type='set' id='sub1'
from='foo@example.com' to='pubsub.voicemail.xmpp.onsip.com'
xmlns='jabber:client'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscribe node='/example.com/vm_foo' jid='foo@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>
</x>
</options>
</pubsub>
</iq>
The responses from pubsub.voicemail.xmpp.onsip.com for "pending", "subscribed", and "none" will be very similar to the responses documented above for the '/me/foo@example.com' node.
Pubsub Events
Pubsub returns event messages to the client when the state of a subscribed mailbox changes.
New voicemail notification
The following is a sample message that might be received when a new voicemail is received:
<message from="pubsub.voicemail.xmpp.onsip.com" to="foo@example.com" >
<event xmlns="http://jabber.org/protocol/pubsub#event">
<items node="/example.com/vm_foo" >
<item id="9f921c83b50f47e781920f2627019064" >
<voicemail xmlns="onsip:voicemail">
<mailbox>1</mailbox>
<caller-id>"Mom" <mom></caller-id>
<created>2009-03-04T13:24:01-05:00</created>
<duration>2</duration>
<labels>
<label>INBOX</label>
</labels>
</voicemail>
</item>
</items>
</event>
<headers xmlns="http://jabber.org/protocol/shim">
<header name="Collection" >/me/foo@example.com</header>
</headers>
</message>
Voicemail deleted notification
The following is a sample message that might be received when a voicemail is deleted:
<message from="pubsub.voicemail.xmpp.onsip.com" to="foo@example.com" >
<event xmlns="http://jabber.org/protocol/pubsub#event">
<items node="/example.com/vm_foo" >
<retract id="0f554a12e2f66454e78086a10cd75e74" />
</items>
</event>
<headers xmlns="http://jabber.org/protocol/shim">
<header name="Collection" >/me/foo@example.com</header>
</headers>
</message>
Mailbox label notification
The following is a sample message that might be received when a mailbox label (aka, folder) is added, deleted, or modified:
<message from="pubsub.voicemail.xmpp.onsip.com" to="foo@example.com" >
<event xmlns="http://jabber.org/protocol/pubsub#event">
<items node="/example.com/vm_foo" >
<item id="labels" >
<labels xmlns="onsip:voicemail">
<label>Family</label>
<label>INBOX</label>
</labels>
</item>
</items>
</event>
<headers xmlns="http://jabber.org/protocol/shim">
<header name="Collection" >/me/foo@example.com</header>
</headers>
</message>
