TG TwitterGram
Developer docs

TwitterGram web service

A simple API for posting short MP3s to Twitter.

Protocol
XML-RPC
Endpoint
http://rpc.twittergram.com/RPC2

twittergram.newPost

This web service is the back-end of the twittergram.com web app. It's an XML-RPC server running at http://rpc.twittergram.com/RPC2.

It implements a single XML-RPC entry-point, twittergram.newPost.

It takes 6 parameters; the first three are required, the last three are optional.

  1. username — a string
  2. password — a string
  3. bits — a base64-encoded binary
  4. flPostToMyAcct — a boolean
  5. metadata — a struct
  6. contentType — a string

Parameters

The username and password are for the user's Twitter account. This data passes through the web service; it is not retained.

The bits are the "gram" — the official limit is 200K, but there's a little bit of grace. (We'll accept slightly more than 200K.)

The boolean flPostToMyAcct, if true, says that the "tweet" should be posted not only to the global account for all TwitterGrams, but also to the user's account. It's an optional parameter; if it's not specified, it defaults to true.

metadata is a struct that can contain fields that have the same names as an RSS 2.0 item, such as title, link, description, category, source, etc. Very much like the Metaweblog API. Not all the elements are acceptable, but ones that aren't are ignored. (For example, enclosure.) All are optional, as is the struct itself. The title, if present, is used in forming the Twitter post. The remaining elements are retained and used to form feed(s). Note: in the initial implementation, only title is recognized.

contentType, an optional parameter added on 6/28/07, allows the caller to tell us which of two types the bits are: audio/mpeg or audio/x-wav. If not specified, it defaults to audio/mpeg. Some of the services that want to connect to twittergram.com only produce wavs. Hence this market-driven feature. :-)

Returns

The username and password must be valid for the MP3 to be retained. The service returns a string — if successful, the URL where the gram is stored. (We're using Amazon S3 for the storage, so it should be fairly reliable.)

Rate limits

There's a limit to the number of grams you can post over time. Not sure exactly what the limit will be — maybe no more than one every ten minutes? Interested in people's opinions. Note: in the initial implementation, the limit is no more than once per 60 seconds. This makes it easier for people who are testing clients to do their work. It will certainly go up over time.

The ideal client for this service, it seems, is Flash, because it can do the MP3 recording and has XML-RPC support.

twittergram.newPhonePost

This procedure facilitates phone-in TwitterGrams. It takes three parameters:

  1. phone number — a string
  2. bits — a base64-encoded binary
  3. contentType — a string

The phone number was obtained via Caller ID — it's the number of the person who phoned-in the TwitterGram. bits and contentType are as in the newPost call, and contentType is optional; if not specified, it defaults to audio/mpeg.

The user calls a special number, records a message, and the app calls this web service. We look up the phone number in a database of registered users (see the new sign-up page), and if we find it, we send the TwitterGram with the options that the user set for us.

twittergram.isPhoneRegistered

This procedure facilitates phone-in TwitterGrams. It takes one parameter:

  1. phone number — a string

It returns a boolean — true if the phone number is registered, false if it isn't.

A phone-in service should call this routine with the number the user is calling from (determined via Caller ID) when a call comes in, before allowing the user to record a gram. If it returns false, the service should tell the user to visit twittergram.com/phone to register the phone number.

Sample code

This example script posts a test TwitterGram from my account with a title, and puts the URL of the MP3 file on the clipboard. 

local (server = "xmlrpc://rpc.twittergram.com/RPC2")
local (bits = file.readwholefile ("macintosh hd:testTwittergram.mp3"))
local (username = "davewiner", password = user.twitter.prefs.password, struct)
new (tabletype, @struct)
struct.title = "TwitterGram Test #" + scratchpad.cttwittergramtests++
local (retval = [server].twittergram.newpost (username, password, bits, false, struct))
clipboard.putvalue (retval)