API Reference

This project aims to bring the power of the Google Voice API to the Python language in a simple, easy-to-use manner. Currently it allows one to place calls, send sms, download voicemails/recorded messages, and search the various folders of Google Voice Accounts. Use the Python API or command line script to schedule calls, check for new received calls/sms, or even sync recorded voicemails/calls.

Voice

In addition to the methods below, Voice instances have several special methods for gathering information from folders in the Google Voice service. These methods are:

  • inbox - Recent, unread messages

  • starred - Starred messages

  • all - All messages

  • spam - Messages likely to be spam

  • trash - Deleted messages

  • voicemail - Voicemail messages

  • sms - Text messages

  • recorded - Recorced messages

  • placed - Outgoing messages

  • received - Incoming messages

  • missed - Messages not received

All of these special methods operate the same way. When they are called, they parse the feed from the Google Voice service and return a Folder instance. After they have been called, you can grab the JSON and HTML data directly.

Usage:

>>> voice.inbox()       # Parses feed and returns Folder instance
... <Folder inbox (9)>
>>> voice.inbox.json    # Raw JSON data
... u'{"messages":{"14ef89...'
>>> voice.inbox.html    # Raw HTML data
... u'\n\n  \n<div id="14fe89...'
>>> voice.inbox.folder  # Just returns Folder instance
... <Folder inbox (9)>
class googlevoice.Voice

Main voice instance for interacting with the Google Voice service Handles login/logout and most of the baser HTTP methods

archive(msg, archive=1)

Archive the specified message by removing it from the Inbox.

call(outgoingNumber, forwardingNumber=None, phoneType=None, subscriberNumber=None)

Make a call to an outgoingNumber from your forwardingNumber (optional). If you pass in your forwardingNumber, please also pass in the correct phoneType

cancel(outgoingNumber=None, forwardingNumber=None)

Cancels a call matching outgoing and forwarding numbers (if given). Will raise an error if no matching call is being placed

property contacts

Partial data of your Google Account Contacts related to your Voice account. For a more comprehensive suite of APIs, check out http://code.google.com/apis/contacts/docs/1.0/developers_guide_python.html

delete(msg, trash=1)

Moves this message to the Trash. Use message.delete(0) to move it out of the Trash.

download(msg, adir=None)

Download a voicemail or recorded call MP3 matching the given msg which can either be a Message instance, or a SHA1 identifier. Saves files to adir (defaults to current directory). Message hashes can be found in self.voicemail().messages for example. Returns location of saved file.

login(email=None, passwd=None, smsKey=None)

Login to the service using your Google Voice account Credentials will be propmpted for if not given as args or in the ~/.gvoice config file

logout()

Logs out an instance and makes sure it does not still have a session

property phones

Returns a list of Phone instances attached to your account.

search(query)

Search your Google Voice Account history for calls, voicemails, and sms Returns Folder instance containting matching messages

send_sms(phoneNumber, text)

Send an SMS message to a given phoneNumber with the given text message

property settings

Dict of current Google Voice settings

property special

Returns special identifier for your session (if logged in)

Folder

class googlevoice.util.Folder(voice, name, data)

Folder wrapper for feeds from Google Voice Attributes are:

  • totalSize: int (aka __len__)

  • unreadCounts: dict

  • resultsPerPage: int

  • messages: list of Message instances

property messages

Returns a list of all messages in this folder

Phone

class googlevoice.util.Phone(voice, data)

Wrapper for phone objects used for phone specific methods Attributes are:

  • id: int

  • phoneNumber: i18n phone number

  • formattedNumber: humanized phone number string

  • we: data dict

  • wd: data dict

  • verified: bool

  • name: strign label

  • smsEnabled: bool

  • scheduleSet: bool

  • policyBitmask: int

  • weekdayTimes: list

  • dEPRECATEDDisabled: bool

  • weekdayAllDay: bool

  • telephonyVerified

  • weekendTimes: list

  • active: bool

  • weekendAllDay: bool

  • enabledForOthers: bool

  • type: int (1 - Home, 2 - Mobile, 3 - Work, 4 - Gizmo)

disable()

Disables this phone

enable()

Enables this phone for usage

Message

class googlevoice.util.Message(folder, id, data)

Wrapper for all call/sms message instances stored in Google Voice Attributes are:

  • id: SHA1 identifier

  • isTrash: bool

  • displayStartDateTime: datetime

  • star: bool

  • isSpam: bool

  • startTime: gmtime

  • labels: list

  • displayStartTime: time

  • children: str

  • note: str

  • isRead: bool

  • displayNumber: str

  • relativeStartTime: str

  • phoneNumber: str

  • type: int

delete(trash=1)

Moves this message to the Trash. Use message.delete(0) to move it out of the Trash.

download(adir=None)

Download the message MP3 (if any). Saves files to adir (defaults to current directory). Message hashes can be found in self.voicemail().messages for example. Returns location of saved file.

mark(read=1)

Mark this message as read. Use message.mark(0) to mark it as unread.

star(star=1)

Star this message. Use message.star(0) to unstar it.

XMLParser

class googlevoice.util.XMLParser(voice, name, datafunc)

XML Parser helper that can dig json and html out of the feeds. The parser takes a Voice instance, page name, and function to grab data from. Calling the parser calls the data function once, sets up the json and html attributes and returns a Folder instance for the given page:

o = XMLParser(voice, 'voicemail', lambda: 'some xml payload')
o()
<Folder ...>
o.json
'some json payload'
o.data
'loaded json payload'
o.html
'some html payload'
property data

Returns the parsed json information after calling the XMLParser

property folder

Returns associated Folder instance for given page (self.name)