Events & JS API - Animam Documentation

Once loaded, the widget exposes a global window.AnimamChat object and dispatches a single DOM event, animam:ready, when it is available. Everything else goes through AnimamChat.on().

window.addEventListener('animam:ready', () => {
  // window.AnimamChat is now available
})

animam:ready is the only DOM CustomEvent the widget dispatches. Widget events (below) are not DOM events — subscribe with AnimamChat.on().

Methods

AnimamChat.open()
AnimamChat.close()
AnimamChat.toggle()
AnimamChat.isOpen()                 // boolean
AnimamChat.sendMessage('Hello!')    // send a message programmatically

AnimamChat.on(event, callback)      // subscribe (event names below)
AnimamChat.off(event, callback)     // unsubscribe
AnimamChat.onMessage(cb)            // alias for on('message', cb)
AnimamChat.onOpen(cb)               // alias for on('open', cb)
AnimamChat.onClose(cb)              // alias for on('close', cb)

// WebMCP "site actions" — register a client-side tool the agent can call
AnimamChat.registerTool(tool)
AnimamChat.unregisterTool('tool-name')

There is no destroy() and no setSegment(): the segment is fixed per page via the data-segment attribute (see Segments), and removing the widget means removing the script tag.

Events

Event	Fires when
`ready`	The widget finished initializing
`open`	The chat panel opens
`close`	The chat panel closes
`message`	A message is exchanged in the conversation
`tool_call`	The agent executed a tool (booking, quote, form…)
`escalated`	The conversation was handed over to a human
`human_message`	A human operator replied in the conversation
`status_change`	The conversation status changed

window.addEventListener('animam:ready', () => {
  AnimamChat.on('message', (m) => {
    console.log('message', m)
  })

  AnimamChat.on('tool_call', (t) => {
    // e.g. push to your analytics
  })

  AnimamChat.on('escalated', () => {
    // e.g. notify your team channel
  })
})

Example: open the chat from your own CTA

<script src="https://cdn.animam.ai/widget.js" data-tenant="your-slug" data-pyrotechnics="false"></script>

<button onclick="AnimamChat.open()">Ask a question</button>

Example: track conversations in your analytics

window.addEventListener('animam:ready', () => {
  AnimamChat.on('open', () => window._paq?.push(['trackEvent', 'chat', 'open']))
  AnimamChat.on('tool_call', () => window._paq?.push(['trackEvent', 'chat', 'tool_call']))
})

Every attribute the script tag accepts: Configuration.