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:
- Embed Meeting - to stick a Twiddla meeting onto your site.
- Create Meeting - to programatically create a new Twiddla meeting.
- List Meetings - to get a list of your active Twiddla meetings.
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. Here are the parameters that you can pass:
| http://www.twiddla.com/api/start.aspx | |||||||
sessionid (required)
|
This is the meeting ID that shows so prominently in every standard Twiddla meeting URL. | ||||||
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:
|
||||||
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:
|
||||||
exiturl (optional, >=enterprise)
|
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 non-Enterprise/Universal accounts. | ||||||
css (optional, >=enterprise)
|
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 non-Enterprise/Universal accounts. | ||||||
js (optional, >=enterprise)
|
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 non-Enterprise/Universal accounts. | ||||||
Example 1. Simple Whiteboard
This example simply takes the URL for one of Twiddla's sandboxes and drops it into an IFRAME:
<iframe src="http://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="http://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="http://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 Enterprise 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="http://www.twiddla.com/api/start.aspx?sessionid=19&css=http://www.twiddla.com/demo/altskin.css&js=http://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 Enterprise 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="http://www.twiddla.com/api/start.aspx?sessionid=19&hide=chat,bottomtray&exiturl=http://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
http://www.twiddla.com/new.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/new.aspx instead.
A Create Meeting request may supply the following parameters:
| http://www.twiddla.com/new.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. |
| Try it out: | |
Listing your Active Meetings:
You can get a list of Twiddla meetingIDs that are currently in use by sending off a HTTP POST to
http://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:
| http://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:
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: | |
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
- User clicks "New Meeting" button somewhere on your site
- You fire off a Create Meeting API request
-
Twiddla hands you back a
SessionID - You write it down somplace so you don't lose it
-
You present a page with EMBED code containing that
SessionID
User enters an Existing Meeting
-
You show the User a list of Meetings that you have associated
with his team's project.
(You did remember to write down thatSessionID, didn't you?) - User clicks one of your "Join Meeting" buttons
-
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
Twiddla's API follows the same pricing model as Twiddla itself. We offer a free trial version that you can use while testing, and for some smaller use cases, as well as a paid version that is suitable for production use.
Professional and Free Trial
Twiddla's API is usable from a Free Trial or Professional subscription, provided you are only running a single meeting at a time. That makes it suitable for single-person design shops, individual tutors or classrooms, and other small uses.
Enterprise and Universal
If you're planning to run more that one meeting at a time, you'll want to sign up for an Enterprise subscription. It's super cheap, at $49/month, and you can run up to 10 simultaneous meetings per license. You'd be surprised how many users you can service with an Enterprise subscription, but if it turns out you're over your limit, no worries. We'll let you know about it and give you a chance to upgrade to a Universal subscription or discuss options for scaling even larger.You can compare Twiddla's pricing plans here. More information about how everything works can be found in our API Terms of Service.