Skip to main content

​
Get a whiteboard authorization code

POST /server/v1/white-board/grant-code Authentication: required (see Overview) Get a whiteboard authorization code. A whiteboard is a collaborative board independent of channels; users who pass the same board open the same whiteboard. The typical flow is similar to the channel token: your backend checks permissions → calls this endpoint to get auth_code and addr → sends them to the client → the client combines them into {addr}?code={auth_code} and opens it (the whiteboard is an H5 page, embedded with an iframe or WebView). The authorization code is valid for 1 hour and expires once connected; get a new one every time the whiteboard is opened, and don’t cache it. A whiteboard is created automatically the first time it is authorized; you don’t need to create it in advance. Users in a channel have an easier route: the join response already includes a ready-made whiteboard URL (field white_board, whose authorization code is that user’s sid), which you can embed directly without calling this endpoint. This endpoint is for “people outside the channel also need the whiteboard” and “using the whiteboard independently of channels”. For the full integration guide, see the “Whiteboard” docs. Request parameters
​
string
required
Board ID, with the same character set restrictions as channel names. A common practice is to use the channel name directly, so each channel maps to one whiteboard (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire
​
string
required
Third-party user ID, used to show collaborator cursors and operators (letters, digits, underscores (_), and hyphens (-) only) (max length 100) Example: 1001
​
string
Third-party user name Example: Alice
​
string
Network line. The value is a Chinese line name; leave empty to let the server choose Example: 内网
​
string
Server group
Request example:
Response parameters
​
string
Whiteboard authorization code, issued to the client to open the whiteboard Example: wb-co63jg6g54hu3b0xhtie
​
string
Whiteboard page URL; combine it with the authorization code as {addr}?code={auth_code} Example: https://api.example.com/white-board/
Response example:

​
Check whether a whiteboard exists

POST /server/v1/white-board/exist Authentication: required (see Overview) Check whether a whiteboard exists, that is, whether it has been created and not destroyed. Use it to decide “is there still content on this board”—for example, whether to show an “Open whiteboard” entry, or to confirm that a destroy has taken effect. Request parameters
​
string
required
Board ID (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire
Request example:
Response parameters
​
boolean
Whether the whiteboard exists (created and not destroyed)
Response example:

​
Destroy a whiteboard

POST /server/v1/white-board/destroy Authentication: required (see Overview) Destroy a whiteboard. Content on the board is cleared and can’t be recovered; users currently on the whiteboard are disconnected. Whiteboards also have two automatic destroy paths; this endpoint is for cleaning up proactively before those happen (such as “Close whiteboard” during a call):
  • When a channel is destroyed, the whiteboard with the same name is destroyed with it. A channel is destroyed automatically after 2 hours with no one in it, so a whiteboard used the recommended way (board set to the channel name) also disappears 2 hours after everyone leaves. To keep whiteboard content long term, don’t use the channel name as board.
  • A whiteboard with no writes for more than 25 hours is cleaned up by a scheduled job.
Request parameters
​
string
required
Board ID (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire
​
string
Operator ID, used for auditing Example: 1001
​
string
Operator name Example: Alice
Request example:
Response parameters data is null Response example: