Listeners and events

Event listeners let your app react to Messenger activity in real time.

What it is

The SDK exposes event APIs:

• on(eventKey, handler)
• off(eventKey, handler)
• once(eventKey, handler)

You can subscribe through framework SDK APIs or direct window events.

Where to find it in OXVO

• Runtime behavior appears in Inbox activity and conversation updates.
• Event subscriptions are implemented in your frontend codebase.

When to use it

Use listeners to:

• Track launcher open/close behavior
• React to postback actions
• Attach analytics or backend calls to contact/conversation updates

Supported event keys

SDK key	Window event name	Typical use
ready	oxvo:ready	Messenger initialized and ready
error	oxvo:error	Capture runtime errors
opened	oxvo:opened	Track open behavior
closed	oxvo:closed	Track close behavior
postback	oxvo:postback	Handle postback payloads
onMessage or on-message	oxvo:on-message	New message signal
onStartConversation or on-start-conversation	oxvo:on-start-conversation	New conversation started
onConversation or on-conversation	oxvo:on-conversation	Conversation data updates
onContact or on-contact	oxvo:on-contact	Contact data updates

You can also subscribe directly using full event names (for example oxvo:opened).

React example

import { useEffect } from 'react';
import { useOxvoMessenger } from '@oxvo/messenger';

export function MessengerEventBridge() {
  const messenger = useOxvoMessenger();

  useEffect(() => {
    const onOpened = event => {
      console.log('messenger opened', event?.detail);
    };

    messenger.on('opened', onOpened);
    return () => {
      messenger.off('opened', onOpened);
    };
  }, [messenger]);

  return null;
}

Vue / Nuxt example

import { onMounted, onBeforeUnmount } from 'vue';
import { useOxvoMessenger } from '@oxvo/messenger-vue';

const messenger = useOxvoMessenger();
const onPostback = event => {
  console.log('postback payload', event?.detail);
};

onMounted(() => {
  messenger.on('postback', onPostback);
});

onBeforeUnmount(() => {
  messenger.off('postback', onPostback);
});

Direct window listener example

window.addEventListener('oxvo:closed', event => {
  console.log('closed', event.detail);
});

Automation pattern: event to backend pipeline

1. Listen to postback or on-conversation.
2. Normalize payload in frontend.
3. Send to your backend event endpoint.
4. Trigger your internal automation workflow.

messenger.on('on-conversation', async event => {
  const payload = event?.detail || {};
  await fetch('/internal/messenger-events', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ type: 'conversation_update', payload }),
  });
});

Reliability tips

• Keep listeners in app shell or dedicated integration modules.
• Always unregister listeners on component unmount.
• Guard backend calls with retry and idempotency keys.

Related guides

• Visitor identification and properties
• Methods reference
• SDK recipes

📷 Image (optional): Messenger event flow to analytics and backend
Why: Clarifies how runtime Messenger events can power product analytics and backend automation workflows.
File: docs/images/sdk-event-pipeline.png
AI prompt: "Clean OXVO documentation flowchart showing Messenger SDK events (opened, closed, postback, on-conversation) routed to frontend handlers, analytics sink, and backend automation service; modern SaaS style, neutral palette with primary accent, crisp labels, OXVO branding only, 1600x1000."