Whiteboard API

Whiteboard Team is an online whiteboard for real-time collaboration. The API brings the power of Whiteboard Team to your app or platform.

Quickstart

Adding Whiteboard Team to your site is quick and easy. Just add this code to your HTML document:

                    
<body>
    <div style="width: 600px; height: 550px;" id="wt-container"></div>

    <script src="https://www.whiteboard.team/dist/api.js"></script>
    <script type="text/javascript">
        var wt = new api.WhiteboardTeam('#wt-container', {
            clientId: '<your clientId>',
            boardCode: '<board code>'
        });
    </script>
</body>
        
    

clientId: To use Whiteboard Team API, you need a client ID. Get your client credential

boardCode: Each board is identified by a unique string code. It should be a unique and unguessable string

The ready event occurs when the board has been loaded and ready to use so, it is a good place to have all other function callings.

wt.onReady(() => console.log('ready'));

IMPORTANT: Do not download the script to your site and host them yourself, this will break the functionality.

API Reference

To create a whiteboard, create a new instance of api.WhiteboardTeam() with a container element and preferred options.

new api.WhiteboardTeam(element, {options})
  • element [string | object] – contains a reference to the element in which whiteboard is
  • {options} [object] – options object

Options

clientId [string]
The public identifier for the application (Get your client credential). Here's an example:
clientId: '42c8014a89e6ad83a13e26538f1a63b6'
boardCode [string]
Whiteboard will use its value as the board's unique code to create a new or load existing board. By default, this option is not set, it should be a unique and unguessable string. We strongly suggest using universally unique identifiers (UUID). Alternatively, URL query strings could identify board codes. For example, board SOMEUNIQUESTRING would have URL: http://yourdomain.com/yourpage?wtBoard=SOMEUNIQUESTRING.
boardCode: '361249e0-feca-4acb-8483-66cf47dad409'
participant.role [string]

With this option, you can set the role of participant. valid roles are 'facilitator' and 'editor' who can edit and 'viewer' who can view only.

 participant: {
    role : 'editor'
}
participant.name [string]

With this option, you can set the display name of the user.

 participant: {
    name : 'DisplayName'
}
participant.permissions [array]

With this option, you can set permissions of the user. view_templates adds templates to the toolbar.

participant: {
    permissions : ["view_templates"]
}
board.tool [string]

With this option you can set a default tool, valid tools are pan, pen, line, arrow, circle, filledCircle, rectangle, filledRectangle, text, stickyNote or select. Default of this option is pen. Here is an example:

board: {
    tool: 'pen'
}
board.thickness [number]

With this option you can set a default thickness, thickness use for pen or border of shapes. Default of this option is 2. Here is an example:

board: {
    thickness: 1
}
board.colors [array]

With this option you can replace your color sub-menu colors. It should be a array of hex colors. The default of this option is null. Here is an example:

board: {
    colors: ['#FF5733', '#3498DB', '#5B2C6F', '#212F3C']
}
board.color [string]

With this option you can set a default color that will appear as the color button on the main menu. It doesn't have to be a part of your color sub-menu colors. It should be a hex color format. The default of this option is black. Here is an example:

board: {
    color: '#000000'
}
board.bg [string]

With this option you can set a default background for the board. The default of this option is 'Dot'. Valid backgrounds are 'None', 'Dot', 'Graph paper', 'Large grid', 'Small grid', 'Line' Here is an example:

board: {
    bg : 'Small grid'
}

Methods:

zoomIn()

Zooms the board in by one step.

wt.zoomIn()
zoomOut()

Zooms the board out by one step.

wt.zoomOut()
resetZoom()

Zooms the board to 100%

wt.resetZoom()
undo()

Does undo of the previous own operation.

wt.undo()
redo()

Does redo of the previous own undo.

wt.redo()
board.clear()

clear the content of the board. It's undoable.

wt.board.clear()
fitToScreen()

Repositions zoom level and pan position so that the entire content on the board is visible.

wt.fitToScreen()
removeCommand()

Removes objects from the board.

wt.removeCommand(commands);
Parameters

  • commands {array} - list of objects to remove

notify()

Shows a notification on the whiteboard.

wt.notify(message);
Parameters

  • message {string} - text of the notification

fullscreen()

Fullsscreens the whiteboard.

wt.fullscreen()
drawLine()

Draws a line or arrow on the board.

wt.drawLine(points, color, lineWidth, type);
Parameters

  • points {array} - list of two points. Example [{x:100, y:100},{x:200, y:200}]
  • color {string} - '#' followed by the 6 digit HEX code
  • lineWidth {number} - width of the stroke in pixels relative to the canvas with zoom level 1
  • type {string} - type of the line could be 'line' or 'arrow'

drawPen()

Draws shape defined as array of points

wt.drawPen(points, color, lineWidth);
Parameters

  • points {array} - list of drawing points, one point is object of two numbers {x:x, y:y}
  • color {string} - '#' followed by the 6 digit HEX code
  • lineWidth {number} - width of the stroke in pixels relative to the canvas with zoom level 1

drawRectangle()

Draws a rectangle on the board

wt.drawRectangle(x, y, w, h, stroke, lineWidth, fill);
Parameters

  • x {number} - X coordinate of the top left point of the rectangle
  • Y {number} - Y coordinate of the top left point of the rectangle
  • w {number} - width of the rectangle
  • h {number} - height of the rectangle
  • stroke {string} - border color. '#' followed by the 6 digit HEX code or null for no color
  • lineWidth {number} - width of the stroke in pixels relative to the canvas with zoom level 1
  • fill {string} - background color. '#' followed by the 6 digit HEX code or null for no color

drawCircle()

Draws a circle on the board

wt.drawCircle(x, y, r, stroke, lineWidth, fill);
Parameters

  • x {number} - X coordinate of the middle point of the circle
  • y {number} - Y coordinate of the middle point of the circle
  • r {number} - radius of the circle
  • stroke {string} - border color. '#' followed by the 6 digit HEX code or null for no color
  • lineWidth {number} - width of the stroke in pixels relative to the canvas with zoom level 1
  • fill {string} - background color. '#' followed by the 6 digit HEX code or null for no color

drawText()

Draws a text on the board

wt.drawText(x, y, text, color, font, size);
Parameters

  • x {number} - X coordinate of the top left point of the text
  • y {number} - Y coordinate of the top left point of the text
  • text {string} - text to be drawn
  • color {string} - '#' followed by the 6 digit HEX code
  • font {string} - font of the text font
  • size {number} - size of the text font

drawStickyNote()

Draws a sticky note on the board

wt.drawStickyNote(x, y, w, h, text, color, size);
Parameters

  • x {number} - X coordinate of the top left point of the sticky note
  • y {number} - Y coordinate of the top left point of the sticky note
  • w {number} - width of the sticky note
  • h {number} - height of the sticky note
  • text {string} - text to be drawn
  • color {string} - '#' followed by the 6 digit HEX code
  • size {number} - size of the sticky note font

drawImage()

Place an image on the board.

wt.drawImage(url,x,y);

Place an image in the center of the viewport.

wt.drawImage(url);

Place an image in the center of the viewport and zoom to the image.

wt.drawImage(url)
.then(image=> {
    wt.viewport.zoomTo(image);
});
Parameters

  • url {string} - url of the image
  • x {number} - X coordinate of the top left point of the image
  • y {number} - Y coordinate of the top left point of the image

Returns

A promise contains the image's object.

getImage()

Get the image of board.

wt.getImage(background).then(img => console.log(img));
Parameters

  • background {string} - 'white' uses white for background, 'default' uses board.bg for background , 'transparent' transparent background.

Returns

Promise with base65 image.

getCurrentUser()

Get the current user of the board.

wt.getCurrentUser().then(user => console.log(user));
Returns

Promise with an object containing the user id.

destroy()

Destroy the instance of the whiteboard.

wt.destroy();

Events:

onReady(callback)

The callback will call when the board has been loaded. Here's an example:

wt.onReady(ctx => console.log(ctx));
Callback Parameters

  • ctx {object} - contains uid of the user

onError(error)

The callback will call when any error occurred. Here's an example:

wt.onError(error => {
    console.log(error.type, error.message);
})

Callback Parameters

  • error {object} - contains error type and error message

user-joined

The event will raise when any other participant joins the board.

wt.addListener('user-joined', user => console.log('joined', user));
Parameters

  • user {object} - contains uid and display name of the user

user-left

The event will raise when any other participant leaves the board.

wt.addListener('user-left', user => console.log('left', user));
Parameters

  • user {object} - contains uid and display name of the user

REST APIs

Using client secret for REST API requests.

You can pass client secret in Api-Key header

Api-Key: <SECRET_KEY>

[GET] /api/v1/boards

Gets all boards and returns an array of board objects

curl  -H "Api-Key: <SECRET_KEY>" -X GET "https://www.whiteboard.team/api/v1/boards"
Returns

returns an array of board objects

                            
{
    "data": [
        {
            "id": "9725c0f7-8a4e-43ee-c87b-08d7a3020e76",
            "name": "Sample Board",
            "code": "8331612C-B0E7-466F-8F50-D2B90ADB42A9",
            "createdDate": "2020-01-27T12:00:49.1113226",
            "lastUse": "2020-01-30T08:07:23.383282",
            "lastChange": "2020-01-29T15:12:11.6749696",
            "shareType": 1
        }
    ],
    "totalCount": 1
}

[GET] /api/v1/boards/<BORAD_ID>

Gets a board by id and returns a board objects

curl  -H "Api-Key: <SECRET_KEY>" -X GET "https://www.whiteboard.team/api/v1/boards/<BORAD_ID>"
Parameters

BORAD_ID [string] - board id

Returns

returns a board object

                            
{
    "name": "Sample Board",
    "code": "8331612C-B0E7-466F-8F50-D2B90ADB42A9",
    "createdDate": "2020-01-27T12:00:49.1113226",
    "lastUse": "2020-01-29T19:17:15.5687596",
    "lastChange": "2020-01-29T15:12:11.6749696",
    "shareType": 1,
    "members": [
        {
            "uid": "68ea8ac4-e21d-4c8b-9e3b-d977feee177e",
            "username": null,
            "joinedDate": "2020-01-27T12:00:49.1180617",
            "isActive": true,
            "isOwner": false
        },
    ]
}

[DELETE] /api/v1/boards/<BORAD_ID>

Delete a board by Id.

curl -H "Api-Key: <SECRET_KEY>" -X DELETE "https://www.whiteboard.team/api/v1/boards/<BORAD_ID>"
Parameters

BORAD_ID [string] - board id

[POST] /api/v1/boards/<BORAD_ID>/upload

Upload an image to the board.

curl -H "Api-Key: <SECRET_KEY>" -F Uid=<USER_ID> -F file=@<FILENAME> https://www.whiteboard.team/api/v1/boards/<BORAD_ID>/upload"
Parameters