# Custom events (/en/realtime-media/whiteboard/build/manage-room-state-and-events/custom-events)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

The Whiteboard SDK provides custom event methods for sending and receiving custom messages in real time in a room. You can use these methods to implement features such as message broadcasting, live chatting, giving likes, and sending gifts.
This feature is for Web only.

This page describes how to send, receive, and stop receiving custom events.

## Understand the tech [#understand-the-tech]

The Whiteboard SDK provides the following custom event methods:

* `dispatchMagixEvent`: Sends a custom event.
* `addMagixEventListener`: Adds a listener for a custom event.
* `removeMagixEventListener`: Removes a listener for a custom event.

To send and receive a custom event, follow these steps:

1. Define the name, payload, and callback function of the event.
2. Call `addMagixEventListener` to listen for the event.
3. Call `dispatchMagixEvent` to send the event. All users in the room listening for the event receive the event notification.
4. Call `removeMagixEventListener` to cancel listening for the event, if you want to stop receiving the event notification.

## Prerequisites [#prerequisites]

To follow the procedure on this page, ensure that you have integrated the Whiteboard SDK into your project and implemented joining a room. For details, see [Join the Whiteboard Room](../set-up-and-build-your-first-app/get-started-uikit/#join-the-whiteboard-room).

## Implementation [#implementation]

The following section extends the [Join the Whiteboard Room](../set-up-and-build-your-first-app/get-started-uikit/#join-the-whiteboard-room) sample code to show the implementation of sending and receiving simple text messages by using the custom event methods.

### Listen for and send a custom event [#listen-for-and-send-a-custom-event]

Add the following lines to the `joinWhiteboard.js` file:

```javascript
var whiteWebSdk = new WhiteWebSdk({
    appIdentifier: "RMxxxAQ",
});

var joinRoomParams = {
    uuid: "a7xxx69",
    roomToken: "NETLESSROOM_YWxxxjk",
};

// Define the name and payload of the event.
var eventObject = {
    event: "Greetings",
    payload: "",
};

// Define the callback function of the event.
function onReceiveGreetings(eventObject) {
    // Output the event payload when receiving the Greetings event.
    console.log(eventObject.payload);
}

whiteWebSdk.joinRoom(joinRoomParams).then(function(room) {

    room.bindHtmlElement(document.getElementById("whiteboard"));

    // Add a listener for the Greetings event.
    room.addMagixEventListener("Greetings", onReceiveGreetings);

    // Send the Greetings event.
    room.dispatchMagixEvent("Greetings", "Hello, how do you do");

}).catch(function(err) {

    console.error(err);
});
```

Save the changes, refresh the `index.html` page, and open the console of your browser. You can see the following information on the console:

```text
Hello, how do you do
```

### Stop listening for a custom event [#stop-listening-for-a-custom-event]

If you want to stop receiving the callback notification of a custom event, call `removeMagixEventListener` to remove the listener for the event.

For example, to stop listening for the `Greetings` event, add the following lines to the `joinWhiteboard.js` file:

```javascript
whiteWebSdk.joinRoom(joinRoomParams).then(function(room) {

    room.bindHtmlElement(document.getElementById("whiteboard"));

    // Remove the listener for the Greetings event.
    room.removeMagixEventListener("Greetings", onReceiveGreetings);

}).catch(function(err) {

    console.error(err);
});
```

## See also [#see-also]

### Considerations [#considerations]

Note the following when implementing custom events:

* To ensure the stability of the `dispatchMagixEvent` method, Agora recommends that the payload of a custom event should not exceed 1 KB; otherwise, delay or freezes may occur in the whiteboard room.
* You cannot receive the notification of an event that is sent before you call `addMagixEventListener`.

### API reference [#api-reference]

* [`dispatchMagixEvent`](/en/api-reference/whiteboard/web)
* [`addMagixEventListener`](/en/api-reference/whiteboard/web)
* [`removeMagixEventListener`](/en/api-reference/whiteboard/web)