feat(widget): propagate client-side events through dispatched events

[simong]

This allows end-users to dispatch events to the widget which are then propagated to the back-end for handling.

The following standard events are supported:

• contextual updates
• user activity
• user message

See https://elevenlabs.io/docs/agents-platform/customization/events/client-to-server-events

To prevent abuse, this is explicitly opt-in. The allow-events attribute needs to have a true value before the event listeners are bound.

This follows the same pattern as the :expanded event:

packages/packages/convai-widget-core/src/widget/Wrapper.tsx

Lines 81 to 106 in 4dac770

	useSignalEffect(() => {
	const handleExpandEvent = ((event: CustomEvent) => {
	if (!event.detail || event.detail._convaiEventHandled) {
	return;
	}
	event.detail._convaiEventHandled = true;
	if (event.detail.action === "expand") {
	expanded.value = true;
	} else if (event.detail.action === "collapse") {
	expanded.value = false;
	} else if (event.detail.action === "toggle") {
	expanded.value = !expanded.value;
	}
	}) as EventListener;
	const host = shadowHost.value;
	// Listen for custom events on the document
	document.addEventListener("elevenlabs-agent:expand", handleExpandEvent);
	host?.addEventListener("elevenlabs-agent:expand", handleExpandEvent);
	return () => {
	document.removeEventListener("elevenlabs-agent:expand", handleExpandEvent);
	host?.removeEventListener("elevenlabs-agent:expand", handleExpandEvent);
	};
	});

[simong]

@kalvin807 @kraenhansen @PaulAsjes : I would love your feedback on this. We're building an integration which combines both MCP on the backend and some client-side logic to "nudge" the model on certain interactions. Having the ability to push client-side information to the LLM through the widget would be really helpful for us.

[kalvin807]

@simong This is an awesome feature addition 🔥 thanks for the contribution.

I’m considering making the three events individually configurable, which may require additional backend work to support opting out of client-side events (since attribute-based gating is easy to bypass). Would you mind if our team takes this over for now and follows up with you later?

[kamilk-11]

Not sure if we want to duplicate the pattern from elevenlabs-agent:expand tbh

The reason it attaches a handler to both the document and the widget, and marks it via _convaiEventHandled, is because whoever implemented it initially listened for the event only on the document. Users then started complaining that this breaks when there are multiple widgets on the page. So I added a proper listener on the shadow host, but kept the document listeners and used a custom _convaiEventHandled instead of stopPropagation() for backwards compatibility

Here, since we are starting clean, I'd suggest we only listen on the host

Missed the previous comment

[simong]

Thank you both. No objections on my end on letting you move this forward. We'd happily beta test the feature if you need any volunteers :)