Messages

Messages are short texts shown on the Viewer and Moderator outputs. At most one message per room shows at a time, so showing one hides the other.

The message object

Audience questions are messages too, with source set to audience.

Name
_id
Type
string
Description
Unique id.
Name
_model
Type
string
Description
The type of this object. Always message.
Name
_updated_at
Type
timestamp
Description
When it last changed.
Name
showing
Type
boolean
Description
Whether the message is on the outputs.
Name
text
Type
string
Description
The message text.
Name
color
Type
string
Description
The text colour.
Name
bold
Type
boolean
Description
Whether the text is bold.
Name
uppercase
Type
boolean
Description
Whether the text shows in capitals.
Name
fullscreen
Type
boolean
Description
Whether the message fills the Viewer and hides the timer.
Name
source
Type
string
Description
operator for messages written in the Controller. audience for questions from the Submit form. One of operator, audience.
Name
submitter_name
Type
string or null
Description
The name typed on the Submit form, if any. Null otherwise.

GET/rooms/{room_id}/messages

List messages

Returns the room's messages, including audience questions.

Path parameters

Name
room_id
Type
string
Required
Description
The room's id, from its address: /o/ROOM_ID/….

Request

GET

/rooms/{room_id}/messages

curl https://app.kloksi.com/api/v1/rooms/ROOM_ID/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "ok": true,
  "message": "Messages loaded",
  "data": {
    "list": [
      {
        "_id": "a2Bc9dEf0GhI",
        "_model": "message",
        "_updated_at": "2026-11-05T09:30:00.000Z",
        "showing": false,
        "text": "Five minutes left",
        "color": "white",
        "bold": false,
        "uppercase": false,
        "fullscreen": false,
        "source": "operator",
        "submitter_name": null
      }
    ]
  }
}

POST/rooms/{room_id}/messages

Create a message

Adds a hidden message to the room.

Path parameters

Name
room_id
Type
string
Required
Description
The room's id, from its address: /o/ROOM_ID/….

Body

Name
text
Type
string
Description
The message text. At most 500 characters.
Name
color
Type
string
Description
The text colour.
Name
bold
Type
boolean
Description
Whether the text is bold.
Name
uppercase
Type
boolean
Description
Whether the text shows in capitals.
Name
fullscreen
Type
boolean
Description
Whether the message fills the Viewer and hides the timer.

Request

POST

/rooms/{room_id}/messages

curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Five minutes left","color":"red","bold":true}'

Response 201

{
  "ok": true,
  "message": "Message created",
  "data": {
    "_id": "a2Bc9dEf0GhI",
    "_model": "message",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "showing": false,
    "text": "Five minutes left",
    "color": "white",
    "bold": false,
    "uppercase": false,
    "fullscreen": false,
    "source": "operator",
    "submitter_name": null
  }
}

GET/rooms/{room_id}/messages/{message_id}

Get a message

Returns one message.

Path parameters

Name
room_id
Type
string
Required
Description
The room's id, from its address: /o/ROOM_ID/….
Name
message_id
Type
string
Required
Description
The message's id.

Request

GET

/rooms/{room_id}/messages/{message_id}

curl https://app.kloksi.com/api/v1/rooms/ROOM_ID/messages/MESSAGE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "ok": true,
  "message": "Message loaded",
  "data": {
    "_id": "a2Bc9dEf0GhI",
    "_model": "message",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "showing": false,
    "text": "Five minutes left",
    "color": "white",
    "bold": false,
    "uppercase": false,
    "fullscreen": false,
    "source": "operator",
    "submitter_name": null
  }
}

PATCH/rooms/{room_id}/messages/{message_id}

Update a message

Changes only the fields you send.

Path parameters

Name
room_id
Type
string
Required
Description
The room's id, from its address: /o/ROOM_ID/….
Name
message_id
Type
string
Required
Description
The message's id.

Body

Name
text
Type
string
Description
The message text. At most 500 characters.
Name
color
Type
string
Description
The text colour.
Name
bold
Type
boolean
Description
Whether the text is bold.
Name
uppercase
Type
boolean
Description
Whether the text shows in capitals.
Name
fullscreen
Type
boolean
Description
Whether the message fills the Viewer and hides the timer.

Request

PATCH

/rooms/{room_id}/messages/{message_id}

curl -X PATCH https://app.kloksi.com/api/v1/rooms/ROOM_ID/messages/MESSAGE_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Two minutes left"}'

Response 200

{
  "ok": true,
  "message": "Message updated",
  "data": {
    "_id": "a2Bc9dEf0GhI",
    "_model": "message",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "showing": false,
    "text": "Five minutes left",
    "color": "white",
    "bold": false,
    "uppercase": false,
    "fullscreen": false,
    "source": "operator",
    "submitter_name": null
  }
}

DELETE/rooms/{room_id}/messages/{message_id}

Delete a message

Deletes a message.

Path parameters

Name
room_id
Type
string
Required
Description
The room's id, from its address: /o/ROOM_ID/….
Name
message_id
Type
string
Required
Description
The message's id.

Request

DELETE

/rooms/{room_id}/messages/{message_id}

curl -X DELETE https://app.kloksi.com/api/v1/rooms/ROOM_ID/messages/MESSAGE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 204

204 No Content

POST/rooms/{room_id}/messages/{message_id}/show

Show a message

Shows the message on the outputs. Any other message showing is hidden.

Path parameters

Name
room_id
Type
string
Required
Description
The room's id, from its address: /o/ROOM_ID/….
Name
message_id
Type
string
Required
Description
The message's id.

Request

POST

/rooms/{room_id}/messages/{message_id}/show

curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/messages/MESSAGE_ID/show \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "ok": true,
  "message": "Message shown",
  "data": {
    "_id": "a2Bc9dEf0GhI",
    "_model": "message",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "showing": false,
    "text": "Five minutes left",
    "color": "white",
    "bold": false,
    "uppercase": false,
    "fullscreen": false,
    "source": "operator",
    "submitter_name": null
  }
}

POST/rooms/{room_id}/messages/{message_id}/hide

Hide a message

Takes the message off the outputs.

Path parameters

Name
room_id
Type
string
Required
Description
The room's id, from its address: /o/ROOM_ID/….
Name
message_id
Type
string
Required
Description
The message's id.

Request

POST

/rooms/{room_id}/messages/{message_id}/hide

curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/messages/MESSAGE_ID/hide \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "ok": true,
  "message": "Message hidden",
  "data": {
    "_id": "a2Bc9dEf0GhI",
    "_model": "message",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "showing": false,
    "text": "Five minutes left",
    "color": "white",
    "bold": false,
    "uppercase": false,
    "fullscreen": false,
    "source": "operator",
    "submitter_name": null
  }
}

POST/rooms/{room_id}/messages/{message_id}/toggle

Show or hide a message

Shows the message if it's hidden, and hides it if it's showing.

Path parameters

Name
room_id
Type
string
Required
Description
The room's id, from its address: /o/ROOM_ID/….
Name
message_id
Type
string
Required
Description
The message's id.

Request

POST

/rooms/{room_id}/messages/{message_id}/toggle

curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/messages/MESSAGE_ID/toggle \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "ok": true,
  "message": "Message shown",
  "data": {
    "_id": "a2Bc9dEf0GhI",
    "_model": "message",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "showing": false,
    "text": "Five minutes left",
    "color": "white",
    "bold": false,
    "uppercase": false,
    "fullscreen": false,
    "source": "operator",
    "submitter_name": null
  }
}