# Events

The Dixa Messenger emits events that you can listen to in order to react to what is happening within the messenger. For example if you want to know when a the widget is opened by the user, or when a conversation is started, you can use the API below to do so.

## API

To listen to an event you should use the `_dixa_.addListener()` API, which receives two arguments, first is the event name and the second is the callback that will be called once the event has happened. In order to remove an event listener you can use the `_dixa_.removeListener()` API. The signature is exactly the same.

Here's a list of available events:

| Event | Description | payload |
|  --- | --- | --- |
| on-api-ready | called when the Dixa Messenger API is fully initialized and ready to receive commands | `void` [info](/docs/dixamessenger/web/interfaces/hostnotificationevents#on-api-ready) |
| on-widget-open-changed | called when widget is either opened or closed by the user or programmatically | `boolean` [info](/docs/dixamessenger/web/interfaces/hostnotificationevents#on-widget-open-changed) |
| on-conversation-started | called when a conversation is started | `object` [info](/docs/dixamessenger/web/interfaces/hostnotificationevents#on-conversation-started) |
| on-conversation-ended | called when a conversation is ends | `object` [info](/docs/dixamessenger/web/interfaces/hostnotificationevents#on-conversation-ended) |
| on-message-added | called when a new message is added to the conversation, by the user, agent or bots | `ReceivableMessages` [info](/docs/dixamessenger/web/interfaces/receivedtextmessage) |
| on-view-changed | called when user navigates to different viewing the messenger | `string` [info](/docs/dixamessenger/web/interfaces/hostnotificationevents#on-view-changed) |
| on-user-identity-changed | called when users identify themselves | `Identify` [info](/docs/dixamessenger/web/types#identify-actors) |
| on-agent-assigned | called when an agent joins the conversation | `Agent` [info](/docs/dixamessenger/web/interfaces/agent) |
| on-agent-unassigned | called when an agent leaves the conversation | `Agent` [info](/docs/dixamessenger/web/interfaces/agent) |
| on-user-purged | called when the user identity is removed programmatically | `void` |
| on-widget-focus-changed | called when the widget is focused or loses focus | `string` [info](/docs/dixamessenger/web/interfaces/hostnotificationevents#on-widget-open-changed) |
| on-shutdown-completed | called when the widget has finished the shutdown process | `void` [info](/docs/dixamessenger/web/interfaces/hostnotificationevents#on-widget-open-changed) |
| on-backend-error | called when the backend has returned an error in response to an action | `BackendError` [info](/docs/dixamessenger/web/interfaces/hostnotificationevents#on-widget-open-changed) |
| user-banned | called when user is banned via agent interface | `void` |
| user-unbanned | called when user is unbanned via agent interface | `void` |


Example:


```ts
function handleConversationStarted(data) {
  console.log(data.conversationId);
}

// Listen for when the API is ready
_dixa_.addListener('on-api-ready', function () {
  console.log('Dixa Messenger API is ready!');
  // You can now use the promise-based API
  _dixa_.api.init({ messengerToken: 'your-token' });
});

// start listening to the events
_dixa_.addListener('on-conversation-started', onConversationStarted);

// stop listening to the events:
_dixa_.removeListener('on-conversation-started', onConversationStarted);
```

# Interface: HostNotificationEvents

Events that a host website can listen to.
This is kept separate from WidgetEvents definitions
in order to avoid any coupling of internal types to
what we expose to the host.

To see a complete list of all available events and their corresponding payloads you can see the [HostNotificationEvents interface.](/docs/dixamessenger/web/interfaces/hostnotificationevents)