Open the assistant from your own page

The launcher is one way in. Your own page can be another: a button on a job card, a link in your FAQ, the search box you already have. Mark the element up and the embed takes it over — no callbacks to wire, and nothing to initialise.

Any element can be a trigger

Put data-voyse-open on it:

<button type="button" data-voyse-open>Ask about this role</button>

Clicking it opens the assistant exactly as the launcher would. The handler is delegated from document, so markup rendered later — an SPA route change, infinite scroll, a modal — works with no rewiring. The click is also prevented from doing anything else, so an <a href> can be a trigger without navigating.

To send a question at the same time, add data-voyse-ask-text:

<button
  type="button"
  data-voyse-open
  data-voyse-ask-text="What does the interview process look like?"
>
  How does hiring work here?
</button>

The assistant opens with that question already asked. The visible label and the question are separate on purpose: the label can be short and the question can be the fuller thing you actually want answered.

The attribute's own value can name a role, and any trigger can inherit one from its surroundings — that is Tell the assistant which role a page is about.

A form marked data-voyse-ask is taken over on submit: the embed cancels the submission, opens the assistant, and forwards whatever the visitor typed.

<form data-voyse-ask>
  <input type="search" name="q" placeholder="Ask about working here…" />
  <button type="submit">Ask</button>
</form>

You do not need an action or a handler, and the form never posts. What the embed does with it:

The question comes from the form's first text input or textarea.
The field is cleared afterwards, so the same form can ask again.
An empty submit is still treated as intent to talk. The placeholder is used as the implied question — hosts usually phrase it as one — and if there is no placeholder either, the assistant opens and the field takes focus. A dead "Ask" button is worse than an open panel.
Forms added to the page later are picked up by a mutation observer, so a form that arrives with a rendered fragment works too.

Once wired, a form carries data-voyse-ask-wired="1". That is the embed's own bookkeeping, not something to set yourself, but it is a quick way to confirm in devtools that a form was found.

Setting the placeholder from the form

data-voyse-placeholder on the form is applied to that first input on load:

<form data-voyse-ask data-voyse-placeholder="Ask about this role…">
  <input type="search" name="q" />
  <button type="submit">Ask</button>
</form>

This exists for template systems where the wrapper is editable and the input is not. If you can set the placeholder on the input directly, do that instead — it is one fewer thing to keep in step, and the two do the same job.

Which one to reach for

You have	Use
A button, link or card	`data-voyse-open`
A button that should ask something specific	`data-voyse-open` with `data-voyse-ask-text`
An existing search or question field	`form data-voyse-ask`
A trigger built by your own JavaScript	The voyse object

Check it worked

Click the trigger. The assistant should open, and where you set data-voyse-ask-text the question should already be in the transcript. If nothing happens, the element is not inside the document the delegated listener is attached to — the usual cause is a trigger rendered inside an iframe of your own, which the embed cannot see.

Any element can be a trigger

Your search box, as the way in

Setting the placeholder from the form

Which one to reach for

Check it worked