Essentials

Event Listeners

Subscribe to any Tawk.to event in Nuxt using useTawk(). Every listener returns a cleanup function to avoid memory leaks.

All Tawk.to event listeners are available via useTawk(). Every listener returns a cleanup function — call it in onUnmounted to remove the listener and avoid memory leaks.

Basic Pattern

composables/useChatEvents.ts

import { onMounted, onUnmounted } from 'vue'

const { onLoad, onStatusChange, onChatStarted } = useTawk()

onMounted(() => {
  const cleanupLoad = onLoad(() => {
    console.log('Tawk.to widget loaded')
  })

  const cleanupStatus = onStatusChange((status) => {
    console.log('Agent status:', status) // 'online' | 'away' | 'offline'
  })

  const cleanupStarted = onChatStarted(() => {
    console.log('Chat session started')
  })

  onUnmounted(() => {
    cleanupLoad()
    cleanupStatus()
    cleanupStarted()
  })
})

Available Listeners

Listener	Callback Signature	Description
`onLoad`	`() => void`	Fires when the widget has fully loaded.
`onBeforeLoad`	`() => void`	Fires just before the widget loads.
`onStatusChange`	`(status: TawkStatus) => void`	Fires when agent availability changes.
`onChatMaximized`	`() => void`	Fires when the chat window is opened.
`onChatMinimized`	`() => void`	Fires when the chat window is minimized.
`onChatHidden`	`() => void`	Fires when the widget bubble is hidden.
`onChatStarted`	`() => void`	Fires when a chat session starts.
`onChatEnded`	`() => void`	Fires when a chat session ends.
`onPrechatSubmit`	`(data: Record<string, unknown>) => void`	Fires when the pre-chat form is submitted.
`onOfflineSubmit`	`(data: Record<string, unknown>) => void`	Fires when the offline form is submitted.
`onChatMessageVisitor`	`(message: string) => void`	Fires when the visitor sends a message.
`onChatMessageAgent`	`(message: string) => void`	Fires when an agent sends a message.
`onChatMessageSystem`	`(message: string) => void`	Fires on system messages.
`onAgentJoinChat`	`(data: Record<string, unknown>) => void`	Fires when an agent joins the chat.
`onAgentLeaveChat`	`(data: Record<string, unknown>) => void`	Fires when an agent leaves the chat.
`onChatSatisfaction`	`(satisfaction: number) => void`	Fires when the visitor submits a rating.
`onVisitorNameChanged`	`(visitorName: string) => void`	Fires when the visitor's name changes.
`onFileUpload`	`(link: string) => void`	Fires when a file is uploaded in chat.
`onTagsUpdated`	`(data: Record<string, unknown>) => void`	Fires when conversation tags change.
`onUnreadCountChanged`	`(count: number) => void`	Fires when the unread message count changes.

Real-World Example

Show a notification badge and track chat engagement:

components/ChatWidget.vue

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue'

const {
  isHidden,
  unreadCount,
  status,
  showWidget,
  onLoad,
  onUnreadCountChanged,
  onChatStarted
} = useTawk()

const cleanupFns: Array<() => void> = []

onMounted(() => {
  cleanupFns.push(
    onLoad(() => {
      console.log('Widget ready, agent is:', status.value)
    }),
    onUnreadCountChanged((count) => {
      console.log('New unread messages:', count)
    }),
    onChatStarted(() => {
      console.log('Chat started — tracking engagement')
    })
  )
})

onUnmounted(() => {
  cleanupFns.forEach(fn => fn())
})
</script>

<template>
  <button
    v-if="isHidden"
    class="fixed bottom-4 right-4 rounded-full"
    @click="showWidget()"
  >
    💬
    <span v-if="unreadCount > 0" class="badge">{{ unreadCount }}</span>
  </button>
</template>

Migration Guide

Upgrade from nuxt-tawk-to v1 to v2. The inject/provide API is gone — use the new useTawk() composable instead.

Setters

Identify visitors, set custom attributes, track events, manage tags, and switch widgets using useTawk() setters.