Find us on Facebook Follow us on Twitter Groupboard on Google+ Groupboard on YouTube

Powerful, cost-effective, secure web conferencing software

Hosted Groupworld API

The hosted version of Groupworld includes a control panel which lets you easily configure your rooms, manage users, and control the server configuration.

URL Format
HTML5 Room Options
Webpage Integration

URL Format

The following base URL is used for the Groupworld conference room:

Users using Chrome, Firefox and Edge are automatically redirected to the HTML5 client.

Or you can use the following URL for the HTML5 client (https is required for screen sharing and video):

To display the math tools above the whiteboard, use this URL instead (or, use the show_math API option):

Users using Chrome and Firefox are automatically redirected to the HTML5 client.

Or to use the HTML5 client with math features:

You can also embed the room into an iframe (see the control panel for sample iframe code), or copy the HTML code into your own web page for more control over integration.

URL Parameters

inst_idYour Groupworld installation id. REQUIRED
instanceThe Groupworld room to use. Each room can have a separate group of users connected. Rooms are automatically created on-the-fly as soon as anyone connects to that room.REQUIRED
usernameThe username of the user
passwordThe password of the user (if you have configured usernames and passwords for your users in the control panel)
widthOptional width of the room in pixels. Use 100% to fill entire web page
heightOptional height of the room in pixels. Use 100% to fill entire web page
show_room_nameSet to true to display the room name at the top of the page
show_timerSet to true to display a timer at the top of the page
janusSet to true to use Janus Gateway for multi-party WebRTC with more than 2 users (if this is enabled, audio/video will be routed through our Janus media server rather than peer-to-peer)
suggest_appSet to true to ask android/iOS users if they want to use the native app instead (we don't automatically suggest the native app any more, as the HTML5 version generally gives the best experience)
hide_html5Set to true to hide the link to the HTML5 client (in the plugin version page)
hide_playbackSet to true to hide the playback link below the room
newuiSet to false to use the classic user interface

Simple URL Format

A simpler format for the conference room URLs is as follows:<installation id>/<room name>


URL parameters can be added, e.g.:

Recording Playback

The following base URL is used to display the recordings for a particular room:

Playback URL Parameters

groupworld_idYour Groupworld installation id. REQUIRED
instanceThe Groupworld room (NOTE: this must match the instance that was used for the original session).REQUIRED
dirOptional directory.
hide_titleSet to true to hide the title and filename at the top of the page
usernameOptional username of the user
passwordOptional password of the user (if you have configured usernames and passwords for your users in the control panel)
widthOptional width of the room in pixels. Use 100% to fill entire web page
heightOptional height of the room in pixels. Use 100% to fill entire web page

Displaying Number of Users Connected

You can use the following URL to display the current number of users connected (across all your rooms). Place it inside an iframe to embed in your web page:

(replace 1 with your Groupworld installation ID, and add &brief=true to just print the number of users).

HTML5 Room Configuration

The hosted version of Groupworld provides a control panel, allowing you to create custom configurations for each room. In addition, the HTML5 client allows you to set these options via javascript. Note that you must set these options before calling groupworld.htmlgen(). Also, you must copy the HTML code into your own web page (you can't use the iframe). Bear in mind that if you configure a room via the control panel, those options will override any that you set using javascript calls. Also note that true and false values in the options[] arrays must be set as strings inside quotes.

Conference room options
Video-strip (audio/video) options
Whiteboard options
Chat options

groupworld.htmlgen(width,height)Generate the Groupworld HTML code, setting the room to a given size (use 100% to fill remaining space)
groupworld.startup(username, password, base, object, flags)Connect to the Groupworld server with optional username and password. See example HTML code for an explanation of parameters.
groupworld.domain_lock_any_roomSet to true to allow users to enter any room if the domain_lock server option is set (otherwise users can only connect to rooms that have been manually created in the room editor)
new_whiteboard.logout_callback()Logs off Groupworld and closes the network connection.
new_conference.options["multi_column"]Set to "true" to have multiple video window columns (NOTE: you must also increase max_video_windows)
new_conference.options["video_on_right"]Set to "true" to display the video windows to the right of the whiteboard
new_conference.options["chat_on_right"]Set to "true" to create a chat window to the right of the whiteboard
new_conference.options["vertical"]Set to "false" to display the video windows horizontally instead of vertically
new_conference.options["presenter_username"]Optionally set this to the username of the presenter user. Only the presenter can transmit audio/video and draw on the whiteboard (but presenters can temporarily grant presenter status to another user via the "Grant Presenter" button). If Janus has been enabled then all users can transmit audio/video by default, but not draw on the whiteboard unless the presenter enables it. It is recomended that you enable Janus when using presenter mode, for better audio/video quality. Note that you must also set new_videostrip.options["presenter_username"] and new_whiteboard.options["presenter_username"]. Also note that this option cannot be used with the use_webrtc feature
new_conference.options["presenter_check_left"]If set to "true", the presenter_username is compared to the start of the user's name, e.g. if presenter_username="teacher" then users with name "teacher_bob" or "teacher_jane" would be given presenter status
new_conference.options["must_have_presenter"]If set to "true" then users can only log in when a presenter is logged in (and users are kicked off when the presenter logs out)
new_conference.options["large_video"]Set to "true" to enable large video windows
new_conference.options["video_width"]Optionally set the video width in pixels (NOTE: you must also set this option in the new_videostrip object). It is recommended that you set the use_webrtc option to true when using large video windows
new_conference.options["video_height"]Optionally set the video height in pixels (you must also set this option in the new_videostrip object)
new_conference.options["demo_time"]If set, users are logged off after this number of seconds. (Used to create a demonstration room)
new_conference.options["default_framerate"]Default video framerate (defaults to "variable", which means framerate increases when user is speaking). Increasing video framerate will result in increased bandwidth (see bandwidth usage). This option does not apply if using WebRTC
new_conference.options["recording_dir"]Sets the directory used to store recordings when using automatic recording of every session (defaults to "recordings")
new_conference.options["use_instance_recording_dir"]Set to "true" to append the instance name to the recording dir (e.g. "recordings/room1") when automatically recording every session
new_conference.options["recording_filename"]Sets the filename used to store recordings when automatically recording every session (only takes effect if record_by_date is set to "false")
new_conference.options["ask_record"]Set to "true" to ask user if they want to record the session (when automatically recording every session)
new_conference.options["record_session"]Set to "true" to automatically record all sessions
new_conference.options["record_session_2_users"]Set to "true" to automatically record all sessions once two users have logged in (make sure you set record_session to false)
new_conference.options["record_by_date"]Set to "false" to record using instance name as filename instead of current date (when automatically recording every session)
new_conference.options["hide_videostrip"]Set to "true" to hide entire video/audio strip
new_conference.options["keepalive"]Set to "true" to send "keepalive" packets to the server and exit if we don't receive a response within a specified time (20 seconds). Can be useful in detecting lost connection more quickly if users have a bad internet connection
new_conference.options["start_time"]Optional start time for the session. Users will not be permitted to log in before this time. Note that the time is client-side time. Append a 'Z' to the time to use UTC time, otherwise the user's local timezone will be used. (format: "HH:MM" or "YYYY-MM-DD HH:MM")
new_conference.options["end_time"]Optional end time for the session. Users will not be logged off after this time. Note that the time is client-side time. Append a 'Z' to the time to use UTC time, otherwise the user's local timezone will be used. (format: "HH:MM" or "YYYY-MM-DD HH:MM")
new_conference.options["authorized_users"]Optional comma separated list of users who are authorized to enter this room
new_videostrip.options["min_video_windows"] Mininum video windows to display (not including user's own preview video window), even if there is insufficient room to display. Default 1
new_videostrip.options["video_width"]Optionally set the video width in pixels (NOTE: you must also set this option in the new_conference object)
new_videostrip.options["video_height"]Optionally set the video height in pixels (you must also set this option in the new_conference object)
new_videostrip.options["max_video_windows"] Maximum video windows to display (not including user's own preview video window). Default 2
new_videostrip.options["presenter_username"] See new_conference.options["presenter_username"] for details
new_videostrip.options["presenter_check_left"] See new_conference.options["presenter_username"] for details
new_videostrip.options["picture_in_picture"] Set to "true" to display small preview video inside other user's video window (for 2 users in room)
new_videostrip.options["chat_under_video"] Set to "true" to display chat window underneath video windows
new_videostrip.options["hide_video"] Set to "true" to disable video. See also new_conference.options["hide_videostrip"]
new_videostrip.options["hide_audio"] Set to "true" to disable audio
new_videostrip.options["large_presenter_window"] Set to "true" to have a large video window for the presenter (when the presenter_username option is used) and up to 4 small windows for the non-presenter users. Normally video is disabled for non-presenter users, but this option enables it. You must have large_video set to true
new_videostrip.options["presenter_audio_all"] Set to "true" to transmit audio for all users in presenter mode by default
new_videostrip.options["dont_start_av"] Set to "true" to prevent audio and video being enabled when the user logs in. You can call new_videostrip.start_av() to enable audio/video
new_videostrip.options["sync_fullscreen"] Set to "true" to syncronize fullscreen video between users, so that when one user enters full-screen, the other user is also automatically entered into fullscreen video
new_videostrip.options["hide_audio_controls"] Hides the audio controls (volume controls and auto-record box)
new_videostrip.options["multi_presenter"] Set to "true" to allow multiple temporary presenter users when using the Grant Presenter button
new_videostrip.options["use_webrtc"] Set to "true" to use WebRTC for high quality streaming video and audio. Note that WebRTC is only used when exactly two users are logged in, and only for the HTML5 client
new_videostrip.options["webrtc_video_width"] Optionally set the preferred video capture width. Use this to set the maximum video size if you intend calling set_video_size() in the future (otherwise video will be captured at the initial, lower resolution). This does not affect the size of the video windows as displayed in the user interface
new_videostrip.options["webrtc_video_height"] Optionally set the preferred video capture height
new_videostrip.set_video_size(width, height) Changes the size of the video windows, resizing the user interface as required (NOTE: this option can only be used after the Groupworld conference room has been fully constructed. If you want to set the default size of the video, use the video_width and video_height options instead)
new_videostrip.options["video_talking_user"] Set to "true" to only display the video for the user who is currently talking
new_videostrip.options["auto_record"] Set to "false" to make "auto transmit voice" off by default (so user's microphone is not transmitting by default)
new_videostrip.options["show_disable_talking"] Set to "true" to show the "Disable Talking" button, allowing users to temporarily disable talking for all other users. The user must have "disable interaction" permission set in the control panel
new_videostrip.options["video_quality"] Sets the jpeg quality of video frames, from 0 to 100 (default 40). Note that increasing quality will result in increased bandwidth
new_videostrip.options["show_auto_record"] Set to "false" to hide the "Auto Transmit Voice" button
new_videostrip.options["warn_no_audio"] Set to "false" to hide the warning that normally appears after 30 seconds if the browser has not been given permission to access the user's microphone
new_videostrip.LOW_VIDEO_FRAMERATE When using the default "variable" framerate, this sets the framerate to use when the user is not speaking. Default 4.0
new_videostrip.HIGH_VIDEO_FRAMERATE When using the default "variable" framerate, this sets the framerate to use when the user is speaking. Default 8.0
new_videostrip.MAX_JANUS_WINDOWS When Janus Gateway has been enabled, this option sets the maximum number of Janus windows (not including the current user). Default is 4.
new_whiteboard.mouse_wheel_scroll Set to false to disable mouse-wheel scrolling)
new_whiteboard.show_hover Set to true to display username of user who drew item when hovering over drawing items)
new_whiteboard.whiteboard_background_colour The default whiteboard background colour (default "rgba(255,255,255,1.0)")
new_whiteboard.tool_background_colour The default tools background colour (the space above and to the right of the whiteboard), in the classic user interface (default "rgb(230,230,230)")
new_whiteboard.options["default_size"] The default text/pen size, from 1-10 (default 1)
new_whiteboard.options["default_tool"] The default tool (31 = ellipse, 32 = filled ellipse, 33 = rectangles, 34 = filled rectangles, 35 = lines, 36 = freehand, 37 = text, 38 = flood fill, 39 = laser pointer, 40 = pan, 41 = eye dropper, 45 = eraser, 46 = select, 47 = lines with arrows, 50 = polygon, 51 = filled polygon, 73 = highlighter, 74 = dotted line)
new_whiteboard.options["default_background"] If set to the filename of an image that has been uploaded, will automatically load this image when the user connects if the whiteboard is blank
new_whiteboard.options["eraser_size"] The default eraser size, from 1-255 (default 10)
new_whiteboard.options["use_scrollbars"] Set to "false" to disable scrollbars
new_whiteboard.options["multiline_text_input"] Set to "true" to enable a multi-line text input box for the whiteboard. (Include jquery UI in your HTML code to make the text input box draggable)
new_whiteboard.options["show_tools_at_top"] Set to "true" to display the tool/colour/size selector at the top of the whiteboard
new_whiteboard.options["zoom_and_pages_at_bottom"] Set to "true" to display the zoom slider and page numbers in a separate bar underneath the whiteboard
new_whiteboard.options["display_num_users"] Set to "false" to hide the "x other users" at the top of the whiteboard
new_whiteboard.options["presenter_username"] See new_conference.options["presenter_username"] for details
new_whiteboard.options["presenter_check_left"] See new_conference.options["presenter_username"] for details
new_whiteboard.options["multi_user_pan"] Set to "false" to disable synchronization of pan/zoom operations between users
new_whiteboard.options["hide_zoom"] Set to "true" to hide the pan/zoom icons
new_whiteboard.options["auto_zoom"] Set to "true" to automatically zoom when another user draws outside the current visible area of the whiteboard, or when the whiteboard is resized
new_whiteboard.options["retain_zoom"] Set to "true" to keep the existing pan/zoom level when moving to a new page or clearing the page
new_whiteboard.options["show_tour"] Set to "true" to display the tour screen when users first connect (only available in the new user interface)
new_whiteboard.options["show_math"] Set to "true" to display the math tools icon (only available in the new user interface)
new_whiteboard.options["show_trash"] Set to "true" to display the trash icon on the main whiteboard interface (only available in the new user interface)
new_whiteboard.options["hide_invite"] Set to "true" to hide the invite button (only available in the new user interface)
new_whiteboard.options["hide_help_button"] Set to "true" to hide the help button (only available in the new user interface)
new_whiteboard.options["show_eraser"] Set to "true" to display the eraser icon on the main whiteboard interface (only available in the new user interface)
new_whiteboard.options["upload_images_to_board"] Set to "false" to not automatically display uploaded images/documents on the whiteboard
new_whiteboard.options["slideshow"] Set to "true" to enable "slideshow" mode, where Prev/Next buttons cycle between all uploaded images. Ignored if multi_page is not set to "false"
new_whiteboard.options["multi_page"] Set to "false" to disable multi-page functionality
new_whiteboard.options["constant_thickness"] Set to "true" if you want lines to appear the same thickness irrespective of zoom level
new_whiteboard.options["centre_in_window"] Set to "true" to centre jpg/png images in window
new_whiteboard.options["scale_to_fit"] Set to "true" to scale down images to fit in whiteboard
new_whiteboard.options["show_filestore"] Set to "true" to display the Filestore button, allowing users to upload/download files to a filestore on the server
new_whiteboard.options["show_load"] Set to "false" to hide the Load button
new_whiteboard.options["show_save"] Set to "false" to hide the Save button
new_whiteboard.options["show_upload"] Set to "false" to hide the Upload button
new_whiteboard.options["show_icons"] Set to "true" to display the Icon Library button
new_whiteboard.options["show_share_video"] Set to "true" to display the Share Video button
new_whiteboard.options["show_text_editor"] Set to "true" to display the shared code/text editor button
new_whiteboard.options["show_disable_drawing"] Set to "true" to display the Disable Drawing button. The user must have "disable interaction" permission set in the control panel
new_whiteboard.options["show_deskshare"] Set to "true" to display the Desktop Sharing button
new_whiteboard.options["show_record"] Set to "true" to display the Record button, if you want to give users the option to manually start recording a session
new_whiteboard.options["recording_dir"]sets the directory used to store recordings, when user presses the Record button (defaults to "recordings")
new_whiteboard.options["show_poll"] Set to "true" to display the Poll button
new_whiteboard.options["show_chat"] Set to "true" to display the Chat button, to allow users to pop up a text chat window. (For the new user interface, this defaults to "true")
new_whiteboard.options["show_send_url"] Set to "true" to display the Send URL button, to allow users to send a web page to other users
new_whiteboard.options["show_logout"] Set to "true" to display the Logout button
new_whiteboard.options["show_breakout"] Set to "true" to display the Breakout Room button, allowing users to invite other users into a separate breakout room
new_whiteboard.options["dont_clear_upload_doc"] Set to "true" to prevent clearing all pages when uploading a document (instead it will be uploaded started at the next free page)
new_whiteboard.options["dont_clear_upload_pic"] Set to "true" to prevent clearing the current page when an image is uploaded
new_whiteboard.options["movable_images"] Set to "true" to allow uploaded images to be moved/deleted/resized/rotated using the select tool (normally only drag+dropped images can be manipulated)
new_whiteboard.options["keep_background_on_clear"] Set to "true" to keep the current background image when clearing the current page
new_whiteboard.options["display_drawing_user"] Set to "false" to prevent displaying the drawing user's name beside their drawing actions
new_whiteboard.options["send_text_chars"] Set to "false" to prevent sending each individual character as user is typing it (when using the text tool)
new_whiteboard.options["force_save_png"] Set to "true" to save in png format by default
new_whiteboard.options["force_save_jpeg"] Set to "true" to save in jpg format by default
new_whiteboard.options["force_save_pdf"] Set to "true" to save in pdf format by default
new_whiteboard.options["logo"] Optional URL of a logo to be displayed in top-right corner of conference room menu bar (only for new user interface)
new_whiteboard.options["show_movement_pointer"] Set to "true" to always display a laser pointer showing the position of the other user's mouse cursor
new_whiteboard.HELP_URL Sets the URL of the help button
new_whiteboard.NEWUI_HELP_URL Sets the URL of the help button for the new user interface
new_whiteboard.newui Set to true to use the new user interface
new_whiteboard.newui_topbar Set to false to remove the top menu bar in the new user interface (and have a hamburger menu icon instead)
new_whiteboard.use_background_canvas Set to true to make the eraser just erase drawing marks but keep the background intact. Note that this option is not available in the plugin/app client, so those users will still see white eraser marks on the background
new_whiteboard.constructed (Read-only). Will be set to true once the new_whiteboard object is fully constructed, and the API is ready to be used.
chat.options["put_up_hand"] Set to "true" to add a hand button to the chat window. Non-presenter users (or users who don't have disable interaction permission) will see the hand button. When clicked, it sends a text notification to all admin/presenter users, and beeps
chat.options["show_chat_names"] Set to "false" to not display usernames in the text chat (this is separate from the user list)
chat.options["popup_chat"]Set to "true" to use a separate popup chat window, instead of one that overlaps the whiteboard
chat.options["allow_private_chat"] Set to "false" to disable private chat
chat.options["store_chat"] Set to "true" to store all chat, so that the entire chat history is displayed when a new user logs in
chat.options["log_chat"] Set to "true" to log all chat to a file on the server (will be stored in the chatlogs/ directory)
chat.options["notify_logins"] Set to "true" to notify all presenter (or users with disable interaction permission) admin users when anyone logs in
chat.options["presenter_username"] If set, only the presenter can see the user list. See new_conference.options["presenter_username"] for details
chat.options["presenter_check_left"] see new_conference.options["presenter_username"] for details
chat.options["presenter_chat_only"] Set to "true" to make it so that only the presenter can send chat text
chat.options["presenter_userlist_only"] Set to "false" to let everyone see the userlist in presenter mode (by default only the presenter can see everyone, and other users can only see the presenter)
chat.options["allow_file_transfer"] Set to "true" to display a Send File button, allowing users to transmit files to each other


The following methods can be used to interact with Groupworld:

groupworld.upload_file(filename, file, callback)Uploads a file to the server. The filename is relative to the top-level filestore directory, the file itself should be a string containing the binary data (not base64 encoded), and the callback is called after uploading (you will probably want to call load_pic in your callback)
new_whiteboard.save_as(filename)Saves the current picture to the server. To save as image or pdf, just add .png, .jpg or .pdf to the filename
new_whiteboard.load_pic(filename, x, y)Loads a picture/image from the server onto the whiteboard at the given co-ordinates
new_whiteboard.tool_callback(true, new_tool)Changes the current drawing tool. Values: 31=ellipse, 32=filled ellipse, 33=rect, 34=filled rect, 35=line, 36=freehand, 37=text, 38=fill, 39=pointer, 40=pan, 41=eye dropper, 45=eraser, 46=select, 47=line with arrows, 50=polygon, 51=filled polygon, 73=highlighter, 74=dotted line,
new_whiteboard.colour_callback(true, new_colour)Changes the current drawing colour. Values: 11=white, 12=red, 13=green, 14=blue, 15=pink, 16=yellow, 17=black, 18=grey, 19=magenta, 20=cyan, 21=brown
new_whiteboard.size_callback(true, new_size)Changes the current line/font size. Values: 1=smallest, 10=largest
new_whiteboard.set_zoom(new_zoom)Changes the current zoom (1.0 = 100%)
new_whiteboard.zoom_in()Zooms in by a factor of 2.0
new_whiteboard.zoom_out()Zooms out by a factor of 2.0
new_whiteboard.undo()Undos the last drawing action
new_whiteboard.redo()Redos the last drawing action
new_whiteboard.copy()Copies the selected items to the clipboard
new_whiteboard.cut()Cuts the selected items to the clipboard
new_whiteboard.paste()Pastes from the clipboard
new_whiteboard.clear_selection()Clears the current selection
new_whiteboard.load_callback()Brings up the Load window
new_whiteboard.save_callback()Brings up the Save window
new_whiteboard.upload_callback()Brings up the Upload window
new_whiteboard.clear_callback()Clears the current page, after confirming with user
new_whiteboard.clear_all_callback()Clears all pages, after confirming with user
new_whiteboard.clear_all()Clears all pages, without confirmation
new_whiteboard.set_page(new_page, true)Sets the current page
new_videostrip.toggle_mute_microphone(is_on)Mutes or unmutes the microphone (pass in false to mute)
new_videostrip.stop_av()Stops audio/video
new_videostrip.start_av()Starts audio/video again (after calling stop_av())
new_videostrip.toggle_mute_speaker(is_on)Mutes or unmutes the loudspeakers (pass in false to mute)
new_videostrip.toggle_video(is_on)Enables or disbles transmission of the user's video (pass in false to disable)

Webpage Integration

The simplest way of integrating Groupworld rooms into your web pages is to simply copy the iframe code provided in your control panel.

However, if you want to use the javascript API, you will need to copy the HTML code out of the iframe into your web page. You can then use the API to control room features. Additional features you can control by editing the HTML code include:

  • Set the user's username by editing the following line of code:
    var username = '';
  • Set the room name by editing the following line of code:
    var object = 'new_conference:newconf';
    (the room name is the string after the colon. DO NOT change new_conference).

  • Control who can enter the room by setting the authorized_users API option.

  • Control what times the room is active by setting the start_time and end_time API options.

  • Ensure that your HTML code can only be hosted from your domain by setting the domain_lock option in the "Server Configuration" of your control panel.

  • You can also optionally create your own scheduling system (using php/mysql, ASP or similar server-side scripting) on your website, authenticate the user yourself, and then generate the Groupworld HTML code if the user is authorized to enter the room. See our example open source tutor scheduler.

On-the-fly Room Creation

If you have copied the Groupworld HTML code into your own web page, you can create new rooms automatically simply by changing the room name in the HTML code (see Webpage Integration section above). Note, however, that some of the default options are different from the default room parameters you get when you manually create room in the hosted Groupworld control panel. (This is because we have changed the default room parameters over the years, but we never change the actual defaults in the javascript code). Here are the default parameters we use when creating a new room:

new_whiteboard.newui = true;
new_whiteboard.options['default_size'] = 3;
new_whiteboard.options['eraser_size'] = 15;
new_whiteboard.options['show_share_video'] = 'true';
new_videostrip.options['show_auto_record'] = 'false';
new_videostrip.options['use_webrtc'] = 'true';
new_whiteboard.options['multi_user_pan'] = 'false';
new_whiteboard.options['auto_zoom'] = 'true';
new_conference.options['use_instance_recording_dir'] = 'true';
new_whiteboard.options['use_scrollbars'] = 'false';

Home | Contact | Privacy