Find us on Facebook Follow us on Twitter GroupWorld on YouTube

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
Methods
Diagnostics
Webpage Integration
TutorCruncher Integration

URL Format

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

http://www.groupworld.net/mp/parse.cgi?filename=nc

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):

https://www.groupworld.net/mp/parse.cgi?filename=ncjs

To display the math tools above the whiteboard, use this URL instead (or, use the show_math API option to use a button for the math features):

http://www.groupworld.net/mp/parse.cgi?filename=math

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

Or to use the HTML5 client with math features:

http://www.groupworld.net/mp/parse.cgi?filename=mathjs

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
timer_two_usersSet to true to only start the timer once at least two users are in the room. You must also set show_timer to true
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). Note that the maximum number of users transmitting audio/video in a Janus room defaults to 6. Set new_videostrip.MAX_JANUS_WINDOWS if you wish to increase this
hide_playbackSet to true to hide the playback link below the room
newuiSet to false to use the classic user interface
no_pan_zoomSet to true to disable all panning (scrolling) and zooming for the current user, including mouse-wheel scrolling
no_mousewheel_scrollSet to true to disable mousewheel scrolling/zooming for the current user
hide_pagesSet to true to hide the page chooser at the bottom of the whiteboard for the current user
diagSet to true to enable extended diagnostics in the server logfile, giving information about audio/video status, javascript errors, etc.
selftestSet to true to perform a self-test before allowing the user to enter the room (but user can optionally quit the self-test).

Simple URL Format

A simpler format for the conference room URLs is as follows:

https://www.groupworld.net/room/<installation id>/<room name>

e.g.:

https://www.groupworld.net/room/1/demo

URL parameters can be added, e.g.:

https://www.groupworld.net/room/1/demo?hide_playback=true

Or use the following URL format if you want to display the math tools at the top of the whiteboard:

https://www.groupworld.net/math/<installation id>/<room name>

Recording Playback

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

http://www.groupworld.net/mp/saved_sessions.cgi

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.
xmlSet to true to output data in xml format.
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:

http://www.groupworld.net/mp/gwusers.cgi?inst_id=1

(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
Screen sharing options
Desmos options
Shared text editor 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 or max_janus_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, or via buttons in the video windows). If Janus and/or WebRTC 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 recommended that you enable Janus Gateway when using presenter mode with more than 2 users, for better audio/video quality. Note that you must also set new_videostrip.options["presenter_username"] and new_whiteboard.options["presenter_username"]. The presenter username is not case sensitive
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["invisible_user"]Optionally set this to the username of a user who will be invisible to other users. Note that you should also set new_whiteboard.options["invisible_user"] and chat.options["invisible_user"] options
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. 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. Only applies when Janus Gateway is not being used
new_videostrip.options["janus_only_publish_presenter"] Set to "true" to make it so that only the presenter's audio and video are transmitted when using Janus Gateway (if you want a large number of users with only one person transmitting audio/video and other users just receiving, i.e. one-to-many). The presenter has a "grant presenter" button allowing them to temporarily grant audio, video and whiteboard permissions to individual users
new_videostrip.options["non_presenter_av_control"] Set to "true" to allow non-presenter users control over their own microphone and webcam when using Janus (normally only the presenter has control over everyone's webcam and microphone permissions)
new_videostrip.options["non_presenter_fullscreen_control"] Set to "true" to display the full-screen icon for non-presenter users when using Janus. (Normally only the presenter sees the fullscreen icons, and it displays the selected user's video in fullscreen for all users). When this option is used, non-presenter users can see other users' video in fullscreen, but it does not affect other users
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() method 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.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["video_quality"] Sets the jpeg quality of video frames, from 0 to 100 (default 65). Note that this has no effect when Janus or WebRTC is active (except for recordings). Also 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.options["video_off_by_default"] Set to "true" to turn off video by default. Users can click on the icon in their video window to enable it
new_videostrip.options["audio_off_by_default"] Set to "true" to turn off audio by default. Users can click on the icon in their video window to enable it
new_videostrip.LOW_VIDEO_FRAMERATE When using the default "variable" framerate, this sets the framerate to use when the user is not speaking if WebRTC is not being used. 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 if WebRTC is not being used. Default 8.0
new_videostrip.WEBRTC_VIDEO_FRAMERATE Sets the framerate used for video frames transmitted to server when WebRTC is being used. This is only used for recordings (as the main audio/video is transmitted peer-to-peer using WebRTC). Default is 4.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 5
new_videostrip.JANUS_BITRATE Sets the bitrate when using Janus Gateway (default 256000)
new_videostrip.JANUS_CODEC Sets the codec when using Janus Gateway (default 'h264'). You can also use vp8 or vp9
new_videostrip.max_video_bw Optionally set the maximum WebRTC video bandwidth (in kilobits per second). Default is to let WebRTC automatically adjust bandwidth
new_videostrip.max_audio_bw Optionally set the maximum WebRTC audio bandwidth (in kilobits per second). Default is to let WebRTC automatically adjust bandwidth
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.load_all_pdf_pages Set to false to prevent populating the page number dropdown with all pages of uploaded pdf/docx/pptx/odt file)
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 = ink dropper, 45 = eraser, 46 = select, 47 = lines with arrows, 50 = polygon, 51 = filled polygon, 73 = highlighter, 74 = dotted line, 103 = transparent ellipse, 104 = transparent rectangle, 105 = transparent polygon, 106 = smooth freehand 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["always_redraw_gridlines"] Set to "true" to always redraw gridlines after user draws on the whiteboard
new_whiteboard.options["gridlines_per_page"] Set to "true" to store the gridlines separately for each page (so you can have gridlines on and off in different pages)
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["non_presenter_access"] Set to "true" to allow non-presenter users write access to the whiteboard by default
new_whiteboard.options["invisible_user"]See new_videostrip.options["invisible_user"] 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["draw_visible_area"] Set to "true" to draw the visible screen areas of other users as a light blue outline
new_whiteboard.options["sync_pan_top_left"] Set to "true" to make it so that the multi_user_pan option synchronizes the top-left of all users' whiteboard area (rather than the centre)
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 always display the tour screen (otherwise it only displays the first time a user connects)
new_whiteboard.options["show_math"] Set to "true" to display the math tools icon. (If you prefer having all the math tools at the top of the page, use the https://www.groupworld.net/math/<installation id>/<room name> URL format)
new_whiteboard.options["show_trash"] Set to "true" to display the trash icon on the main whiteboard window, at the bottom-left (in addition to displaying it at the top)
new_whiteboard.options["hide_invite"] Set to "true" to hide the invite button
new_whiteboard.options["hide_help_button"] Set to "true" to hide the help button
new_whiteboard.options["show_eraser"] Set to "true" to display the eraser icon on the main whiteboard 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/text to appear the same thickness/font-size 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 (to make both width and height fit), but only if image is larger than whiteboard
new_whiteboard.options["scale_to_fit_width"] Set to "true" to scale images to fit to the width of the whiteboard (whether smaller or larger than the width)
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["ovals_from_centre"] Set to "true" to draw ellipses from the centre rather than from the top-left corner
new_whiteboard.options["show_load"] Set to "false" to hide the Load button
new_whiteboard.options["hide_flood_fill"] Set to "true" to hide the Flood fill tool
new_whiteboard.options["show_insert_page"] Set to "true" to display the Insert Page 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 "false" to hide the Chat button
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["auto_open_upload_dialog"] Set to "false" to prevent automatically opening the file chooser when the upload dialog box is opened
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. Not compatible with the movable_images option
new_whiteboard.options["display_drawing_user"] Set to "false" to prevent displaying the drawing user's name beside their drawing actions
new_whiteboard.options["display_pointer_username"] Set to "true" to display username next to pointer if display_drawing_user is enabled. Normally the drawing username is not displayed for the pointer tool
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["logo"] Optional URL of a logo to be displayed in top-right corner of conference room menu bar
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.options["dot_pointer"] Set to "true" to make the pointer tool display as a red dot instead of a crosshair
new_whiteboard.options["arrow_pointer"] Set to "true" to make the pointer tool display as an arrow instead of a crosshair
new_whiteboard.options["no_pan_left_above"] Set to "true" to prevent the user from being able to pan (scroll) above or to the left of the origin of the whiteboard (0,0)
new_whiteboard.options["limit_pan"] Set to "true" to prevent the user from being able to pan (scroll) more than half the whiteboard width/height beyond the current whiteboard contents
new_whiteboard.options["persistent_ruler_protractor"] Set to "true" to make the ruler and protractor remain on the whiteboard after lifting the mouse button. Instead, the ruler and protractor are removed from the whiteboard by clicking the protractor or ruler icon again
new_whiteboard.options["bezier_curves"] Set to "true" to draw continuous freehand lines using bezier curves, for smoother freehand drawing
new_whiteboard.HELP_URL Sets the URL of the help button
new_whiteboard.NEWUI_HELP_URL Sets the URL of the help page
new_whiteboard.TOPBAR_HEIGHT Sets the height in pixels of the top menu bar along the top of the whiteboard (default 38)
new_whiteboard.newui Set to false to use the old user interface
new_whiteboard.newui_topbar Set to false to remove the top menu bar (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.
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.
new_whiteboard.save_dir Optionally set this to the directory to use for loading/saving/uploading files for the room. Defaults to the room name with "wb1" at the end.
chat.options["invisible_user"]See new_videostrip.options["invisible_user"] for details
chat.options["chat_input_on_top"]Set to true to move the chat input box to the top of the chat window
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 / whispers. Exceptions: presenters can still use private chat, and users can still send private chats to the presenter
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
deskshare.updates_per_sec Optionally set the screen sharing framerate (default is 2.0 frames per second)
deskshare.show_user_own_win Set to true (without quotes) to make it so that users see their own shared screen/window inside the whiteboard (as other users do)
desmos.api_key Sets the Desmos API key (required to use Desmos)
txted.using_redips Set to false to make the shared text editor fill the entire whiteboard
tunnel.ask_reconnect Set to true to ask user if they want to reconnect when they get disconnected from the server

Methods

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). You can pass new_whiteboard.upload_complete as the callback function, which waits for the first page of the image or document to be generated by the server, and loads it onto the whiteboard
new_whiteboard.save_as(filename)Saves the current picture to the server, or downloads to the browser as pdf or image. By default the image is saved to the server in the custom Groupworld format, and can be loaded using the load_pic API. To save as image or pdf, just add .png, .jpg or .pdf to the filename (this will save to the browser instead of to the server)
new_whiteboard.load_pic(filename, x, y)Loads a saved whiteboard state, or a jpg/png image from the server onto the whiteboard at the given co-ordinates (ignored if loading a saved whiteboard). By default the image is loaded from the current whiteboard's directory (new_whiteboard.save_dir, which defaults to the room name with "wb1" appended) unless the filename starts with a "/"
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.reset_pan_zoom()Resets the current zoom to 100% and pans to the centre of the whiteboard
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, send_to_server)Changes the current page. Pass true as the second parameter to transmit the set-page to the server (otherwise it will only be visible by the current user)
new_whiteboard.insert_page(true)Inserts a new blank page at the current position
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)
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)

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.

Diagnostics

You can optionally capture diagnostics include room logins, WebRTC status, javascript errors, uploaded files, etc. Set:

groupworld.diag = true;

By default the diagnostics are logged to filestore/groupworld_client_log, but you can override groupworld.log_diag to capture the messages:

groupworld.log_diag = function(msg) {}

With the hosted Groupworld, you can simply add

&diag=true

to the room URL, and the diagnostics can be viewed in the server logfile.

Replacing Groupworld icons

We use Font Awesome for most of the user interface icons. You can replace any FA icon by using CSS such as the following (replace /images/tick.png with the url of your replacement icon, which ideally should be svg):

.fa-paste { background-size: contain; height: 30px; width: 30px; margin-bottom: 0px !important; margin-top: -5px !important; position: relative; top: 6px; background-repeat: no-repeat; background-image: url('/images/tick.png') }
.fa-paste:before { content: ""; }

To replace regular icons (non font awesome), you would simply use something like this:

#gridlines { content: url('/images/tick.png') }

Embedding the Groupworld self-test page

The Groupworld self-test wizard allows users to test their microphone and camera before entering the Groupworld room. You can embed the self-test page in your own web page by using the following code:

<iframe allow="microphone; camera" width=640 height=500 src="https://www.groupworld.net/mp/parse.cgi?filename=selftest.html" style="border: 0"></iframe>

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';

TutorCruncher Integration

Groupworld can be integrated with TutorCruncher, giving access to scheduling and payment processing. For details of how to integrate with TutorCruncher, see our video.

After integration, when a user clicks on the whiteboard in TutorCruncher, they will be directed to a Groupworld room with the name of the room set to the TutorCruncher appointment name, and the user's username is passed in to Groupworld from TutorCruncher.

When TutorCruncher is integrated with Groupworld, the integration URL is set to https://www.groupworld.net/mp/tutorcruncher.cgi in the SSO integration settings in TutorCruncher. You can add the following parameters to this url to change the integration behaviour:

redirYou can optionally set redir=true to redirect users to a Groupworld room link. (By default users are just sent to a tutorcruncher.cgi link, with a token, so they cannot see the room url or their username in the url)
append_roleYou can optionally set append_role=true to prepend the TutorCruncher role (Admin, Contractor, Client, etc.) to the username, which then allows a presenter user to be set for your TutorCruncher rooms

Android ChromeWebView

If using an Android ChromeWebView, you may need to call:

webview.getSettings().setMediaPlaybackRequiresUserGesture(false)

in order to enable audio/video.




Home | Contact | Privacy