0.0.3.md

Preliminary documentation for v.0.0.3

v.0.0.3 will have significant breaking changes from 0.0.2, but I think it's for the best in the long run.

v.0.0.3 is not ready yet, but I will be updating this documentation as I work on it. This is mostly for me to keep track of what does what and how, but it will eventually become the docs for the next version.

GVClient.connect(method,options,callback)

• method (String,required): 'call', 'sms', or 'cancel' (cancels the most recent call)
• options (Object, required) : requires different properties, depending on method. The parameters are listed below, and the methods that each parameter works with are inside the curly braces:
  • forwardingNumber {call} (String or Array, required) : One of your Google Voice forwarding numbers. This can also be your Google Voice login ('[email protected]') to connect to Google Talk or have it ring in Gmail.
  • phoneType {call} (Integer, required) : the phone type of forwardingPhone. It can be one of the following values:
    • 1 - Home
    • 2 - Mobile
    • 3 - Work
    • 7 - Gizmo (this may not work anymore as Gizmo has been shut down by Google)
    • 9 - Google Talk
  • outgoingNumber {'call','sms'} (String or Array, required) : the number to connect the forwarding phone to or the number(s) to which the text message will be sent. outgoingNumber can be:
    • String {call, sms} - just one number to call/text
    • Array {sms} - to send a text message to multiple numbers, use an Array of Strings
  • text {sms} (String, optional, default = ' ') : The text message to send. If empty, it will default to ' '.
  • date {sms,call,cancel} (Array or Date, optional) : If a date parameter is included in options, the call/text/cancel will be scheduled for that time, if it is a future time. date can be:
    • an Array of the form [Year, Month, Day, Hour, Minute, Second, Millisecond] . This array must contain at least the year; the other parameters are optional. If a parameter is not specified, it will default to null. Therefore, [2011] will schedule the event for January 01, 2011 12:00 AM. [2011,05,01,null,30] will schedule the event for May 01, 2011 12:30AM.
    • a Date object : Using, for example, new Date()
  • overwrite {sms,cancel,call} (True/False, default = true) : This parameter is recognized only for scheduling requests (i.e. when there is a date property in options). The overwrite property specifies whether a scheduling request can unschedule an event that is already scheduled at the same time.
• callback (Function: function(status,body,response), optional) where
  • status (Integer) : a status code specifying the result of the request. The possible status codes are given in GVClient.STATUS_CODES. See "STATUS_CODES" below for more information.
  • body (Object or String) is one of the following:
    • Object formed from the JSON response from Google Voice, typically something like the following examples:
      • { ok: true, data: { code: 0 } }
      • { ok: false, error: 'Cannot complete call.' }
      • { ok: false, data: { code: 20 } }
    • String containing the HTML response from Google Voice (for cases when the body of the response doesn't contain JSON, or if the JSON couldn't be parsed)
  • response (http.ClientResponse) is the instance of Node's http.ClientResponse corresponding to that particular request. It is provided for cases where you would like to get more information about what went wrong (or right!) and act on it. Note that the response has a response.statusCode, which corresponds to the 3-digit HTTP response code. For cases when status is 600 (HTTP_ERROR), it is important to check the HTTP response status code to determine what went wrong.

GVClient.get(options,callback)

• options (String or Object, required): options can be a String, or one of two Object types:

  • to retrieve messages from one of the standard Google Voice labels, use one of the following Strings for options. Note that this will return ALL results of the given request type (equivalent to setting limit=-1 (see below)).

   	'history'
   	'inbox'
   	'spam'
   	'trash'
   	'starred'
   	'sms'
   	'voicemail'
   	'placed'
   	'missed'
   	'received'
   	'recorded'

  • to set a limit on the number of returned messages, use an Object for options with the following properties:
    • type (String, required) : one of the 11 Strings given above
    • limit (Integer, optional, default = -1) : limits the number of returned messages to a certain number, ordered by message time. So limit=1 will return the most recent message of the given request, and limit=10 will return the 10 most recent messages. If limit = -1, ALL messages will be returned (can be slow for very large message lists)
  • to just update GVClient.unreadCounts, use the 'counts' String for options. In this case, the messages Array passed to callback will be empty.
  • to search for messages matching a particular search string, use an Object for options with the following properties:
    • query (String) : This last form retrieves messages that match the given query in some way. The search function is entirely implemented by Google Voice, so the search results are the same as would be returned by searching from the Google Voice web interface.
    • limit (Integer, optional, default = -1) : see above for explanation

• callback (Function function(status, messages) ):

  • status (Integer) : the status of the request. See "STATUS CODES" below for more information.

  • messages (Array) : an Array of message Objects. Each message object is formed from the JSON response from Google Voice; the format is therefore subject to change. At the time of this writing, an example message looked like this:

     	{ id: 'someStringIdentifier',
     	  phoneNumber: '+18005551212',
     	  displayNumber: '(800) 555-1212',
     	  startTime: '1305138033000',
     	  displayStartDateTime: '5/11/11 2:20 PM',
     	  displayStartTime: '2:20 PM',
     	  relativeStartTime: '3 weeks ago',
     	  note: '',
     	  isRead: true,
     	  isSpam: false,
     	  isTrash: false,
     	  star: false,
     	  labels: [ 'missed', 'all' ],
     	  type: 0,
     	  children: '' 
     	}

    • SMS messages (messages with 'sms' as one of the labels) have some additional properties and methods:
      • thread (Array) : an array of DOM elements (made with jsdom), each containing three child elements, corresponding to text, from, time
      • getValue(param) : a method for extracting one of the three parameters of a message DOM element. This is used with the DOM elements in thread to get
        • the relative time of the message: msgDOMelement.getValue('time')
        • the sender's identification: msgDOMelement.getValue('from')
        • the text message: msgDOMelement.getValue('text')
      • lastText (String) : the most recent text message in the SMS thread. Equivalent to thread[0].getValue('text').

GVClient.set(options,messageIDs,callback)

• options (String or Object, required): A String or one of two types of Objects:

  • To mark (un)read, (un)star, (un)archive, (un)spam, (un)trash, or delete messages(s), or (un)block the caller, use one of the following Strings:

   	'read' 			// mark messages as read
   	'unread' 		// mark messages as unread
   	'archive'		// archive messages
   	'unarchive'		// unarchive messages (move back to inbox)
   	'star'			// star messages
   	'unstar',		// remove star from messages
   	'spam', 		// mark messages as spam
   	'unspam' 		// unmark messages as spam
   	'deleteForever' // permanently deletes the message(s)
   	'toggleTrash' 	// calling this on a message will move it to the inbox if it is in the trash OR will move it to the trash if it is somewhere else
   	'block' 		// block the number associated with the message
   	'unblock' 		// unblock the number associated with the message

  • To add a note to the message, use an Object with the following property:
    • note (String, required) : a note to be saved with the message
    • NOTE: setting a note can only be done on one message at a time.
  • To forward a voicemail message, use an Object with the following properties:
    • forward (String or Array, required) : One email address string, or an Array of email addresses to forward the message to
    • subject (String, optional, default =' ') : The subject of the forwarded message
    • body (String, optional, default =' ') : The body of the email message
    • link (True/False, optional, default = false) : Whether or not to include a link to the voicemail message in the email
    • NOTE:
      • Only voicemails can be forwarded. Attempting to forward other messages will fail.
      • Only one message can be forwarded per request.

• messageIDs (String or Array, required) : unique Google Voice message ID(s). The message ID can be had from the message objects returned by GVClient.get() (discussed above)

  • The first set() approach described above (with a String) can set more than one message at a time:
    • use a String with the message ID to manipulate one message
    • use an Array of message ID Strings to manipulate multiple messages simultaneously
  • The other two set() methods (with an Object), for setting notes and forwarding messages, can only manipulate one message at a time:
    • Use a message ID String for these operations. If you pass an Array of message IDs, only the first message will be targeted.

• callback (Function function(status,body,response), optional) - a callback function that behaves identically to the callback in GVClient.connect(). See that section for more information.