# Events

WebChat emits a number of events that you can listen to within your own application.

## Adding an event listener

To add an event listener, use:

```typescript
webchat.on('event_name':string, callback: Function)
```

Each listener will return a `CustomEvent` object with specific data nested in the `event.detail` object:

```typescript
/**
* Add an event listener to the chat widget
* @function on
* @param {string} eventName - the event to listen for
* @param {Function} callback - the function to call when the event is triggered
* @returns {CustomEvent} - the event object with specific data in the event.detail object
*/

.on('loaded', (e: CustomEvent) => {
    console.log(e.detail) // the event data specific to WebChat
})
```

For convenience, all events return the element upon which the event was fired within the `detail` object. For additional return values, see the descriptions below.

### Supported events

`'loaded'` - fired when the WebChat widget has initialised.

Returns a 'loaded' property with a Boolean value:

`loaded: true`

***

`'openStateChanged'` - fired when the WebChat widget is opened or closed.

Returns a String value:

```typescript
enum openState {
  OPEN = 'open',
  CLOSED = 'closed'
}

return openState: openState.OPEN
```

***

`'messageSent'` - fired when the user sends a message.

Returns a message object:

```typescript
export interface IMessagePayload {
  kind?: 'outgoing'
  author: string
  content: IMessageContent
  message_id: string
  notification: string
  user_id: string
  uuid?: string
  mode?: string
  modeInstance?: number
  partOfLastTemplate?: boolean
}

export interface IMessageContent {
  author: string
  callback_id?: string
  id: string
  mode?: string
  modeInstance?: number
  type: string
  user: Object
  data: {
    text: string
    date: string
    time: string
    value?: string
    [key: string]: any
  }
  escalating?: boolean
}

return message: IMessagePayload
```

***

`'messageReceived'` - fired when WebChat receives a message from the server.

Returns a message object:

```typescript
export interface IMessage {
  kind?: 'incoming'
  first?: boolean
  last?: boolean
  author: string
  intent?: string
  type: string
  data: IMessageData
  uuid?: string
  authorAvatar?: string
  authorName?: string
  partOfLastTemplate?: boolean
}

export interface IMessageData {
  text: string | null
  meta?: {
    author?: {
      name?: string
      avatar?: string
      [key: string]: any
    }
    [key: string]: any
  }
  attribute_name: string | null
  date: string | null
  disable_text?: boolean
  hideavatar?: boolean
  hidetime?: boolean
  internal?: boolean
  time: string | null
  elements?: IElement[] | IElementsObject
  submit_text?: string
  [key: string]: any
}

return message: IMessage
```

***

`'chatEnded'` - fired when the user selects 'end chat' from the menu in the WebChat application


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.opendialog.ai/developing-with-opendialog/webchat/sdk/events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.