API

Minnit's API allows you to automate various tasks on your Organization by making requests to our servers. This page will cover how to get started using the API.

The API is available for Organizations on the Basic plan or higher.

Getting Started

To get your API Endpoint & Key, go to your Organization, and click "Organization Settings", then select "API".

You are able to type any key of your choosing; we recommend using a randomizer of your choice for maximum security, rather than hand-inputting a key.

Required parameters

All requests must include your API key as the X-Key header.

Actions are sent via the action parameter. For instance, creating a chatroom will have the key action with value createchat.

Read on to learn more about what each action can do.

createchat - Creating a chatroom POST

You are able to create chatrooms using the API.

Name	Description	Required	Constraints
action	Must be set to createchat	Yes
chatname	The name of the chat you want to create, e.g. SecondChat	Yes	Max length: 50 characters
copyfrom	Allows you to copy settings from an existing chat. You can create multiple chatrooms to act as templates, and copy those settings over to the newly-created chatrooms.	No	Max length: 50 characters
managerkey	If set to true this will generate, store, and return a "Manager Key" for the chatroom. Click here to learn more about staff keys.	No
maxusers	The maximum number of users that can connect to this specific chat. Use this if you want to reduce the ability for a single chat to take up your entire Organization's allotment of users.	No	Number only

cURL (example)

curl -X POST -d "action=createchat&chatname=SecondChat" https://example.minnit.org/page/api \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "X-Key:12345"

Response (example)

{
    "success": true,
    "chatname": "SecondChat",
    "response": "Chat created"
}

deletechat - Delete a chatroom POST

You can instantly delete a chatroom using the API.

Name	Description	Required	Constraints
action	Must be set to deletechat	Yes
chatname	The name of the chat you want to delete, e.g. SecondChat	Yes	Max length: 50 characters

cURL (example)

curl -X POST -d "action=deletechat&chatname=SecondChat" https://example.minnit.org/page/api \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "X-Key:12345"

Response (example)

{
    "success": true,
    "response": "Chat deleted"
}

pause - Pause your chat POST

You can permanently pause your chat using the API.

Name	Description	Required	Constraints
action	Must be set to pause	Yes
chatname	The name of the chat you'd like the notice to be placed on, e.g. Main	Yes	Max length: 50 characters

cURL (example)

curl -X POST -d "action=pause&chatname=Main" https://example.minnit.org/page/api \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "X-Key:12345"

Response (example)

{
    "success": true,
    "chatname": "main",
    "response": "Chat paused"
}

unpause - Unpause your chat POST

You can unpause your chat using the API.

Name	Description	Required	Constraints
action	Must be set to unpause	Yes
chatname	The name of the chat you'd like the notice to be placed on, e.g. Main	Yes	Max length: 50 characters

cURL (example)

curl -X POST -d "action=unpause&chatname=Main" https://example.minnit.org/page/api \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "X-Key:12345"

Response (example)

{
    "success": true,
    "chatname": "main",
    "response": "Chat paused"
}

setnotice - Set a pinned notice POST

You can set pinned notices in the chatroom using the API.

Name	Description	Required	Constraints
action	Must be set to setnotice	Yes
chatname	The name of the chat you'd like the notice to be placed on, e.g. Main	Yes	Max length: 50 characters
noticetext	The text you'd like placed in the notice, e.g. hello world. URLs will automatically be parsed in the user's browser so they may click on them. HTML will not render.	Yes	Max length: 2000 characters

cURL (example)

curl -X POST -d "action=setnotice&chatname=Main&noticetext=hello%20world" https://example.minnit.org/page/api \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "X-Key:12345"

Response (example)

{
    "success": true,
    "chatname": "main",
    "response": "Notice set"
}

kick - Kick a user POST

You can kick users using the API.

You can combine webhooks with this API to create your own bot that moderates your chat.

Name	Description	Required	Constraints
action	Must be set to kick	Yes
chatname	The name of the chat you'd like to kick the user from, e.g. Main	Required	Max length: 50 characters
channel	The channel the user is currently signed into (if any). Will default to the main channel if not included	No	Max length: 50 characters
username	The username of the user you're trying to kick.	Required (if userid is not provided)
userid	The user ID of the user you're trying to kick.	Required (if username is not provided)
reason	The reason for the kick.	No

cURL (example)

curl -X POST -d "action=kick&chatname=Main&username=testuser&reason=inappropriate%20language" https://example.minnit.org/page/api \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "X-Key:12345"

Response (example)

{
    "success": true,
    "response": "User kicked"
}

ban - Ban a user POST

You can ban users for a specific amount of time using the API.

You can combine webhooks with this API to create your own bot that moderates your chat.

Name	Description	Required	Constraints
action	Must be set to ban	Required
chatname	The name of the chat you'd like to ban the user on, e.g. Main	Required	Max length: 50 characters
channel	The channel the user is currently signed into (if any). Will default to the main channel if not included	Optional	Max length: 50 characters
username	The username of the user you're trying to ban. This or the user ID must be included.	Required (if userid is not provided)
userid	The user ID of the user you're trying to ban. This or the username must be included.	Required (if username is not provided)
duration	You can send a duration in hours. Values from 0.01 to 8760 are accepted. If you do not send a duration, or the duration you send is invalid, it will default to a permanent ban.	Optional
reason	The reason for the ban.	Optional
msgid	The ID of the message that you're banning the user for.	Optional
deletemessages	Set to true if you'd like all of the user's messages to be deleted	Optional
silentban	Set to true if you'd like to silently ban the user	Optional

cURL (example)

curl -X POST -d "action=ban&chatname=Main&username=testuser&duration=12&reason=inappropriate%20language" https://example.minnit.org/page/api \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "X-Key:12345"

Response (example)

{
    "success": true,
    "response": "User banned"
}

unban - UnBan a user POST

You can unban users using the API.

You can combine webhooks with this API to create your own bot that moderates your chat.

Name	Description	Required	Constraints
action	Must be set to unban	Required
chatname	The name of the chat you'd like to unban the user from, e.g. Main	Required	Max length: 50 characters
channel	The channel the user is was signed into (if any). Will default to the main channel if not included	Optional	Max length: 50 characters
username	The username of the user you're trying to unban.	Required (if userid is not provided)
userid	The user ID of the user you're trying to unban.	Required (if username is not provided)

cURL (example)

curl -X POST -d "action=unban&chatname=Main&username=testuser" https://example.minnit.org/page/api \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "X-Key:12345"

Response (example)

{
    "success": true,
    "response": "User unbanned"
}

setrank - Set the rank of a user POST

You can set a user's rank in the chat — make them an owner, manager, moderator, regular, or visitor (unranked).

Note: By giving users owner in a chatroom, they will have access to the chat settings menu for that chatroom.

Guest accounts can not be made owner.

Name	Description	Required	Constraints
action	Must be set to setrank	Required
chatname	The name of the chat you'd like to set the user's rank on, e.g. Main	Required	Max length: 50 characters
username	The username of the user you're trying to set the rank of. This or the user ID must be included.	Required (if userid is not provided)
userid	The user ID of the user you're trying to set the rank of. This or the username must be included.	Required (if username is not provided)
rank	Desired rank.	Required	Accepts visitor, regular, moderator, manager, or owner

cURL (example)

curl -X POST -d "action=setrank&chatname=Main&username=testuser&rank=moderator" https://example.minnit.org/page/api \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "X-Key:12345"

Response (example)

{
    "success": true,
    "response": "Successfully set rank"
}

deletemessage - Delete a chat message POST

You can delete chat messages using the API.

You can combine webhooks with this API to create your own bot that moderates your chat.

Name	Description	Required	Constraints
action	Must be set to deletemessage	Yes
chatname	The name of the chat you'd like to delete the message from, e.g. Main	Yes	Max length: 50 characters
msgid	The ID of the message you'd like to delete	Yes

cURL (example)

curl -X POST -d "action=deletemessage&chatname=Main&msgid=9f5bcfa7-db10-463c-8455-c456aa1131b3" https://example.minnit.org/page/api \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "X-Key:12345"

Response (example)

{
    "success": true,
    "response": "Message deleted"
}

exportaccounts - Export account data POST

You can export account data using the API if your Organization is on the Pro plan or higher.

Name	Description	Required	Constraints
action	Must be set to exportaccounts	Yes
beforets	Set to unix timestamp in seconds if you'd like to include accounts created before this time	No
afterts	Set to unix timestamp in seconds if you'd like to include accounts created after this time	No
withmarketingconsentonly	Set to true if you'd like to include accounts that have given marketing consent only	No
firstchat	Include a chat name to limit your results to only users who connected to that chatroom as their first chat. Example: If someone registers and joins "Main", their first chat will be stored as "Main".	No
Data To Include	At least one of the values below must be included, otherwise the export data will be empty
userid	Set to true if you'd like to include the user ID in the export data	No
username	Set to true if you'd like to include the username in the export data	No
nickname	Set to true if you'd like to include the nickname in the export data	No
email	Set to true if you'd like to include the email in the export data	No
emailactivated	Set to true if you'd like to include the email activation status in the export data	No
marketingconsent	Set to true if you'd like to include the marketing consent status in the export data	No
protected	Set to true if you'd like to include the the account data protected status in the export data. Account data may be protected if a user logs in using a social login provider if you aren't using custom credentials. Read more about using custom credentials.	No
avatar	Set to true if you'd like to include the avatar URL in the export data	No
attributes	Set to true if you'd like to include the account attributes in the export data	No
ssolinks	Set to true if you'd like to include the SSO services linked to this account in the export data	No
registrationip	Set to true if you'd like to include the registration IP in the export data	No
lastloginip	Set to true if you'd like to include the last login IP in the export data	No
createtimestamp	Set to true if you'd like to include the account creation timestamp in the export data	No
lastactivetimestamp	Set to true if you'd like to include the account last activity timestamp in the export data	No

cURL (example)

curl -X POST -d "action=exportaccounts&userid=1&username=1&email=1&avatar=1" https://example.minnit.org/page/api \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "X-Key:12345"

Response (example)

{
    "success": true,
    "results": [
        {
            "avatar_url": "https://minnit.chat/images/userdefault.svg",
            "email": "[email protected]",
            "nickname": "Test",
            "userid": "1",
            "username": "Test"
        },
        {
            "avatar_url": "https://minnit.chat/images/userdefault.svg",
            "email": "[email protected]",
            "nickname": "Minnit",
            "userid": "2",
            "username": "Minnit"
        }
    ]
}

createaccount - Create an account POST

You can create accounts using the API if your Organization is on the Pro plan or higher.

Name	Description	Required	Constraints
action	Must be set to createaccount	Yes
username	Username for the account (must be unique)	Yes	Max length: 500 characters
password	Password for the account	Yes	Max length: 100 characters
nickname	Nickname for the account (does not need to be unique)	No	Max length: 500 characters
avatar	URL for the account avatar	No	Max length: 500 characters
email	Email for the account	No	Max length: 300 characters
emailverified	Set to true if the email has been verified	No

cURL (example)

curl -X POST -d "action=createaccount&username=Jeff&password=aXnLeIZ" https://example.minnit.org/page/api \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "X-Key:12345"

Response (example)

{
    "success": true,
    "response": "Account created"
}

sendmessage - Send chat messages POST

You can send messages in main chat using the API.

You can combine webhooks with this API to create your own bot that responds to messages from users.

Name	Description	Required	Constraints
action	Must be set to sendmessage	Yes	Max length: 10,000 characters
message	The message you'd like to send	Yes
chatname	The name of the chat you'd like to send the message to	Yes
username	The username of the user you'd like the message to be sent under	Yes
channel	The channel you'd like to send the message to. Will default to the main channel if not included	No

cURL (example)

curl -X POST -d "action=sendmessage&chatname=main&username=jeff&message=Hello" https://example.minnit.org/page/api \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "X-Key:12345"

Response (example)

{
    "success": true,
    "response": "Message sent"
}