> ## Documentation Index
> Fetch the complete documentation index at: https://docs.animam.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Listen to widget events

The widget emits JavaScript events that you can listen to for integration with your application.

## Available events

| Event                       | Description             | Payload              |
| --------------------------- | ----------------------- | -------------------- |
| `animam:ready`              | Widget loaded and ready | `{}`                 |
| `animam:open`               | Widget opened           | `{}`                 |
| `animam:close`              | Widget closed           | `{}`                 |
| `animam:message`            | Message sent/received   | `{ role, content }`  |
| `animam:conversation:start` | New conversation        | `{ conversationId }` |
| `animam:error`              | Error occurred          | `{ error }`          |

## Usage

```javascript theme={null}
// Widget ready
window.addEventListener('animam:ready', () => {
  console.log('Animam widget loaded')
})

// Widget opened
window.addEventListener('animam:open', () => {
  // e.g., track analytics
  gtag('event', 'chat_opened')
})

// Widget closed
window.addEventListener('animam:close', () => {
  gtag('event', 'chat_closed')
})

// New message
window.addEventListener('animam:message', (event) => {
  const { role, content } = event.detail
  console.log(`${role}: ${content}`)

  // role = 'user' or 'assistant'
})

// New conversation
window.addEventListener('animam:conversation:start', (event) => {
  const { conversationId } = event.detail
  console.log('Conversation:', conversationId)
})
```

## Use cases

### Analytics

```javascript theme={null}
window.addEventListener('animam:open', () => {
  // Google Analytics
  gtag('event', 'chat_widget_opened', {
    page: window.location.pathname
  })
})

window.addEventListener('animam:message', (e) => {
  if (e.detail.role === 'user') {
    gtag('event', 'chat_message_sent')
  }
})
```

### CRM Integration

```javascript theme={null}
window.addEventListener('animam:conversation:start', async (e) => {
  // Send to your CRM
  await fetch('/api/crm/chat-started', {
    method: 'POST',
    body: JSON.stringify({
      conversationId: e.detail.conversationId,
      page: window.location.href,
      timestamp: new Date().toISOString()
    })
  })
})
```

### Notifications

```javascript theme={null}
window.addEventListener('animam:message', (e) => {
  if (e.detail.role === 'assistant') {
    // Desktop notification if widget is closed
    if (Notification.permission === 'granted') {
      new Notification('New Animam message', {
        body: e.detail.content.substring(0, 100)
      })
    }
  }
})
```

## JavaScript API

In addition to events, the widget exposes an API:

```javascript theme={null}
// Check if ready
if (window.Animam) {
  window.Animam.open()
}

// Available methods
window.Animam.open()           // Open
window.Animam.close()          // Close
window.Animam.toggle()         // Toggle
window.Animam.sendMessage(msg) // Send a message
window.Animam.setSegment(seg)  // Change segment
window.Animam.destroy()        // Remove the widget
```