Google Talk for Developers

Voicemail

This document describes the XMPP extension used by Google Talk to enable users to send voicemail messages to another chat client.

Note: This extension is not intended to become a standard and is subject to change.

Table of Contents

  • Introduction
  • First Try: Request Voicemail Support on Your Recipient's Server
  • Second Try: Request Your Own Voicemail JID
  • About Google Talk Extensions
  • Introduction

    Google Talk enables you to send a voicemail message to another user in a two different ways. If the other user's server supports the voicemail extension, you can request a voicemail JID that server, record a message, and expect that they will receive it. If the other user's server does not support this functionality but yours does (as Google Talk does), you can instead request your own voicemail JID, record a message, and your server will email it to the other user (specifically, to the email address of their bare JID).

    Note: The audio session established here between the client and the server is similar to but not a standard Jingle audio session. It is based on the open source libjingle code. Therefore, do not expect that many chat servers other than Google Talk will support this extension. To support this extension on a server, you should incorporate the libjingle code to handle JID audio sessions. Within this document we will refer to it as a "libjingle audio session".

    First Try: Request Voicemail Support on Your Recipient's Server

    Your first step is to query whether the message recipient's server supports this extension. To determine support, send a service discovery request addressed to the other user's bare JID, requesting the voicemail node, as shown here:

    Example 1. Hamlet requests Fortinbras's voicemail JID

    <iq type='get'             
        to='fortinbras@norway.lit'
        id='voicemail-1'>
        <query xmlns=' http://jabber.org/protocol/disco#items' node='voicemail'/>         
    </iq>

    If the other server does not support voicemail caching, it will return an IQ error, and you should next request your own voicemail JID as described in the section Second Try. Otherwise, the server will return the recipient's voicemail JID as shown here:

    Example 2. Fortinbras's server returns his voicemail JID

    <iq type='result'             
        from='fortinbras@norway.lit'             
        to='hamlet@denmark.lit'
        id='voicemail-1'>             
        <query xmlns=' http://jabber.org/protocol/disco#items' node='voicemail'>
            <item jid='hamlet@denmark.lit/voicemail' />             
        </query>
    </iq>

    Use the returned voicemail JID to initiate a libjingle audio session as described in Negotiating a libjingle Audio Session.

    Second Try: Request Your Own Voicemail JID

    If your friend's server does not support this extension, you can request your own voicemail JID from your own server and use it to record and forward a message to your friend. To query whether your own server supports the voicemail extension, send a service discovery request to yourself, requesting the node outgoingvoicemail as shown here:

    Example 3. Hamlet requests his own voicemail JID from his server

    <iq type='get'
        to='hamlet@denmark.lit'
        id='voicemail-2'>
        <query xmlns='http://jabber.org/protocol/disco#items' node='outgoingvoicemail'/>
    </iq>

    If your server does not support voicemail forwarding, it will return an IQ error and nothing more can be done. Otherwise, your server will return your own voicemail JID, which you can use to record your message, as described in the next step. The following stanza shows a successful reply to a request for your own voicemail JID.

    Example 4. Server returns Hamlet's voicemail JID

    <iq type='result'
        from='hamlet@denmark.lit'
        to='hamlet@denmark.lit/throne'
        id='voicemail-2'>
        <query xmlns=' http://jabber.org/protocol/disco#items' node='outgoingvoicemail'>
           <item jid='voicemail@denmark.lit/outgoingvoicemail' />
        </query>
    </iq>

    Negotiating a libjingle Audio Session

    Once you have successfully received a voicemail JID (either your own or the other user's), you will use it to negotiate a libjingle audio session with the server that sent it. To learn how to negotiate a libjingle audio session, read the libjingle voice chat documentation. (Note that this documentation does not describe the actual protocol; you are expected to use the libjingle code to negotiate and manage an audio chat.)

    As part of the session negotiation, the client should include a <regarding> element that specifies to whom the recorded message should be sent (this stanza must be added regardless of whether you're recording to your own or someone else's voicemail JID). This element includes a name attribute with the bare JID of the recipient (again, use the recipient's bare JID regardless of whether you're recording to your own or to his voicemail JID). The following code snippet from the session negotiation demonstrates the use of the <regarding> element.

    Example 5. Client specifies an email recipient for the completed voicemail

    <iq to='voicemail@denmark.lit' id='sessionaudio1' type='set'>
        <session xmlns='http://www.google.com/session'
                 type='initiate'
                 initiator='hamlet@denmark.lit'
                 id='a35e4n3g4n82'>
            <regarding xmlns='http://www.google.com/session/voicemail'
                       name='fortinbras@norway.lit'/>
    ...

    After you have negotiated the connection and recorded the message, end the session and the server should send the message to the recipient. For messages stored to your own voicemail JID/server, the server will email the message to the address specified by the <regarding> element's name attribute. Messages stored to the recipient's voicemail JID/server will be delivered in an appropriate way by that server.

    About Google Talk Extensions

    Extensibility is one of the greatest strengths of XMPP, the IETF standard protocol on which Google Talk is built. While XMPP itself defines a bare set of features, the protocol encourages third parties to develop their own extensions. During the development of Google Talk, we found it useful to define extensions to implement features not already found in XMPP or any of its currently defined extensions.The protocol defined in this document is currently used by the Google Talk clients and servers. However, note that it is not currently part of a proposed standardized extension, and therefore may change as we work to standardize these features.

    Authentication required

    You need to be signed in with Google+ to do that.

    Signing you in...

    Google Developers needs your permission to do that.