Custom CTAs
Render action buttons inside the widget that trigger logic in your app.
Custom CTAs (Call-To-Actions) let you add buttons inside the Village widget that trigger logic in your platform. This allows users to take actions — like saving a contact, opening a modal, or sending a message — directly from within the widget interface.
CTAs are configured via the paths_cta
array passed during widget initialization.
Defining Custom CTAs
Each CTA includes:
label
: The text shown on the buttoncallback
: A function executed when the button is clickedstyle
(optional): Custom styling for the button
The
callback
function is always executed in your application environment, not inside the widget. This gives you full control to run custom logic securely on your side.
CTA Object Format
Advanced Usage (Optional)
If you want to observe CTA clicks across contexts (e.g. in iframes) or for analytics/automation purposes, you can listen to CTA events using the SDK or browser-level messaging.
Option 1: Using Village.on()
Option 2: Listening to PostMessage
Example Payload
This is a sample payload received when a CTA is clicked. All names and URLs are fictional and provided for demonstration purposes only.
This payload provides full context of the clicked path, which you can optionally use for logging, custom tracking, or integrations. This is not required for standard CTA usage.
Events Reference
Event Name | Description | Payload |
---|---|---|
village.widget.ready | Widget is initialized | — |
village.path.cta.clicked | CTA was clicked | { index, cta, context } |
village.paths_cta.updated | CTA list was dynamically updated | PathCTA[] |