SDK installation guide

This page covers the first practical SDK setup for Conversaic publishers. The goal is not a deep API reference. It is the minimum install path needed to get a clearly labeled sponsor card into your conversational product.

What the SDK is for

The Conversaic SDK helps publishers do three things:

send conversation context for sponsor matching
prefetch a placement while the AI answer is still loading
render a sponsored card in a controlled container after the answer appears

The package name is conversaic-sdk-js.

What you need before you start

Before installation, make sure you have:

approved pilot access or a working publisher test environment
your Conversaic publisher app ID
a chat or answer surface where a sponsored card can appear clearly
a DOM container in your UI where the sponsored card should render

Install the package

Install the SDK with npm:

npm install conversaic-sdk-js

Load the browser SDK

Add the script to your page or app shell:

<script src="node_modules/conversaic-sdk-js/conversaic.js"
        data-app-id="conv_your_app_id"
        data-base-url="https://api.conversaic.io">
</script>

Use data-app-id to pass your publisher app ID. Use data-base-url when you want the SDK to call the Conversaic API directly instead of the current page origin.

Basic integration flow

The basic integration sequence is:

The user submits a question.
Your app starts the AI request.
In parallel, call Conversaic.prefetch({ context: question }).
After your AI response renders, call Conversaic.attachCard({ context: question, container }).

<div id="chat-response"></div>
<div id="sponsor-slot"></div>

<script>
  async function onUserMessage(question) {
    Conversaic.prefetch({ context: question });

    const aiResponse = await fetch('/api/chat', {
      method: 'POST',
      body: JSON.stringify({ message: question })
    }).then((response) => response.json());

    document.getElementById('chat-response').innerText = aiResponse.text;

    Conversaic.attachCard({
      context: question,
      container: document.getElementById('sponsor-slot')
    });
  }
</script>

What to prepare in your app

The sponsored container should live in a place that feels native to the answer flow. Do not hide it in a generic ad slot. The early product direction works best when the recommendation appears as an explicit and clearly labeled part of the conversation experience.

In practice, most teams should prepare:

a stable container element for the sponsor card
disclosure language that matches internal product policy
a clear answer-render event or callback where attachCard() can run

What to request from Conversaic

If your team is getting ready to install the SDK, make sure you have:

the correct publisher app ID
the right API base URL for your environment
confirmation about where sponsored placements are allowed in your product

For broader rollout questions, read the publisher integration overview after this page.

SDK installation guide for Conversaic publishers