Webhooks

Webhooks will allow Minnit to send a request to a URL on your website when an action is performed in your chatroom.

Currently, these actions are sending a message, user joining, and user leaving.

You can use this to generate real-time statistics, perform an action on your server when a specific message or keyword is said in the chat, integrate with Zapier and more.

Webhooks can also be combined with our API to create your own bot that responds to messages and moderate the chat.

Webhooks are available on the Community plan and higher.

Events

Chat Messages POST

You can receive notification every time a chat message is sent.

Here's an example of what it will look like when we send a notification:

{
  "type": "chat_message",
  "data": [
    {
      "msg_id": "9f5bcfa7-db10-463c-8455-c456aa1131b3",
      "chat_id": "1",
      "chat_name": "Main",
      "channel": "1",
      "user_id": "123",
      "username": "John",
      "nickname": "John Smith",
      "profile_picture_url": "https://minnit.chat/images/userdefault.svg",
      "message": "Hello everyone",
      "rank": "owner",
      "attachment": "https://usercontent.minnitchat.com/media/photo.jpg",
      "ip": "127.0.0.1",
      "timestamp": 1696925870
    }
  ]
}

Key	Example Value	Description
msg_id	9f5bcfa7-db10-463c-8455-c456aa1131b3	The ID the message that was sent
chat_id	1	The ID of your chatroom the message was sent on. This always stays the same even if the chat name is changed
chat_name	Main	The name of your chatroom the message was sent on
channel	Main	The channel within the chatroom the message was sent on
user_id	123	The ID of the user that sent the message
username	John	The username of the user that sent the message
nickname	John Smith	The nickname of the user that sent the message
profile_picture_url	https://minnit.chat/images/userdefault.svg	The profile picture URL of the user that sent the message
message	Hello everyone	The message the user sent
rank	owner	The rank of the user that sent the message. Possible values are: visitor, regular, moderator, manager, owner
attachment	https://usercontent.minnitchat.com/media/photo.jpg	The URL of the attachment sent with the message (if any)
ip	127.0.0.1	The IP address of the user that sent the message
timestamp	1696925870	The UNIX timestamp of when the message was sent

Users joining the chat POST

{
    "type": "user_joined",
    "data": [
        {
            "chat_id": "1",
            "chat_name": "Main",
            "channel": "1",
            "user_id": "123",
            "username": "John",
            "nickname": "John Smith",
            "profile_picture_url": "https://minnit.chat/images/userdefault.svg",
            "rank": "owner",
            "timestamp": 1696925816
        }
    ]
}

Key	Example Value	Description
chat_id	1	The ID of your chatroom the user joined. This always stays the same even if the chat name is changed
chat_name	Main	The name of your chatroom the user joined
channel	Main	The channel within the chatroom the user joined
user_id	123	The ID of the user that joined the chat
username	John	The username of the user that joined the chat
nickname	John Smith	The nickname of the user that joined the chat
profile_picture_url	https://minnit.chat/images/userdefault.svg	The profile picture URL of the user that joined the chat
rank	owner	The rank of the user that joined the chat. Possible values are: visitor, regular, moderator, manager, owner
timestamp	1696925870	The UNIX timestamp of when the user joined the chat

Users leaving the chat POST

{
    "type": "user_left",
    "data": [
        {
            "chat_id": "1",
            "chat_name": "Main",
            "channel": "1",
            "user_id": "123",
            "username": "John",
            "nickname": "John Smith",
            "profile_picture_url": "https://minnit.chat/images/userdefault.svg",
            "rank": "owner",
            "timestamp": 1696919619
        }
    ]
}

Key	Example Value	Description
chat_id	1	The ID of your chatroom the user left. This always stays the same even if the chat name is changed
chat_name	Main	The name of your chatroom the user left
channel	Main	The channel within the chatroom that the user left
user_id	123	The ID of the user that left the chat
username	John	The username of the user that left the chat
nickname	John Smith	The nickname of the user that left the chat
profile_picture_url	https://minnit.chat/images/userdefault.svg	The profile picture URL of the user that left the chat
rank	owner	The rank of the user that left the chat. Possible values are: visitor, regular, moderator, manager, owner
timestamp	1696925870	The UNIX timestamp of when the user left the chat

Actions POST

You can receive notification for bans, unbans, kicks, rank changes and message deletions.

Bans

Key	Example Value	Description
action_type	ban	The type of action
chat_id	1	The ID of your chatroom where the user was banned. This always stays the same even if the chat name is changed
chat_name	Main	The name of your chatroom where the user was banned
channel	Main	The channel within the chatroom where the user was banned
user_id	123	The ID of the user that banned the user
username	John	The username of the user that banned the user
nickname	John Smith	The nickname of the user that banned the user
profile_picture_url	https://minnit.chat/images/userdefault.svg	The profile picture URL of the user that banned the user
rank	moderator	The rank of the user that banned the user. Possible values are: visitor, regular, moderator, manager, owner
a_user_id	456	The ID of the user that was banned
a_username	Bad	The username of the user that was banned
a_nickname	Bad Guy	The nickname of the user that was banned
a_profile_picture_url	https://minnit.chat/images/userdefault.svg	The profile picture URL of the user that was banned
a_rank	visitor	The rank of the user that was banned. Possible values are: visitor, regular, moderator, manager, owner
duration	01:00	The length of the ban expressed in HH:MM. For permanent bans, this is set to "forever"
reason	Breaking the rules	The reason for the ban
all_msgs_deleted	true / false	Whether all messages from the user were deleted when they were banned
ip	127.0.0.1	The IP address of the user that was banned (if available)
timestamp	1696925870	The UNIX timestamp of when the user was banned

Unbans

Key	Example Value	Description
action_type	unban	The type of action
chat_id	1	The ID of your chatroom where the user was unbanned. This always stays the same even if the chat name is changed
chat_name	Main	The name of your chatroom where the user was unbanned
channel	Main	The channel within the chatroom where the user was unbanned
user_id	123	The ID of the user that unbanned the user
username	John	The username of the user that unbanned the user
nickname	John Smith	The nickname of the user that unbanned the user
profile_picture_url	https://minnit.chat/images/userdefault.svg	The profile picture URL of the user that unbanned the user
rank	moderator	The rank of the user that unbanned the user. Possible values are: visitor, regular, moderator, manager, owner
a_user_id	456	The ID of the user that was unbanned
a_username	Bad	The username of the user that was unbanned
a_nickname	Bad Guy	The nickname of the user that was unbanned
a_profile_picture_url	https://minnit.chat/images/userdefault.svg	The profile picture URL of the user that was unbanned
a_rank	visitor	The rank of the user that was unbanned. Possible values are: visitor, regular, moderator, manager, owner
timestamp	1696925870	The UNIX timestamp of when the user was unbanned

Kicks

Key	Example Value	Description
action_type	kick	The type of action
chat_id	1	The ID of your chatroom where the user was kicked. This always stays the same even if the chat name is changed
chat_name	Main	The name of your chatroom where the user was kicked
channel	Main	The channel within the chatroom where the user was kicked
user_id	123	The ID of the user that kicked the user
username	John	The username of the user that kicked the user
nickname	John Smith	The nickname of the user that kicked the user
profile_picture_url	https://minnit.chat/images/userdefault.svg	The profile picture URL of the user that kicked the user
rank	moderator	The rank of the user that kicked the user. Possible values are: visitor, regular, moderator, manager, owner
a_user_id	456	The ID of the user that was kicked
a_username	Bad	The username of the user that was kicked
a_nickname	Bad Guy	The nickname of the user that was kicked
a_profile_picture_url	https://minnit.chat/images/userdefault.svg	The profile picture URL of the user that was kicked
a_rank	visitor	The rank of the user that was kicked. Possible values are: visitor, regular, moderator, manager, owner
reason	Breaking the rules	The reason for the kick
ip	127.0.0.1	The IP address of the user that was kicked (if available)
timestamp	1696925870	The UNIX timestamp of when the user was kicked

Message deletions

Key	Example Value	Description
action_type	delete_message	The type of action
chat_id	1	The ID of your chatroom where the message was deleted. This always stays the same even if the chat name is changed
chat_name	Main	The name of your chatroom where the message was deleted
channel	Main	The channel within the chatroom where the message was deleted
user_id	123	The ID of the user that deleted the message
username	John	The username of the user that deleted the message
nickname	John Smith	The nickname of the user that deleted the message
profile_picture_url	https://minnit.chat/images/userdefault.svg	The profile picture URL of the user that deleted the message
rank	moderator	The rank of the user that banned the user. Possible values are: visitor, regular, moderator, manager, owner
a_user_id	456	The ID of the user which sent the deleted message
a_username	Bad	The username of the user which sent the deleted message
a_nickname	Bad Guy	The nickname of the user which sent the deleted message
a_profile_picture_url	https://minnit.chat/images/userdefault.svg	The profile picture URL of the user which sent the deleted message
a_rank	visitor	The rank of the user which sent the deleted message. Possible values are: visitor, regular, moderator, manager, owner
msg_id	9f5bcfa7-db10-463c-8455-c456aa1131b3	The ID of the message which was deleted
msg	Hi everyone	The content of the deleted message
msg_attachment	https://usercontent.minnitchat.com/media/photo.jpg	The URL of the attachment sent with the message (if any)
msg_deleted	true / false	Whether the message was deleted or restored
ip	127.0.0.1	The IP address of the user which sent the deleted message (if available)
timestamp	1696925870	The UNIX timestamp of when the message was deleted

Rank changes

Key	Example Value	Description
action_type	rank_change	The type of action
chat_id	1	The ID of your chatroom where the user's rank was changed. This always stays the same even if the chat name is changed
chat_name	Main	The name of your chatroom where the user's rank was changed
channel	Main	The channel within the chatroom where the user's rank was changed
user_id	123	The ID of the user that changed the rank of the user
username	John	The username of the user that changed the rank of the user
nickname	John Smith	The nickname of the user that changed the rank of the user
profile_picture_url	https://minnit.chat/images/userdefault.svg	The profile picture URL of the user that changed the rank of the user
rank	moderator	The rank of the user that changed the rank of the user. Possible values are: visitor, regular, moderator, manager, owner
a_user_id	456	The ID of the user whose rank was changed
a_username	Bad	The username of the user whose rank was changed
a_nickname	Bad Guy	The nickname of the user whose rank was changed
a_profile_picture_url	https://minnit.chat/images/userdefault.svg	The profile picture URL of the user whose rank was changed
a_rank	visitor	The rank of the user whose rank was changed. Possible values are: visitor, regular, moderator, manager, owner
new_rank	regular	The new rank of the user whose rank was changed. Possible values are: visitor, regular, moderator, manager, owner
rank_length	1709186325	The UNIX timestamp of when the rank will expire. This is set to 0 if the rank is permanent.
timestamp	1708927125	The UNIX timestamp of when the rank was changed

Here's an example of what it will look like when we send a notification:

{
  "type": "chat_action",
  "data": [
    {
      "action_type": "ban",
      "chat_id": "54",
      "chat_name": "Main",
      "channel": "1",
      "user_id": "123",
      "username": "John",
      "nickname": "John Smith",
      "profile_picture_url": "https://minnit.chat/images/userdefault.svg",
      "rank": "moderator",
      "a_user_id": "456",
      "a_username": "Bad",
      "a_nickname": "Bad Guy",
      "a_profile_picture_url": "https://minnit.chat/images/userdefault.svg",
      "a_rank": "visitor",
      "reason": "Breaking the rules",
      "duration": "01:00",
      "all_msgs_deleted": true,
      "ip": "127.0.0.1",
      "timestamp": 1708927125
    },
    {
      "action_type": "unban",
      "chat_id": "54",
      "chat_name": "Main",
      "channel": "1",
      "user_id": "123",
      "username": "John",
      "nickname": "John Smith",
      "profile_picture_url": "https://minnit.chat/images/userdefault.svg",
      "rank": "moderator",
      "a_user_id": "456",
      "a_username": "Bad",
      "a_nickname": "Bad Guy",
      "a_profile_picture_url": "https://minnit.chat/images/userdefault.svg",
      "a_rank": "visitor",
      "timestamp": 1708927125
    },
    {
      "action_type": "kick",
      "chat_id": "54",
      "chat_name": "Main",
      "channel": "1",
      "user_id": "123",
      "username": "John",
      "nickname": "John Smith",
      "profile_picture_url": "https://minnit.chat/images/userdefault.svg",
      "rank": "moderator",
      "a_user_id": "456",
      "a_username": "Bad",
      "a_nickname": "Bad Guy",
      "a_profile_picture_url": "https://minnit.chat/images/userdefault.svg",
      "a_rank": "visitor",
      "reason": "Breaking the rules",
      "ip": "127.0.0.1",
      "timestamp": 1708927125
    },
    {
      "action_type": "delete_message",
      "chat_id": "54",
      "chat_name": "Main",
      "channel": "1",
      "user_id": "123",
      "username": "John",
      "nickname": "John Smith",
      "profile_picture_url": "https://minnit.chat/images/userdefault.svg",
      "rank": "moderator",
      "a_user_id": "456",
      "a_username": "Bad",
      "a_nickname": "Bad Guy",
      "a_profile_picture_url": "https://minnit.chat/images/userdefault.svg",
      "a_rank": "visitor",
      "msg_id": "9f5bcfa7-db10-463c-8455-c456aa1131b3",
      "msg": "Hi everyone",
      "msg_attachment": "https://usercontent.minnitchat.com/media/photo.jpg",
      "msg_deleted": true,
      "ip": "127.0.0.1",
      "timestamp": 1708927125
    },
    {
      "action_type": "rank_change",
      "chat_id": "54",
      "chat_name": "Main",
      "channel": "1",
      "user_id": "123",
      "username": "John",
      "nickname": "John Smith",
      "profile_picture_url": "https://minnit.chat/images/userdefault.svg",
      "rank": "moderator",
      "a_user_id": "456",
      "a_username": "Jack",
      "a_nickname": "Jack Smith",
      "a_profile_picture_url": "https://minnit.chat/images/userdefault.svg",
      "a_rank": "regular",
      "new_rank": "moderator",
      "rank_length": 1709186325,
      "timestamp": 1708927125
    }
  ]
}

Batching

To avoid overwhelming your server, we try to batch messages together before sending them to you.

Notifications are sent on average once every 3 seconds, and we batch multiple messages of the same event.

For instance, if 10 chat messages are sent within 2 seconds, you'll receive all of those messages within one notification.

We also batch the same event types across different chats within your organization if you've set up the same webhook URL for multiple chats.

Events​

Chat Messages POST​

Users joining the chat POST​

Users leaving the chat POST​

Actions POST​

Bans​

Unbans​

Kicks​

Message deletions​

Rank changes​

Batching​