SDK

Our SDK allows you to programatically control the chat and receive events from the chat.

This allows you to create your own custom chat UI using HTML and JavaScript and much more.

If you're just interested in embedding your chat onto your website, you can check out our embed guide here.

The SDK is available on the Community plan or higher.

Many of the same methods are also supported via our API and webhooks if you'd like to make server side requests.

Setting up the SDK

Setting up the SDK just requires a few lines of code.

Go to the embed chat page for the chatroom you'd like to embed, and click on "Get HTML Code".

Once you see the HTML code, scroll down until you see "Advanced: SDK", and click on "Show SDK embed code".

You can also enable the "Hide Chat" option here, if you'd like to build your own custom UI.

Tips

Calling methods

When calling methods, we recommend using user IDs instead of usernames if user IDs are available as this is faster.

For example:

Use minnit.banUser({"userid": 123, "duration": 24}); instead of minnit.banUser({"username": "Test", "duration": 24});

Customizing appearance or text

If you're customizing the chat appearance or text when the chat first loads, we recommend using the chatLoaded event and then calling these methods.

For example:

minnit.on("chatLoaded", function(data) { minnit.customizeAppearance({"css": "#topBar-menu-button{display: none}", "theme": "dark", "messagebubblecolor": "pink", "accentcolor": "#FFFFFF"}); minnit.customizeText({"text.changenickname":"Change Name"}); });

Building your own UI

On the embed page, you can enable the headless option to hide the chat.

Building your own UI will require developer experience, but you'll be able to fully control the design of the chat.

We recommend using Zero-Click SSO to automatically log your users in, since you won't be able to use our UI for account registrations.

Embedding multiple chats on the same page

If you're using the SDK and embedding multiple chats on the same page, you'll need to make a few changes to your embed code to ensure that you can send actions to each chat and receive events from each chat separately.

There are two changes you need to make:

Each iframe must have a unique ID
Your embed code should contain &sdkidentifier=uniqueIdentifierHere, and this should be declared when setting up the SDK.

Here's a full example:

<script src="https://minnit.chat/js/chatsdk.js?c=1752216300" defer></script>

<script src="https://minnit.chat/js/embed.js?c=1752216300" defer></script>

<span style="display: none;" class="minnit-chat-sembed" data-iframeid="chat1" data-chatname="https://example.minnit.io/c/Main?embed&sdk&sdkidentifier=chat1" data-style="width:90%; height:500px; max-height:90vh;" data-version="1.52">Chat</span>

<span style="display: none;" class="minnit-chat-sembed" data-iframeid="chat2" data-chatname="https://example.minnit.io/c/Main?embed&sdk&sdkidentifier=chat2" data-style="width:90%; height:500px; max-height:90vh;" data-version="1.52">Chat</span>

let minnit1;
let minnit2;

document.addEventListener("DOMContentLoaded", function(event) {
   minnit1 = new MinnitChat({"iframe": document.getElementById("chat1"), "sdkidentifier": "chat1"});

   minnit1.on("messageHistory", function(data) {
       console.log("received message history from chat 1:", data);
   });

   minnit1.on("message", function(data) {
       console.log("received message from chat 1:", data);
   });

   minnit2 = new MinnitChat({"iframe": document.getElementById("chat2"), "sdkidentifier": "chat2"});

   minnit2.on("messageHistory", function(data) {
       console.log("received message history from chat 2:", data);
   });

   minnit2.on("message", function(data) {
       console.log("received message from chat 2:", data);
   });
});

Methods

Perform actions in the chat such as sending/deleting messages, banning users etc.

sendMessage - Send a chat message

Name	Description	Required	Type
message	The message you'd like to send	Yes	string
directmessage	Set to true if you're sending a direct message	No	boolean
username	The username you'd like to send the direct message to, if you are sending a direct message	No	string
userid	The user ID you'd like to send the direct message to, if you are sending a direct message	No	string/number

If you are sending a direct message, you can include the username or user ID when sending a message.

Example

minnit.sendMessage({"message": "Hello world", "userid": 123});

getMessages - Get chat messages

This option allows you to get the chat message history. This returns up to 40 messages at once.

Name	Description	Required	Type
before_timestamp	Older messages than this timestamp will be turned. This must be a UNIX timestamp in seconds.	Yes	string
pending_messages	Set to true if you'd like to retrieve pending messages if the message pre-approval setting is turned on	No	boolean

Example

minnit.getMessages({"before_timestamp": 1757909660, "pending_messages": true});

Response

The response is a JSON object with a messages array.
Each element in the array represents a single message object.

deleteMessage - Delete a message

Name	Description	Required	Type
message_id	The ID of message you'd like to delete	Yes	string

Example

minnit.deleteMessage({"message_id": "9fa39341-20f6-4c3c-b017-c8e0f08a2c9c"});

restoreMessage - Restore a message

This allows you to restore a message that was previously deleted.

Name	Description	Required	Type
message_id	The ID of message you'd like to restore	Yes	string

Example

minnit.restoreMessage({"message_id": "9fa39341-20f6-4c3c-b017-c8e0f08a2c9c"});

reactToMessage - React to a message

This allows you to restore a message that was previously deleted.

Name	Description	Required	Type
message_id	The ID of message you'd like to restore	Yes	string
reaction	The reaction you'd like to add	Yes	string

Example

minnit.reactToMessage({"message_id": "9fa39341-20f6-4c3c-b017-c8e0f08a2c9c", "reaction": "👍"});

Note: Message reactions must be set up in Chat Settings.

approveMessage - Approve a pending message

This allows you to approve a message if the message pre-approval setting is turned on.

Name	Description	Required	Type
message_id	The ID of message you'd like to approve	Yes	string

Example

minnit.approveMessage({"message_id": "9fa39341-20f6-4c3c-b017-c8e0f08a2c9c"});

rejectMessage - Reject a pending message

This allows you to reject a message if the message pre-approval setting is turned on.

Name	Description	Required	Type
message_id	The ID of message you'd like to reject	Yes	string

Example

minnit.rejectMessage({"message_id": "9fa39341-20f6-4c3c-b017-c8e0f08a2c9c"});

openConversation - Open a conversation with another user

Name	Description	Required	Type
username	The username of the user you'd like to open the conversation with	Yes	string
userid	The user ID of the user you'd like to open the conversation with	Yes	string/number

You can provide either a username or user ID when opening a conversation.

Example

minnit.openConversation({"userid": 123});

Response

If you enter a username that does not exist, a response with User does not exist will be returned.

changeNickname - Change your nickname

Name	Description	Required	Type
nickname	The new nickname you'd like to use	Yes	string

Example

minnit.changeNickname({"nickname": "My new nickname"});

getActiveChannels - Get active channels

Example

let activeChannels = await minnit.getActiveChannels();
console.log(activeChannels);

Response

{
  "automatic_channels": [],
  "custom_channels": {
    "test": {
      "display_name": "Test Room",
      "minimum_rank_to_join": "visitor",
      "minimum_rank_to_talk": "visitor",
      "order": 0
    }
  }
}

Root Object

Field	Type	Description
`automatic_channels`	array	List of system/automatic channels.
`custom_channels`	object	Key-value mapping of custom channels, where the key is the channel identifier.

Custom Channel Object

Field	Type	Description
`display_name`	string	Human-readable name of the channel.
`minimum_rank_to_join`	string	Minimum rank required to join (`visitor`, `regular`, `moderator`, `manager`, `owner`).
`minimum_rank_to_talk`	string	Minimum rank required to send messages `visitor`, `regular`, `moderator`, `manager`, `owner`.
`order`	number	Sort order for displaying the channel.

moveToChannel - Move to a channel

Example

Name	Description	Required	Type
channel	The channel you'd like to move to	Yes	string

minnit.moveToChannel({"channel": "test"});

lookUpUser - Search for user

This option allows you to retrieve details about a user, e.g. their user ID, nickname, profile picture, rank, and much more.

Name	Description	Required	Type
username	The username of the user you'd like to look up	Yes	string

let userDetails = await minnit.lookUpUser({"userid": 123});
console.log(userDetails);

Response

{
    "userid": "123",
    "username": "John",
    "nickname": "John Smith",
    "profile_picture_url": "https://cdn.minnit.chat/media/avatar_test.png"
}

Field	Type	Description
`userid`	string	The ID of the user.
`username`	string	The username of the user.
`nickname`	string	The nickname of the user.
`profile_picture_url`	string	The profile picture URL of the user.
`does_not_exist`	boolean	Whether the user exists.

customizeText - Customize texts in the chat

This is available on the Pro plan and higher.

This feature is identical to the Language & Text Strings feature in Chat Settings.

This allows you to override text shown in the chat, for example you can modify "Change Nickname" and replace it with "Change Name".

To use this option, you'll need to send an object with the values you'd like to replace.

You can view the list of text strings here.

The chatLoaded event should be used when customizing the text if the text must be changed when the chat first loads.

Example

minnit.on("chatLoaded", function(data) {
    minnit.customizeText({"text.changenickname":"Change Name"});
});

customizeAppearance - Customize appearance

Name	Description	Required	Type
css	The CSS you'd like to apply	No	string
theme	The theme you'd like to use. Available options are `bright`, `gray`, `dark`	No	string
messagebubblecolor	The message bubble color you'd like to use. Available options are `none`, `green`, `blue`, `orange`, `pink`, `skyblue`, `salmon`, `purple`, `gray`	No	string
accentcolor	The accent color you'd like to use as a HEX color code, e.g. #FFFFFF for white.	No	string

The chatLoaded event should be used when customizing the appearance of the chat if the appearance must be changed when the chat first loads.

Example

minnit.on("chatLoaded", function(data) {
    minnit.customizeAppearance({"css": "#topBar-menu-button{display: none}", "theme": "dark", "messagebubblecolor": "pink", "accentcolor": "#FFFFFF"});
});

changeUserRank - Change the rank of a user

Note: Only moderators and higher can perform this action.

Name	Description	Required	Type
username	The username of the user whose rank you'd like to change	Yes	string
userid	The user ID of the user whose rank you'd like to change	Yes	string/number
rank	The rank you'd like the user to have. Options are `visitor`, `regular`, `moderator`, `manager`, `owner`	Yes	string
expire_hours	When you'd like the rank to expire in hours. Leave blank for permanent	Yes	number

Example

minnit.changeUserRank({"userid": 123, "rank": "moderator", "expire_hours" 8});

Response

If you enter a username that does not exist, a response with User does not exist will be returned.

kickUser - Kick a user

Note: Only moderators and higher can perform this action.

Name	Description	Required	Type
username	The username of the user who you'd like to kick	Yes	string
userid	The user ID of the user who you'd like to kick	Yes	string/number
reason	The reason for the kick	No	string

Example

minnit.kickUser({"userid": 123, "reason": "Testing Kick"});

Response

If you enter a username that does not exist, a response with User does not exist will be returned.

banUser - Ban a user

Note: Only moderators and higher can perform this action.

Name	Description	Required	Type
username	The username of the user who you'd like to ban	Yes	string
userid	The user ID of the user who you'd like to ban	Yes	string/number
reason	The reason for the ban	No	string
duration	The length of the ban in hours. Bans over `8760` hours will be treated as a permanent ban.	Yes	string
ban_forever	If you'd like this to be a permanent ban	No	boolean
delete_messages	If you'd like to automatically delete messages from the banned user	No	boolean
silent_ban	If you'd like to treat it as a silent ban	No	boolean

Example

minnit.banUser({"userid": 123, "reason": "Testing Ban", "duration": 24});

Response

If you enter a username that does not exist, a response with User does not exist will be returned.

unBanUser - UnBan a user

Note: Only moderators and higher can perform this action.

Name	Description	Required	Type
username	The username of the user who you'd like to unban	Yes	string
userid	The user ID of the user who you'd like to unban	Yes	string/number

Example

minnit.unBanUser({"userid": 123});

Response

If you enter a username that does not exist, a response with User does not exist will be returned.

connect - Reconnect to the chat

This method is useful if you'd like to reconnect to the chat after a ban or kick is over.

The chat automatically manages reconnecting in all other scenarios (e.g. user's connection drops).

Example

minnit.connect();

Events

Receive events in the chat such as messages, when users join or leave, and much more.

chatLoaded - Receive event when the chat loads

This event is helpful when you'd like to customize the appearance or customize text in the chat when it loads, or perform other actions when the chat loads.

minnit.on("chatLoaded", function() {
  minnit.customizeAppearance({"theme": "dark", "messagebubblecolor": "pink", "accentcolor": "#FFFFFF"});
});

connected - Receive event when the user connects

This event is helpful when you'd like to perform certain actions when the user first connects to the chat.

minnit.on("connected", function() {
  console.log("connected to the chat");
});

disconnected - Receive event when the user disconnects

Disconnections can happen if the user has a spotty internet connection -- the chat will automatically try to reconnect.

You can use this event to avoid calling methods while the user is disconnected, or queue methods for when the user reconnects later.

minnit.on("disconnected", function() {
  console.log("disconnected from the chat");
});

userList - Receive data on users in the chat

minnit.on("userList", function(data) {
  console.log("userlist:", data);
});

Response

{
    "type": "entire_userlist",
    "data": {
        "123": {
            "username": "John",
            "nickname": "John Smith",
            "profile_picture_url": "https://cdn.minnit.chat/media/avatar_test.png",
            "rank": 0,
            "rank_expire_timestamp": 0,
            "number_of_connections": 1,
            "join_timestamp": 1758811024
        },
        "456": {
            "username": "Jane",
            "nickname": "Jane Smith",
            "profile_picture_url": "https://cdn.minnit.chat/media/avatar_test.png",
            "rank": 0,
            "rank_expire_timestamp": 0,
            "number_of_connections": 1,
            "join_timestamp": 1758811028
        }
    }
}

Root Object

Field	Type	Description
`type`	string	Type of update. Possible values: `"entire_userlist"`, `"user_joined"`, `"user_left"`, `"user_data_changed"`.
`data`	object	Mapping of user IDs to user objects.

User Object

Field	Type	Description
`username`	string	The account username of the user.
`nickname`	string	The user’s display name in the chat.
`profile_picture_url`	string	URL of the user’s profile picture.
`rank`	number	Value indicating the user’s rank. Options are `visitor`, `regular`, `moderator`, `manager`, `owner`
`rank_expire_timestamp`	number	Unix timestamp when the rank expires (0 if permanent).
`number_of_connections`	number	Number of active connections this user has open.
`join_timestamp`	number	Unix timestamp of when the user joined the room.

messageHistory - Receive message history

This option allows you to receive the message history when the user signs in. This returns up to 40 messages at once.

Example

minnit.on("messageHistory", function(data) {
    console.log("message history:", data);
});

Response

The response is a JSON object with a messages array.
Each element in the array represents a single message object.

message - Receive new messages

minnit.on("message", function(data) {
    console.log("received message:", data);
});

Response

The response represents a single message object.

pendingMessage - Receive new pending messages

Receive messages pending approval if the message pre-approval setting is turned on.

minnit.on("pendingMessage", function(data) {
    console.log("received pending message:", data);
});

Response

The response represents a single message object.

unreadMessages - Receive unread direct messages

This event is triggered when the user has unread direct messages when the chat loads and the user connects.

minnit.on("unreadMessages", function(data) {
    console.log("received unread messages:", data);
});

Response

The response is a JSON object with a messages array.
Each element in the array represents a single message object.

messageAttachmentUpdate - Receive message attachment updates

Receive message attachment updates.

minnit.on("messageAttachmentUpdate", function(data) {
    console.log("received message attachment update:", data);
});

Response

{
    "type": "link",
    "attachment_id": "waHR0cDovL21pbm5pdC5jaGF0",
    "title": "Minnit Chat: Add a group chat for your website, live event...",
    "subtitle": "Minnit allows you to easily create a group chat for your w...",
    "icon_url": "https://minnit.chat/images/apple-touch-icon.png"
}

Field	Type	Description
`type`	string	Options are: `link`.
`icon_url`	string	Link to an icon for this link, if applicable.
`attachment_id`	string	The ID of this attachment.
`title`	string	The title of this attachment.
`subtitle`	string	The subtitle of this attachment.

messageReaction - Receive reactions to messages

This event is triggered whenever a user adds or removes a reaction on a message.

minnit.on("messageReaction", function(data) {
    console.log("received message reaction:", data);
});

Response

{
    "message_id": "1883d14b-3469-4f2a-a393-0389850b3f2a",
    "reaction": "👍",
    "reactor": "456",
    "added": true
}

Field	Type	Description
`message_id`	string	The unique ID of the message being reacted to.
`reaction`	string	The emoji used.
`reactor`	string	The user ID of the person who reacted.
`added`	boolean	Indicates if the reaction count increased (`true`) or decreased (`false`) for this reaction.

selfModerationAction - Receive data on actions affecting the user

This event is triggered when you're banned, kicked or moved to another channel.

minnit.on("selfModerationAction", function(data) {
    console.log("received action info:", data);
});

Response

{
    "type": "banned",
    "end_timestamp": 1767139200
}

Field	Type	Description
`type`	string	Options are `banned`, `kicked`, `moved`, `ip_blacklisted`, `exceeded_sign_in_attempts`
`end_timestamp`	number	UNIX timestamp in seconds for when the ban or kick ends.
`banned_forever`	boolean	Whether the ban is permanent.
`moved_to`	string	The name of the channel the user was moved to, if applicable.

The ip_blacklisted type applies if the IP is detected as a proxy/VPN and Block VPNs/Proxies is turned on.

The exceeded_sign_in_attempts type applies if the user repeatedly disconnects and reconnects and triggers rate limiting.

maximumConnectionsExceeded - Receive event when the chat has exceeded its maximum connections

This event is triggered when you're banned, kicked or moved to another channel.

minnit.on("maximumConnectionsExceeded", function() {
    console.log("maximum connections exceeded, cannot join the chat");
});

Common Responses

The following responses are used for several methods and/or events.

Message Object

{
    "userid": "123",
    "username": "John",
    "nickname": "John Smith",
    "profile_picture_url": "https://cdn.minnit.chat/avatar_test.png",
    "rank_expire_timestamp": "0",
    "rank": "visitor",
    "message_id": "881edfc4-0c6d-4f56-a17f-19c45fe4ed3c",
    "timestamp": "1758810288",
    "message": "hello world",
    "attachment": {}
}

Field	Type	Description
`userid`	string	Unique ID of the user who sent the message.
`username`	string	User’s account username.
`nickname`	string	Display name/nickname in chat.
`profile_picture_url`	string	URL of the user’s profile picture (may be empty).
`rank_expire_timestamp`	string	UNIX timestamp in seconds when the user’s rank expires (if applicable). `"0"` means no expiry.
`rank`	string	Value indicating the user’s rank. Options are `visitor`, `regular`, `moderator`, `manager`, `owner`
`message_id`	string	Unique identifier for the message.
`timestamp`	string	UNIX timestamp in seconds when the message was sent.
`message`	string	The actual chat message text.
`attachment`	object	Attachment object. `{}` if none.

Attachment Object

{
    "attachment": {
        "attachment_id": "waHR0cHM6Ly9taW5uaXQuY2hhdA==",
        "url": "https://minnit.chat",
        "title": "Minnit Chat: Add a group chat for your website, live event...",
        "subtitle": "Minnit allows you to easily create a group chat for your w...",
        "iconurl": "https://minnit.chat/images/apple-touch-icon.png",
        "type": "link"
    }
}

Field	Type	Description
`attachment_id`	string	Encoded unique identifier for the attachment. The `messageAttachmentUpdate` event will reference this ID if data changes for this attachment.
`url`	string	Link URL.
`title`	string	Title of the link/attachment.
`subtitle`	string	Additional description or preview text.
`icon_url`	string	Icon image URL for the attachment.
`type`	string	Type of attachment (options are `image`, `link`, `file`).

Setting up the SDK​

Tips​

Calling methods​

Customizing appearance or text​

Building your own UI​

Embedding multiple chats on the same page​

Methods​

sendMessage - Send a chat message​

getMessages - Get chat messages​

deleteMessage - Delete a message​

restoreMessage - Restore a message​

reactToMessage - React to a message​

approveMessage - Approve a pending message​

rejectMessage - Reject a pending message​

openConversation - Open a conversation with another user​

changeNickname - Change your nickname​

getActiveChannels - Get active channels​

Root Object​

Custom Channel Object​

moveToChannel - Move to a channel​

lookUpUser - Search for user​

customizeText - Customize texts in the chat​

customizeAppearance - Customize appearance​

changeUserRank - Change the rank of a user​

kickUser - Kick a user​

banUser - Ban a user​

unBanUser - UnBan a user​

connect - Reconnect to the chat​

Events​

chatLoaded - Receive event when the chat loads​

connected - Receive event when the user connects​

disconnected - Receive event when the user disconnects​

userList - Receive data on users in the chat​

Root Object​

User Object​

messageHistory - Receive message history​

message - Receive new messages​

pendingMessage - Receive new pending messages​

unreadMessages - Receive unread direct messages​

messageAttachmentUpdate - Receive message attachment updates​

messageReaction - Receive reactions to messages​

selfModerationAction - Receive data on actions affecting the user​

maximumConnectionsExceeded - Receive event when the chat has exceeded its maximum connections​

Common Responses​

Message Object​

Attachment Object​

Setting up the SDK

Tips

Calling methods

Customizing appearance or text

Building your own UI

Embedding multiple chats on the same page

Methods

sendMessage - Send a chat message

getMessages - Get chat messages

deleteMessage - Delete a message

restoreMessage - Restore a message

reactToMessage - React to a message

approveMessage - Approve a pending message

rejectMessage - Reject a pending message

openConversation - Open a conversation with another user

changeNickname - Change your nickname

getActiveChannels - Get active channels

Root Object

Custom Channel Object

moveToChannel - Move to a channel

lookUpUser - Search for user

customizeText - Customize texts in the chat

customizeAppearance - Customize appearance

changeUserRank - Change the rank of a user

kickUser - Kick a user

banUser - Ban a user

unBanUser - UnBan a user

connect - Reconnect to the chat

Events

chatLoaded - Receive event when the chat loads

connected - Receive event when the user connects

disconnected - Receive event when the user disconnects

userList - Receive data on users in the chat

Root Object

User Object

messageHistory - Receive message history

message - Receive new messages

pendingMessage - Receive new pending messages

unreadMessages - Receive unread direct messages

messageAttachmentUpdate - Receive message attachment updates

messageReaction - Receive reactions to messages

selfModerationAction - Receive data on actions affecting the user

maximumConnectionsExceeded - Receive event when the chat has exceeded its maximum connections

Common Responses

Message Object

Attachment Object