Twiddla Home
Close
Convert to an API Sandbox Account
Try it out with a Free Account
Click here to get an API Sandbox account.

Twiddla API Reference

For adding Twiddla to your own site

Twiddla's Application Programming Interface (API) lets you host Twiddla meetings on your own website. You can create new meetings on the fly and embed them into any page you'd like. You can disable the bits you don't want to see, and you can even show your own logo instead of ours.

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

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
format

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
url (for load)
text (for chat)