Webhook Event Reference

Dead Simple Chat sends 18 event types. Every request has the same envelope — the event key holds one of the strings below, and data holds the objects listed in the data contains column:

JSON

{
  "event": "new_chatroom_message",
  "data": {
    "chatMessage": { }
  }
}

The field-by-field shape of each object is described in Payloads.

Each event is sent only while its switch is on in Settings -> Webhooks and a Webhook URL is saved. All switches are off by default.

Chat room lifecycle

event	Fires when	data contains	Switch
chatroom_created	A chat room is created, either from the dashboard or with the Create Chat Room API.	chatRoom	Chat Room Created
chatroom_updated	An existing chat room's settings are saved, either from the dashboard or with the Update Chat Room API.	chatRoom	Chat Room Updated
chatroom_deleted	A chat room is deleted, either from the dashboard or with the Delete Chat Room API.	chatRoom	none — see below

chatroom_updated fires on every save of the room's settings, including saves that change nothing. The data.chatRoom object is the room after the update; the previous values are not included, so if you need to know what changed you have to keep your own copy.

Deleting a chat room also deletes its channels. Each one produces its own channel_deleted event first, followed by a single chatroom_deleted for the room.

caution

chatroom_deleted has no switch on the Settings -> Webhooks page, so it cannot be turned on from the dashboard and is off for new accounts. Everything else about the event works. If you need this event, contact support.

Channel lifecycle

Channels are the sub-rooms inside a chat room.

event	Fires when	data contains	Switch
channel_created	A channel is created in a chat room, either from the dashboard or with the Create Channel API.	channel	Channel Created
channel_updated	An existing channel is updated, either from the dashboard or with the Update Channel API.	channel	Channel Updated
channel_deleted	A channel is deleted from the dashboard or with the Delete Channel API, or because the chat room containing it was deleted.	channel	Channel Deleted

caution

The Channel Created switch also controls private_message_initiated. Turning it on subscribes you to both events. See Private messages below.

Membership

event	Fires when	data contains	Switch
user_joined_chatroom	A user joins a chat room.	user	User Joined Chat Room
user_left_chatroom	A user's connection to the chat closes.	user	User Left Chat Room

user_joined_chatroom fires on every join, not only the first one. A user who refreshes the page, reconnects after losing their network, or rejoins later produces another event each time. The room they joined is in data.user.lastChatRoomId, which holds the public roomId.

user_left_chatroom fires when the user's connection closes, which includes closing the tab, navigating away and losing the network — it is not a deliberate "leave" action by the user. Its user object is a reduced one and it carries no room identifier, so it cannot tell you which room the user was in. See Payloads for the fields it does carry.

info

There is a Channel Joined switch on the settings page, but no event is ever sent for it. Turning it on has no effect. See Known limitations.

Chat room messages

These events cover messages posted in the main chat room, not in a channel.

event	Fires when	data contains	Switch
new_chatroom_message	A message is posted in a chat room by a participant, or with the Send Chat Room Message API.	chatMessage	New Chat Room Message
chatroom_message_deleted	A moderator deletes a message from the chat room or from Dashboard -> Moderation, or a message is deleted with the Delete Message API.	chatMessage	Chat Room Message Deleted
chatroom_message_approved	A moderator approves a held message in a pre-moderated chat room, from the chat room or from Dashboard -> Moderation.	chatMessage	Chat Room Message Approved
chatroom_message_like_toggle	A participant adds or removes a reaction on a chat room message.	likeAction	Chat Room Message Reaction

chatroom_message_like_toggle covers both directions. data.likeAction.action is "liked" when the reaction was added and "unliked" when it was removed.

In a pre-moderated chat room, a held message produces new_chatroom_message when it is posted (with disapproved set to true) and chatroom_message_approved when a moderator releases it.

info

Deleting all messages in a room, whether from the dashboard or with the Delete Chat Room Messages API, does not send a chatroom_message_deleted event for each message. See Actions that do not send webhooks.

Channel messages

The channel equivalents of the chat room message events.

event	Fires when	data contains	Switch
new_channel_message	A message is posted in a channel, or with the Send Channel Message API.	channelMessage	New Channel Message
channel_message_deleted	A moderator deletes a channel message from the chat room, or a message is deleted with the Delete Channel Message API.	channelMessage	Channel Message Deleted
channel_message_approved	A moderator approves a held channel message in a pre-moderated chat room.	channelMessage	Channel Message Approved
channel_message_like_toggle	A participant adds or removes a reaction on a channel message.	likeAction	Channel Message Reaction

caution

Deleting or approving a channel message from the Dashboard -> Moderation page does not send a webhook. Only the in-room moderator actions and the REST API do. The chat room equivalents (chatroom_message_deleted and chatroom_message_approved) do fire from that page.

A channelMessage identifies its channel with data.channelMessage.channel and does not include the chat room. If you need the room, keep a channel-to-room map from the channel_created events or the List Channels API.

Private messages

These are the one-to-one conversations between two users inside a chat room.

event	Fires when	data contains	Switch
private_message_initiated	A user opens a one-to-one conversation with another user.	member_one, member_two, chatRoom	Channel Created — see the warning
new_private_message	A user sends a message in a one-to-one conversation.	privateMessage	New Private Message

caution

private_message_initiated is controlled by the Channel Created switch, not by its own. It is delivered whenever Channel Created is on, and the Private Message Initiated switch has no effect.

In practice this means:

• Turning on Private Message Initiated does nothing.
• Turning on Channel Created subscribes you to channel_created and private_message_initiated. If you only want channel events, filter on the event string in your handler and ignore private_message_initiated — and be aware that you are receiving the identities of both participants of every private conversation that is opened in your rooms.

Treat Channel Created as the switch for both events, and filter on the event string in your handler.

private_message_initiated fires every time a conversation is opened, not only the first time two users talk. Reopening an existing conversation sends the event again. member_one is the user who opened it and member_two is the other participant.

new_private_message carries the message text, the sender's id in data.privateMessage.user and both participants, but no message id and no timestamp. Compare user against member_one._id and member_two._id to tell who sent it.

caution

Private conversations are private between two users. Both of these events deliver their content and participants to your endpoint. Make sure that is what you want before switching them on, and that your endpoint handles the data accordingly.