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 you to place calls, send sms, download voicemails/recorded messages, and search the various folders of your Google Voice Accounts. You can use the Python API or command line script to schedule calls, check for new received calls/sms, or even sync your recorded voicemails/calls. Works for Python 2 and Python 3


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.


>>> 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

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
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
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)
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
Logs out an instance and makes sure it does not still have a session
Returns a list of Phone instances attached to your account.
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
Dict of current Google Voice settings
Returns special identifier for your session (if logged in)


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
Returns a list of all messages in this folder


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)
Disables this phone
Enables this phone for usage


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
Moves this message to the Trash. Use message.delete(0) to move it out of the Trash.
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 this message as read. Use message.mark(0) to mark it as unread.
Star this message. Use message.star(0) to unstar it.


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'
Returns the parsed json information after calling the XMLParser
Returns associated Folder instance for given page (self.name)

Table Of Contents

Previous topic


Next topic

Change Log

This Page