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.

Developer Interface

Twiddla's public interface is crazy simple. It consists of just two web services along with a URL format for embedding Twiddla meetings in an IFRAME:

There are actually a few more API calls that you can use, though most people will do just fine with the above. If you're looking to squeeze every last drop of Twiddliness out of the API, you might want to check out our Advanced Developer Interface.

Embed:

You can embed a Twiddla meeting into any website simply by dropping the url for that meeting into an IFRAME tag.

For more control, we offer a secondary URL that you can use.

NOTE: Google Chrome has deprecated WebRTC over HTTP, so you'll need to ensure that both your Twiddla Embed and the page it is contained on are running under SSL (ie., served from HTTPS urls) or Voice Chat will not function.

Here are the parameters that you can pass:

https://www.twiddla.com/api/start.aspx
sessionid (required) This is the meeting ID that shows so prominently in every standard Twiddla meeting URL.
v (optional) Twiddla Version to use. Leave empty for the latest version. Specify v=1 to force display of the V1 top nav.
guestname (optional) If this parameter is supplied, and this user is not yet logged in to Twiddla, we'll give him the supplied name when he joins the meeting.
password or passwordhash (optional) If the meeting is password protected, you can skip the password screen by supplying it here.

The low-tech, yet slightly less secure way of doing it is to simply hand across the password in plain text.

Alternately, if the cool kids are giving you grief, you can do some simple encryption before handing it over the wire as a passwordhash. Create a string consisting of the meeting password plus the viewing user's IP address, then compute a 32-character hexadecimal-formatted MD5 hash of that string. As an example:

password pvt
user IP 127.0.0.1
passwordhash md5("pvt" + "127.0.0.1") = 0c6bd5671b45545169352fd11351561b
hide (optional) A comma-separated list of UI components that you'd like to be hidden from view. This is useful in customizing the look of a meeting to match your own site, or to remove elements that you have duplicated elsewhere on your page (such as Chat or Voice).

Valid component names include:

  • chat
  • invite
  • profile
  • voice
  • welcome
  • url
  • etherpad
  • documents
  • images
  • bottomtray
  • email
  • widgets
  • math
  • roomsettings
  • logo (co-branding only)
exiturl (optional, co-branding only) For embedded meetings, this is the URL to which your users will be sent when they click the Logo while in a meeting.

NOTE: this parameter will be ignored for accounts without co-branding access.

css (optional, co-branding only) The URL of a CSS file to be included in the page. Use it to customize the look of anything you want.

NOTE: this parameter will be ignored for accounts without co-branding access.

js (optional, co-branding only) The URL of a Javascript file to be included in the page. It's your own little Greasemonkey script inside of Twiddla. Use it to change the behavior of whatever you want!

NOTE: This parameter will be ignored for accounts without co-branding access.

autostart (optional) If specified, will skip the interstitial "play" screen and drop your users straight into the meeting.

Please don't use this parameter on any public-facing pages, as it will quickly fill your meetings with thousands of random strangers!

NOTE: This parameter will be ignored for accounts without API access.

controltype (optional) An integer value that, if specified, will set the meeting to either Collaboration Mode or Presentation Mode.

Valid integer values include:

  • 1 (Collaboration)
  • 2 (Presentation)
loginusername (optional) If specified, and the viewing user is not currently logged in to Twiddla, will attempt to login using this username and a corresponding password set in loginpassword.

The Twidda User Account should be created using the CreateUser method of the Twiddla API.

NOTE: This parameter will be ignored for accounts without API access.

loginpassword (optional) Specifies the password to use when logging a user into Twiddla via the loginusername parameter.

Will be ingored if not accompanied by a loginusername.


Example 1. Simple Whiteboard

This example simply takes the URL for one of Twiddla's sandboxes and drops it into an IFRAME:

<iframe src="https://www.twiddla.com/5" frameborder="0" width="800" height="600"></iframe>

show this widget


Example 2. Simple Whiteboard, alternate syntax

This example is functionally equivilant to the one above, but it uses the alternate URL syntax that we'll need in the more complex examples below.

Note how we found the SessionID below by splitting the URL above. Not exactly rocket science, eh? In real-world use, you'll most likely be using SessionIDs that you received as the result of Create Meeting API calls.

<iframe src="https://www.twiddla.com/api/start.aspx?sessionid=5" frameborder="0" width="800" height="600"></iframe>

show this widget


Example 3. Whiteboard with components removed

This example crams the whiteboard into a smaller space. It removes the chat, bottom tray, and URL field so that they don't get in the way. <iframe src="https://www.twiddla.com/api/start.aspx?sessionid=7&hide=chat,bottomtray,url" frameborder="0" width="600" height="400" style="border:solid 1px #555;"></iframe>

show this widget


Example 4. Customized Whiteboard with external CSS and Javascript

This is the MySpace Example using a couple Co-Branding features. It pulls in custom CSS and JS files from an external server to change the toolbar to a cool pink and add a blingin' dancing logo. Now we're getting somewhere!

If you want to do advanced CSS and scripting features like these, you're welcome to go nuts, but we can't really give you any support here. You'll need to use a tool like FireBug or similar to reverse engineer our confusing naming conventions. And you'll need a heavy dose of client-side skeelz to pull it off. Just sayin'.

<iframe src="https://www.twiddla.com/api/start.aspx?sessionid=19&css=https://www.twiddla.com/demo/altskin.css&js=https://www.twiddla.com/demo/altscript.js" frameborder="0" width="800" height="600" style="border:solid 1px #555;"></iframe>

show this widget


Example 5. Branded Whiteboard with components removed and custom URL

This is the Kitchen Sink Example. It shows a meeting we've set up with a custom logo (which is an co-branding feature), and that we've also redirected back to our own website.

You'll notice that there's very little left to identify it as having come from Twiddla. That's why they call it CoBranding.

<iframe src="https://www.twiddla.com/api/start.aspx?sessionid=19&hide=chat,bottomtray&exiturl=https://www.google.com/" frameborder="0" width="800" height="600" style="border:solid 1px #555;"></iframe>

show this widget

Creating a new Twiddla Meeting:

You can create a new Twiddla meeting by means of a simple HTTP POST to https://www.twiddla.com/API/CreateMeeting.aspx containing your Twiddla username and password.

Successful requests will return the ID of newly created meeting. 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/CreateMeeting.aspx instead.

A Create Meeting request may supply the following parameters:

https://www.twiddla.com/API/CreateMeeting.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.
meetingtitle (optional) A title for your meeting, if you'd like one.
meetingpassword (optional) A password for your meeting, if you'd like one. If omitted, the meeting will be set to public.
url (optional) The URL of a web page to load as the initial document for this meeting. If omitted, the meeting will begin with a blank canvas.
presenterusername (optional) The name of the user that will be "presenter" if this meeting is placed into Presentation Mode. If omitted, this will default to the API User (which is probably not what you want, if you plan to use Presentation Mode).
 

Try it out:

username
password
meetingtitle
meetingpassword
url
presenterusername

Listing your Active Meetings:

You can get a list of Twiddla meetingIDs that are currently in use by sending off a HTTP POST to https://www.twiddla.com/API/ListActive.aspx containing your Twiddla username and password.

Successful requests will return a comma-separated list of IDs for any Twiddla meeting you've created that's currently in progress. 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 active meetings in progress (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/ListActive.aspx instead.

A List Meetings request may supply the following parameters:

https://www.twiddla.com/API/ListActive.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.
format (optional) Valid formats are:

  • csv
  • xml

By default, we'll hand back a simple comma-separated list of meetingIDs, 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 Meetings and the Users that they contain. There's plenty of information there to do anything you want, so parse away!

 

Try it out:

username
password
format

Sample Workflow

Let's say you run a website that helps people do project management. Your users want a way to collaborate in real time, but all you have is a little half-baked chat room for them to use. Wouldn't it be better if you could hook these people up with a proper Web Meeting tool like Twiddla?

Hell yeah, it would! Here's how you'd do it:

User starts a New Meeting

  1. User clicks "New Meeting" button somewhere on your site
  2. You fire off a Create Meeting API request
  3. Twiddla hands you back a SessionID
  4. You write it down somplace so you don't lose it
  5. You present a page with EMBED code containing that SessionID

User enters an Existing Meeting

  1. You show the User a list of Meetings that you have associated with his team's project.
    (You did remember to write down that SessionID, didn't you?)
  2. User clicks one of your "Join Meeting" buttons
  3. You present a page with EMBED code containing that SessionID

Those are really the only two use cases that Twiddla needs to be involved in. Naturally, you'll want to associate that SessionID with whatever objects it makes sense to stick it onto, and you'll probably want to build some sort of invite system, but really that's not our problem. We're just here to get your meetings working. Good luck with all that other stuff!

Pricing

We offer three tiers of API access to suit the needs of your business, as well as a Sandbox account that you can use during evaluation and testing.

Small Business

Twiddla's Small Business API plan is an affordable way to integrate Twiddla functionality into your site. It varies from our more expensive plans primarily in that the whiteboards you embed will retain Twiddla's branding, but you can still create as many users and whiteboards as you like.

Medium and Large Business plans

These plans will give your business full access to the co-branding and customization features of the API so that you can present a professional, polished look and seamless integration into your site. These plans differ from one another mainly in terms of capacity. The bigger the plan, the more whiteboards you can run simultaneously.

Start a new whiteboard
Try it out with a Free Account
Click here to get an API Sandbox account.

API Sandbox

During testing, you can use a Sandbox account that gains access to all the functionality of the API (with a few minor restrictions to keep you from taking your site live). You can co-brand and otherwise customize the meeting rooms that you embed into your site, and test out the user and whiteboard creation portions of the API.

You can compare Twiddla's API plans and pricing here. More information about how everything works can be found in our API Terms of Service.