Documentation
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.
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:
|
||||||
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, 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:
|
||||||
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: | |
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:
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
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.
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.