> ## Documentation Index
> Fetch the complete documentation index at: https://audio-app-kit-docs.upgrade-api.int.bragi-dev.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

All events are being dispatched from Audio App Kit to the window object. In order to listen for events, an event listener needs to be created.

Each event is of type `CustomEvent` and it contains the payload within `event.detail` property.

## Importing Events

<CodeGroup>
  ```typescript Typescript
  import { AudioAppKitEvents } from '@bragiai/audio-app-kit';
  // Usage: AudioAppKitEvents.agent.ON_MESSAGE;
  ```

  ```javascript Javascript
  const { AudioAppKit } from '@bragiai/audio-app-kit';
  // Usage: AudioAppKit.events.agent.ON_MESSAGE;
  ```
</CodeGroup>

## List of Events

### Agent State Update

Listen for events when the agent state updates:

<CodeGroup>
  ```typescript Typescript
  window.addEventListener(AudioAppKitEvents.agent.ON_STATE_UPDATE, ((event: CustomEvent) => {
    // Handle event
  }) as EventListener);
  ```

  ```javascript Javascript
  window.addEventListener(AudioAppKit.events.agent.ON_STATE_UPDATE, event => {
    // Handle event
  });
  ```

  ```javascript Payload Example
  {
    "state": 1 // agentNotify.StatePayload_State.INITIAL
  }
  ```
</CodeGroup>

### Mute State Update

Listen for events when the mute state updates:

<CodeGroup>
  ```typescript Typescript
  window.addEventListener(AudioAppKitEvents.agent.ON_MUTE_STATE_UPDATE, ((event: CustomEvent) => {
    // Handle event
  }) as EventListener);
  ```

  ```javascript Javascript
  window.addEventListener(AudioAppKit.events.agent.ON_MUTE_STATE_UPDATE, event => {
    // Handle event
  });
  ```

  ```javascript Payload Example
  {
    "state": 0 // agentShared.StatePayload_State.OFF
  }
  ```
</CodeGroup>

### Chat Message Received

Listen for events when a chat message is received:

<CodeGroup>
  ```typescript Typescript
  window.addEventListener(AudioAppKitEvents.agent.ON_MESSAGE, ((event: CustomEvent) => {
    // Handle event
  }) as EventListener);
  ```

  ```javascript Javascript
  window.addEventListener(AudioAppKit.events.agent.ON_MESSAGE, event => {
    // Handle event
  });
  ```

  ```javascript Payload Example
  {
    "text": "What is superconductivity?",
    "uuid": "43fed0f0-4e6c-496e-8d2e-3b0c633dab0c",
    "createdAt": "2025-04-14T12:51:37.747Z",
    "sender": 1 // agentNotify.ChatMessagePayload_MessageSender.USER
  }
  ```
</CodeGroup>

### Chat History Received

Listen for events when a chat history is received:

<CodeGroup>
  ```typescript Typescript
  window.addEventListener(AudioAppKitEvents.agent.ON_CHAT_HISTORY_UPDATE, ((event: CustomEvent) => {
    // Handle event
  }) as EventListener);
  ```

  ```javascript Javascript
  window.addEventListener(AudioAppKit.events.agent.ON_CHAT_HISTORY_UPDATE, event => {
    // Handle event
  });
  ```

  ```javascript Payload Example
  {
    "messages": [
      {
        "text": "What is superconductivity?",
        "uuid": "43fed0f0-4e6c-496e-8d2e-3b0c633dab0c",
        "createdAt": "2025-04-14T12:51:37.747Z",
        "sender": 1 // agentNotify.ChatMessagePayload_MessageSender.USER
      },
      // ...
    ]
  }
  ```
</CodeGroup>

### Language Updated

Listen for events when the chat language is updated:

<CodeGroup>
  ```typescript Typescript
  window.addEventListener(AudioAppKitEvents.agent.ON_LANGUAGE_UPDATE, ((event: CustomEvent) => {
    // Handle event
  }) as EventListener);
  ```

  ```javascript Javascript
  window.addEventListener(AudioAppKit.events.agent.ON_LANGUAGE_UPDATE, event => {
    // Handle event
  });
  ```

  ```javascript Payload Example
  {
    "language": "en"
  }
  ```
</CodeGroup>

### Available Languages Received

Listen for events when a list of available chat languages is received:

<CodeGroup>
  ```typescript Typescript
  window.addEventListener(AudioAppKitEvents.agent.ON_AVAILABLE_LANGUAGES, ((event: CustomEvent) => {
    // Handle event
  }) as EventListener);
  ```

  ```javascript Javascript
  window.addEventListener(AudioAppKit.events.agent.ON_AVAILABLE_LANGUAGES, event => {
    // Handle event
  });
  ```

  ```javascript Payload Example
  [
    {
      "label": "English",
      "code": "en"
    },
    {
      "label": "Spanish",
      "code": "es"
    },
    // ...
  ]
  ```
</CodeGroup>

### Pad Volume Update

Listen for events when the pad volume is updated:

<CodeGroup>
  ```typescript Typescript
  window.addEventListener(AudioAppKitEvents.agent.ON_PAD_VOLUME_UPDATE, ((event: CustomEvent) => {
    // Handle event
  }) as EventListener);
  ```

  ```javascript Javascript
  window.addEventListener(AudioAppKit.events.agent.ON_PAD_VOLUME_UPDATE, event => {
    // Handle event
  });
  ```

  ```javascript Payload Example
  {
    "value": 50
  }
  ```
</CodeGroup>

### Voice Control Update

Listen for events when the voice control is updated:

<CodeGroup>
  ```typescript Typescript
  window.addEventListener(AudioAppKitEvents.agent.ON_VOICE_CONTROL_UPDATE, ((event: CustomEvent) => {
    // Handle event
  }) as EventListener);
  ```

  ```javascript Javascript
  window.addEventListener(AudioAppKit.events.agent.ON_VOICE_CONTROL_UPDATE, event => {
    // Handle event
  });
  ```

  ```javascript Payload Example
  {
    "state": 1 // agentShared.StatePayload.ON
  }
  ```
</CodeGroup>

### Wake Word Update

Listen for events when the wake word is updated:

<CodeGroup>
  ```typescript Typescript
  window.addEventListener(AudioAppKitEvents.agent.ON_WAKE_WORD_UPDATE, ((event: CustomEvent) => {
    // Handle event
  }) as EventListener);
  ```

  ```javascript Javascript
  window.addEventListener(AudioAppKit.events.agent.ON_WAKE_WORD_UPDATE, event => {
    // Handle event
  });
  ```

  ```javascript Payload Example
  {
    "isAvailable": true,
    "title": "Hey, Chat AI"
  }
  ```
</CodeGroup>

### Notification Badge State Updated

Listen for events when a notification badge state updates:

<CodeGroup>
  ```typescript Typescript
  window.addEventListener(AudioAppKitEvents.agent.ON_NOTIFICATION_BADGE_STATE_UPDATE, ((event: CustomEvent) => {
    // Handle event
  }) as EventListener);
  ```

  ```javascript Javascript
  window.addEventListener(AudioAppKit.events.agent.ON_NOTIFICATION_BADGE_STATE_UPDATE, event => {
    // Handle event
  });
  ```

  ```javascript Payload Example
  {
    isActive: true, // Boolean - whether the notification badge is active
    type: 0 // agentShared.NotificationBadgePayload_Type.SETTINGS_BUTTON
  }
  ```
</CodeGroup>

### Banner State Updated

Listen for events when a banner state updates:

<CodeGroup>
  ```typescript Typescript
  window.addEventListener(AudioAppKitEvents.agent.ON_BANNER_UPDATE, ((event: CustomEvent) => {
    // Handle event
  }) as EventListener);
  ```

  ```javascript Javascript
  window.addEventListener(AudioAppKit.events.agent.ON_BANNER_UPDATE, event => {
    // Handle event
  });
  ```

  ```javascript Payload Example
  {
    isAvailable: true, // Boolean - whether the banner is available
    title: "✨ Bonus: for a limited time try our UHD AI models"
  }
  ```
</CodeGroup>

### Debug Data

<CodeGroup>
  ```typescript Typescript
  window.addEventListener(AudioAppKitEvents.agent.ON_DEBUG_DATA, ((event: CustomEvent) => {
    // Handle event
  }) as EventListener);
  ```

  ```javascript Javascript
  window.addEventListener(AudioAppKit.events.agent.ON_DEBUG_DATA, event => {
    // Handle event
  });
  ```

  ```javascript Payload Example
  {
    lastSessionId: "123123";
    cloudVersion: "1.0.0";
    serviceId: "chatai";
  }
  ```
</CodeGroup>

### Available Language models

<CodeGroup>
  ```typescript Typescript
  window.addEventListener(AudioAppKitEvents.agent.ON_AVAILABLE_LANGUAGE_MODELS, ((event: CustomEvent) => {
    // Handle event
  }) as EventListener);
  ```

  ```javascript Javascript
  window.addEventListener(AudioAppKit.events.agent.ON_AVAILABLE_LANGUAGE_MODELS, event => {
    // Handle event
  });
  ```

  ```javascript Payload Example
  {
    models: [
      {
        label: "English", // The language label of the model
        code: "en", // The language code of the model
        downloaded: true, // Whether the model is downloaded
        fileSize: 83886080, // File size in bytes
        estimatedDownloadTime: 120, // Estimated download time in seconds
        newVersionAvailable: false, // Whether a new version of the model is available
        newVersionBannerContent: '✨ New English AI voice is out', // The banner content for the new version of the model
      },
      // ...
    ],
  }
  ```
</CodeGroup>

### Download Language Model Progress

<CodeGroup>
  ```typescript Typescript
  window.addEventListener(AudioAppKitEvents.agent.ON_LANGUAGE_MODEL_DOWNLOAD_PROGRESS, ((event: CustomEvent) => {
    // Handle event
  }) as EventListener);
  ```

  ```javascript Javascript
  window.addEventListener(AudioAppKit.events.agent.ON_LANGUAGE_MODEL_DOWNLOAD_PROGRESS, event => {
    // Handle event
  });
  ```

  ```javascript Payload Example
  {
    languageCode: 'en', // The language code of the model
    progress: 42, // Progress in percent
  }
  ```
</CodeGroup>

### Download Language Model Error

<CodeGroup>
  ```typescript Typescript
  window.addEventListener(AudioAppKitEvents.agent.ON_LANGUAGE_MODEL_DOWNLOAD_ERROR, ((event: CustomEvent) => {
    // Handle event
  }) as EventListener);
  ```

  ```javascript Javascript
  window.addEventListener(AudioAppKit.events.agent.ON_LANGUAGE_MODEL_DOWNLOAD_ERROR, event => {
    // Handle event
  });
  ```

  ```javascript Payload Example
  {
    languageCode: 'en', // The language code of the model
    errorType: agentNotify.LanguageModelDownloadErrorPayload_ErrorType.STORAGE_FULL, // Storage full error
  }
  ```
</CodeGroup>

### Placeholder Message Update

<CodeGroup>
  ```typescript Typescript
  window.addEventListener(AudioAppKitEvents.agent.ON_PLACEHOLDER_MESSAGE_UPDATE, ((event: CustomEvent) => {
    // Handle event
  }) as EventListener);
  ```

  ```javascript Javascript
  window.addEventListener(AudioAppKit.events.agent.ON_PLACEHOLDER_MESSAGE_UPDATE, event => {
    // Handle event
  });
  ```

  ```javascript Payload Example
  {
    message: '🎉 Download abgeschlossen – Sie können jetzt mit ChatAI sprechen und ChatAI wird auf Deutsch antworten.',
  }
  ```
</CodeGroup>