Advanced Developer Interface

Here are a few more API calls that you might find handy. Most sites using the API will do just fine using only the basic API calls, but these ones will let you go to 11:

• Create User - to programatically create a new Twiddla meeting.
• List Snapshots - to get a list of Snapshots that have been saved in your meetings
• Delete Meeting - to completely delete a meeting, including all transcripts, snapshots and viewed webpages.

Creating a new Twiddla User:

You can create a new Twiddla user by means of a simple HTTP POST to https://www.twiddla.com/API/CreateUser.aspx containing your Twiddla username and password, along with some basic information about the user to be created.

Successful requests will return the Username of newly created user. Failed requests will return -1 along with an error message. Regardless, all responses will take the form of plain text, with nary an angle bracket in sight.

You may encrypt this request via SSL if you'd like, by directing it to https://www.twiddla.com/API/CreateUser.aspx instead.

A Create User request may supply the following parameters:

https://www.twiddla.com/API/CreateUser.aspx
username (required)	Your Twiddla username
password (required)	Your Twiddla password. Yes, in plaintext over the internet. Send it via SSL if you're afraid they're watching you.
newusername (required)	The username you'd like to use for this new user. (Be warned that we have half a million usernames registered and they all need to be unique. Best practice here is to prepend your sitename to a unique string, e.g., "mytutoringsite_kenny")
newpassword (required)	A password for your new user.
displayname (required)	Your user's full name, for display in Twiddla meetings.
email (optional)	Your user's email, if you want.
Try it out: username password newusername newpassword displayname email

Listing Saved Snapshots:

You can get a list of Twiddla snapshots that your users have saved by sending off a HTTP POST to https://www.twiddla.com/API/ListSnapshots.aspx containing your Twiddla username and password.

Successful requests will return a comma-separated list of Snapshot URLs. Failed requests will return -1 along with an error message. Note that a successful request will simply return nothing in the case that your account has no snapshots (since that's what a comma-separated list of zero length looks like.)

You may encrypt this request via SSL if you'd like, by directing it to https://www.twiddla.com/API/ListSnapshots.aspx instead.

A List Snapshots request may supply the following parameters:

https://www.twiddla.com/API/ListSnapshots.aspx
username (required)	Your Twiddla username
password (required)	Your Twiddla password. Yes, in plaintext over the internet. Send it via SSL if you're afraid they're watching you.
sessionid (optional)	The SessionID for which you'd like to list snapshots. If omitted, all snapshots for the supplied user will be returned.
format (optional)	Valid formats are: csv xml By default, we'll hand back a simple comma-separated list of Snapshot URLs, but if you want to get all fancy and enterprisey, you can go there too. Specify xml for this parameter and we'll hand you back a big chunk of XML containing a list of all your Snapshots along with a bunch of extra information about them. There's plenty of information there to do anything you want, so parse away!
Try it out: username password sessionid format csv xml

Listing Images and Documents:

You can get a list of Twiddla images and documents that your users have uploaded by sending off a HTTP POST to https://www.twiddla.com/API/ListMedia.aspx containing your Twiddla username and password.

Successful requests will return a comma-separated list of Media URLs. Failed requests will return -1 along with an error message. Note that a successful request will simply return nothing in the case that your account has no media of the type requested (since that's what a comma-separated list of zero length looks like.)

You may encrypt this request via SSL if you'd like, by directing it to https://www.twiddla.com/API/ListMedia.aspx instead.

A List Media request may supply the following parameters:

https://www.twiddla.com/API/ListMedia.aspx
username (required)	The Twiddla username of the user we're listing Media for
password (required)	That user's Twiddla password. Yes, in plaintext over the internet. Send it via SSL if you're afraid they're watching you.
mediatype (optional)	The type of media you'd like returned. If omitted, both Documents and Images will be returned. Valid mediatypes are: document image
format (optional)	Valid formats are: csv xml By default, we'll hand back a simple comma-separated list of Snapshot URLs, but if you want to get all fancy and enterprisey, you can go there too. Specify xml for this parameter and we'll hand you back a big chunk of XML containing a list of all your Snapshots along with a bunch of extra information about them. There's plenty of information there to do anything you want, so parse away!
Try it out: username password mediatype document image format csv xml

Delete a Meeting:

You can completely delete a Twiddla meeting by sending a HTTP POST to https://www.twiddla.com/API/DeleteSession.aspx containing your Twiddla username and password, along with the sessionid of the meeting in question.

Successful requests will a positive integer. Failed requests will return -1 along with an error message.

You may encrypt this request via SSL if you'd like, by directing it to https://www.twiddla.com/API/DeleteSession.aspx instead.

A Delete Meeting request may supply the following parameters:

https://www.twiddla.com/API/DeleteSession.aspx
username (required)	Your Twiddla username
password (required)	Your Twiddla password. Yes, in plaintext over the internet. Send it via SSL if you're afraid they're watching you.
sessionid (required)	The SessionID of the meeting you'd like to delete.
Try it out: username password sessionid

Adding Actions to a Meeting:

You can add Actions and send commands to an existing Meeting by sending off a HTTP POST to https://www.twiddla.com/API/AddAction.aspx containing your Twiddla username and password, as well as the sessionid of the meeting in question and a mode parameter describing the action to be taken.

Successful requests will return an empty response with status code 200. Failed requests will return -1 along with an error message.

You may encrypt this request via SSL if you'd like, by directing it to https://www.twiddla.com/API/AddAction.aspx instead.

An Add Action request may supply the following parameters:

https://www.twiddla.com/API/ListSnapshots.aspx
username (required)	Your Twiddla username
password (required)	Your Twiddla password. Yes, in plaintext over the internet. Send it via SSL if you're afraid they're watching you.
sessionid (required)	The SessionID which you'd like to modify.
mode	Valid modes are: reset - Reset a meeting, clearing all actions load - Open a URL on the stage chat - Add a line to the chat box reset requires no additional parameters. If users are present in the meeting, they will not notice a change until they exit and rejoin. load requies that url also be specified. chat requies that text also be specified.
url (required for load)	A full URL to the web page or document to display on the stage.
text (required for chat)	Text to be displayed in the Meeting's chat area.
Try it out: username password sessionid userID mode reset load chat url (for load) text (for chat)