Ask Module Quick Start

Overview

The Ask module allows your users to ask questions in natural language and receive AI-generated answers based on your content. This guide walks you through the four steps to get it running.

Obtain Your API Key

Log in to the Miso Dashboard, select your target environment (e.g., Production), and navigate to the Overview section to copy your Publishable API Key.

Miso Dashboard — select your environment and copy your API keys

There is one publishable key and one secret key per environment. The publishable key is used in client-side code; the secret key is used for server-side API calls.

Upload Your Corpus via API

Before the Ask module can answer questions, you need to upload your content to Miso using the Product / Content Upload API. You can do this with any HTTP client — the steps below use Postman.Endpoint — View full API reference

POST https://api.askmiso.com/v1/products

Step 1 — Set your request headersIn Postman, go to the Headers tab and add your Secret API Key:

Header	Value
`X-API-KEY`	Your Secret API Key
`Content-Type`	`application/json`

Postman — set the X-API-KEY header with your Secret API Key

Step 2 — Add your request bodySwitch to the Body tab, select raw → JSON, and paste your corpus data:

{
  "data": [
    {
      "product_id": "art_001",
      "title": "Your Article Title Here",
      "url": "https://yoursite.com/your-article",
      "cover_image": "https://yoursite.com/cover.png",
      "description": "A brief description of the article content.",
      "html": "" // Full article HTML content, JSON-escaped
    },
    {
      "product_id": "art_002",
      "title": "Another Article Title",
      "url": "https://yoursite.com/another-article",
      "cover_image": "https://yoursite.com/cover2.png",
      "description": "Another article description.",
      "html": "" // Full article HTML content, JSON-escaped
    }
  ]
}

Step 3 — Send and verifyClick Send. A 200 OK response confirms the corpus has been uploaded successfully.

Postman — request body with JSON data and 200 OK response

You can verify the upload under Miso Dashboard → Data Sets → Catalog.

Miso Dashboard — Data Sets → Catalog showing uploaded articles

Install the Miso SDK

Add the Miso JavaScript SDK to your webpage using either method:

npm (Node Module)
Script Tag

Install the SDK via npm:

npm install --save @miso.ai/client-sdk

Then import it in your JavaScript file:

import MisoClient from '@miso.ai/client-sdk';

Add the following to your <head>:

<script async src="https://cdn.jsdelivr.net/npm/@miso.ai/client-sdk@1.12.7/dist/umd/miso.min.js"></script>

Since the SDK loads asynchronously, use the misocmd queue to ensure your code runs only after the SDK is ready:

const misocmd = window.misocmd || (window.misocmd = []);
misocmd.push(() => {
  const MisoClient = window.MisoClient;
  // Your initialization code here
});

Add the Ask UI to Your Page

Place the container element in your HTML where you want the Ask interface to appear:

<body>
  <div id="miso-ask-combo" class="miso-ask-combo"></div>
</body>

Configure the workflow by adding the following script:

<script>
  const misocmd = window.misocmd || (window.misocmd = []);
  misocmd.push(async () => {
    // setup client
    const MisoClient = window.MisoClient;
    const client = new MisoClient('YOUR_PUBLISHABLE_API_KEY');
    const rootWorkflow = client.ui.ask;

    // wait for styles to be loaded
    await client.ui.ready;

    // render DOM and get element references
    // default templates are available since v1.9.1
    const defaults = MisoClient.ui.defaults.ask;
    const templates = defaults.templates;
    const rootElement = document.querySelector('#miso-ask-combo');
    rootElement.innerHTML = templates.root();

    // setup workflows
    // uncomment the following lines if your SDK version is older than v1.12.5
    // defaults.wireFollowUps(client, rootElement.querySelector(`.miso-ask-combo__follow-ups`));
    // defaults.wireRelatedResources(client, rootElement.querySelector(`.miso-ask-combo__related-resources`));

    // start query if specified in URL parameters
    rootWorkflow.autoQuery();
  });
</script>

Replace YOUR_PUBLISHABLE_API_KEY with the key obtained in Step 1. To test, open the page in a browser and add ?q=your+question to the URL.

Complete Example

Here is a minimal working HTML file that puts it all together:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Miso Ask Demo</title>
  <script async src="https://cdn.jsdelivr.net/npm/@miso.ai/client-sdk@1.12.7/dist/umd/miso.min.js"></script>
</head>
<body>
  <div id="miso-ask-combo" class="miso-ask-combo"></div>

  <script>
    const misocmd = window.misocmd || (window.misocmd = []);
    misocmd.push(async () => {
      // setup client
      const MisoClient = window.MisoClient;
      const client = new MisoClient('YOUR_PUBLISHABLE_API_KEY');
      const rootWorkflow = client.ui.ask;

      // wait for styles to be loaded
      await client.ui.ready;

      // render DOM and get element references
      // default templates are available since v1.9.1
      const defaults = MisoClient.ui.defaults.ask;
      const templates = defaults.templates;
      const rootElement = document.querySelector('#miso-ask-combo');
      rootElement.innerHTML = templates.root();

      // setup workflows
      // uncomment the following lines if your SDK version is older than v1.12.5
      // defaults.wireFollowUps(client, rootElement.querySelector(`.miso-ask-combo__follow-ups`));
      // defaults.wireRelatedResources(client, rootElement.querySelector(`.miso-ask-combo__related-resources`));

      // start query if specified in URL parameters
      rootWorkflow.autoQuery();
    });
  </script>
</body>
</html>

Save this as client_sdk_test_ask.html, open it in a browser, and append ?q=media to the URL to see the Ask module in action.

Live Demo & Visuals

Once configured, the Miso Ask module provides a professional, interactive UI out of the box. To verify your setup is working:

Open client_sdk_test_ask.html in a browser.
Append ?q=media to the URL — you should see an AI-generated answer based on your uploaded corpus, along with follow-up suggestions and related resources.

Ask module — AI-generated answer for the query "media"

API keys can be passed via the api_key query parameter or the X-API-KEY request header. There is one publishable key and one secret key per environment — use the publishable key in client-side code and the secret key for server-side API calls.

Next Steps

Template Helpers

Customize the layout and content of Ask UI elements.

Elements Reference

Browse all customizable UI components available in the Ask module.

Product / Content Upload API

Full reference for uploading your corpus to Miso.

Ask Questions API

The underlying API powering the Ask module Q&A responses.

Authentication

Learn how API keys work and how to authenticate your requests.

👋 Introduction

🏊 Data Integration

Support

Overview

Complete Example

Live Demo & Visuals

Next Steps

Template Helpers

Elements Reference

Product / Content Upload API

Ask Questions API

Authentication

👋 Introduction

🏊 Data Integration

Support

​Overview

​Complete Example

​Live Demo & Visuals

​Next Steps

Template Helpers

Elements Reference

Product / Content Upload API

Ask Questions API

Authentication

Overview

Complete Example

Live Demo & Visuals

Next Steps