NeevAI
PlaygroundBook an Intro Call

Seeded questions and the host-page API

Start a conversation from your own page: a search box, a pricing calculator, a button. What the host page can send and what it hears back.

A host page can hand the agent a question, open the panel, and follow the visitor's theme choice. This is how the NeevAI landing pages send their prompt chips into the full-page chat, and how the ROI calculator sends an estimate into the corner widget.

Seeding a question by URL

Two URL parameters on any embed:

  • q=<text>, up to 200 characters, prefills the composer and focuses it.
  • q=<text>&autosend=1 sends it as soon as the chat is ready.

The send is skipped when the session's last visitor message is identical, so reloads never double-send.

The host-page API

Pages using the launcher snippet get window.NeevaiChat:

NeevaiChat.ask('What does a booking agent cost?', {
  autosend: true, // default false prefills the composer
  state: 'expanded' // optional: widget | expanded | fullscreen
})

NeevaiChat.submit('How do I connect HubSpot?') // ask() with autosend
NeevaiChat.open()
NeevaiChat.close()
NeevaiChat.toggle()
NeevaiChat.setTheme('dark') // 'light' | 'dark' | 'system'

Calls made before the chat is ready are queued and delivered once it is. Messages over two thousand characters are dropped silently.

Talking to an iframe directly

A page that embeds the assistant in its own iframe posts messages instead. After the chat announces it is ready, the host can send:

iframe.contentWindow.postMessage(
  { type: 'neevai:ask', question: 'Which calendars does it book into?', autosend: true },
  'https://CHAT_HOST'
)

The chat accepts these only from trusted origins: the origins configured for the deployment, or the actual embedding page when none are configured. Unrecognised origins are ignored.

What the chat sends back

The chat posts these messages to the host, pinned to the trusted origin and never to a wildcard:

| Message | Meaning | |---|---| | NEEVAI_READY | The chat has loaded and will accept questions. | | NEEVAI_CLOSE | The visitor closed the chat. | | NEEVAI_EXPAND, NEEVAI_FULLSCREEN, NEEVAI_MINIMIZE | The visitor changed the panel size. |

The launcher snippet handles all of these for you. A custom iframe host listens for them itself.

A worked example

The NeevAI ROI calculator builds a plain-text estimate from the visitor's inputs and calls:

NeevaiChat.ask('ROI calculator estimate from neevai.io/roi: ...', { autosend: true, state: 'expanded' })

The agent reads the estimate, treats every number as the visitor's own assumption, and moves the conversation towards a booked call. Any structured payload from a host page works the same way: put it in the message, and give the agent knowledge about the format.