Web Widget Deployment

Embed an AI voice and chat widget on any website with a single script tag.

The Web Widget deployment embeds an interactive AI assistant directly into your website. Visitors can type messages, speak via microphone, and hear voice responses — all from a floating widget that loads with a single script tag. Voice input and output are optional; the widget works as a text-only chat by default.

Voice capabilities (microphone input and spoken responses) are optional. You can deploy a text-only chat widget by skipping the Voice Input and Voice Output steps during configuration.

Creating a Web Widget Deployment

Navigate to your assistant, click Configure Assistant, then select Deployments from the sidebar. Click Add Deployment and choose Web Widget.

The web widget wizard walks you through four steps:

1. Experience

   Define the greeting, quickstart questions, and session behaviour.

   Required fields:

   • Greeting — Welcome message displayed when the widget opens. Describe your agent so users know how to interact with it

   Quickstart Questions:

   • Quickstart Questions — Pre-configured questions displayed as clickable buttons below the greeting. Users can tap one to start a conversation instantly, or type their own query

   Advanced settings (expand to configure):

   • Error Message — Message shown when an unexpected error occurs
   • Idle Silence Timeout — Duration of silence before Rapida prompts the user (3000-10000ms, default: 30000ms)
   • Idle Timeout Backoff — How many times the idle timeout multiplies before ending the session (0-5, default: 2)
   • Idle Message — Message spoken/shown when the user hasn’t responded (default: “Are you there?”)
   • Maximum Session Duration — Hard limit before the session is automatically ended (3-15 minutes, default: 5 min)
2. Voice Input (Speech-to-Text) — Optional

   Enable microphone-based voice input for the widget. Users can speak instead of typing.

   If enabled:

   • STT Provider — Deepgram, AssemblyAI, Google, Azure, OpenAI Whisper, AWS Transcribe, Cartesia, Rev.ai, Speechmatics, Sarvam, Groq, or Nvidia
   • Model — Provider-specific transcription model
   • Language — Primary transcription language
   • Encoding — Audio encoding format
   • Sample Rate — Audio sample rate

   Advanced settings (expand to configure):

   • Voice Activity Detection (VAD) — Silero VAD with configurable threshold (0.0-1.0, default: 0.8)
   • Background Noise Removal — RNNoise for removing ambient noise before transcription
   • End of Speech Detection — Silence-based EOS with configurable timeout (default: 1000ms)

   Click Skip to deploy a text-only widget without voice input. You can enable it later by editing the deployment.

3. Voice Output (Text-to-Speech) — Optional

   Enable spoken audio responses from the assistant. The assistant’s text responses will be read aloud through the browser.

   If enabled:

   • TTS Provider — ElevenLabs, Deepgram, Azure, Google, OpenAI, AWS Polly, Cartesia, Resemble, Rime, Sarvam, Neuphonic, MiniMax, Groq, Speechmatics, or Nvidia
   • Model — Provider-specific voice model
   • Language — Output speech language
   • Voice ID — The specific voice from your TTS provider

   Advanced settings (expand to configure):

   • Pronunciation Dictionaries — Custom pronunciation for domain-specific terms, names, and acronyms
   • Conjunction Boundaries — Natural pause points at conjunctions for more human-like speech
   • Pause Duration — Length of pause at conjunction boundaries (100-300ms, default: 240ms)

   Click Skip to deploy without voice output. Text responses will still appear in the chat. You can enable voice output later.

4. Features

   Enable additional content sections available in the web widget beyond the chat interface.

   Available sections:

   • Help Center / Q&A Listing — Display a searchable FAQ section alongside the chat, powered by your knowledge base
   • Product Catalog — Show product listings and details within the widget
   • Blog Post / Articles — Surface blog posts and articles for self-service browsing

   Click Deploy Web Widget to save and activate the deployment.

Embedding the Widget

After deployment, Rapida generates a pre-built widget script (app.min.js) hosted on the Rapida CDN. You configure it by setting window.chatbotConfig before the script loads.

Quick Start

Add this to any page on your website:

<script>
  window.chatbotConfig = {
    assistant_id: "YOUR_ASSISTANT_ID",
    token: "YOUR_PROJECT_CREDENTIAL_KEY",
  };
</script>
<script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>

The widget renders a floating button in the corner of the page. Clicking it opens the chat window with your assistant’s greeting and quickstart questions.

Replace YOUR_ASSISTANT_ID with your assistant’s ID (found on the assistant overview page) and YOUR_PROJECT_CREDENTIAL_KEY with your project credential key from the credential vault.

Configuration Options

The window.chatbotConfig object accepts the following properties:

<script>
  window.chatbotConfig = {
    // Required
    assistant_id: "YOUR_ASSISTANT_ID",
    token: "YOUR_PROJECT_CREDENTIAL_KEY",

    // Optional: target a specific assistant version
    assistant_version: "VERSION_ID",

    // Optional: custom API base URL (for self-hosted deployments)
    api_base: "https://assistant-01.rapida.ai",

    // Optional: language for the widget UI (default: "en", auto-detects from <html lang="">)
    language: "en",

    // Optional: enable debug logging in the browser console
    debug: false,

    // Optional: user identification
    user: {
      name: "Jane Doe",
      user_id: "user-123",
      meta: {
        plan: "enterprise",
        source: "pricing-page",
      },
    },

    // Optional: theme customisation
    theme: {
      color: "#0f62fe",
    },
  };
</script>
<script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>

Property	Type	Required	Default	Description
assistant_id	string	Yes	—	Your assistant’s ID
token	string	Yes	—	Project credential key from the credential vault
assistant_version	string	No	latest	Pin to a specific assistant version
api_base	string	No	https://assistant-01.rapida.ai	API base URL (override for self-hosted)
language	string	No	"en"	Widget UI language. Auto-detects from <html lang=""> attribute changes
debug	boolean	No	false	Enable verbose logging in browser console
user.name	string	No	"Guest"	Display name for the user in the chat
user.user_id	string	No	auto-generated	Unique user identifier. If not provided, a UUID is generated and persisted in localStorage
user.meta	Record<string, string>	No	{ source: "web plugin" }	Custom metadata attached to the session (e.g., plan, UTM params, page URL)
theme.color	string	No	"#2663eb"	Primary accent color for the widget UI

Full HTML Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to my website</h1>

  <!-- Rapida Web Widget Configuration -->
  <script>
    window.chatbotConfig = {
      assistant_id: "2139456643765633024",
      token: "5e04b962dfd988ca0f4ac9e097f17841ebf34d7e38c50297e245c12bddce2117",
      user: {
        name: "Guest",
        user_id: "website-visitor-001",
        meta: {
          source: "marketing-site",
          page: window.location.pathname,
        },
      },
      theme: {
        color: "#0f62fe",
      },
    };
  </script>
  <script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>
</body>
</html>

Place both script tags just before the closing </body> tag. The defer attribute on app.min.js ensures it loads after the config is set without blocking page rendering.

CSS Customisation

The widget supports CSS custom properties to control its size and position. Add these in a <style> tag before the script:

<style>
  #RPDContainer.RPDContainer .RPD_Wrapper {
    --cds-chat-BASE-border-radius-xsmall: 0px;
    --cds-chat-BASE-border-radius-small: 0px;
    --cds-chat-BASE-border-radius-med: 0px;
    --cds-chat-BASE-border-radius-large: 10px;
    --cds-chat-BASE-border-radius-xlarge: 10px;
    --cds-chat-BASE-width: 400px;
    --cds-chat-BASE-height: 600px;
    --cds-chat-BASE-bottom-position: 20px;
    --cds-chat-BASE-right-position: 20px;
  }
</style>

CSS Variable	Default	Description
--cds-chat-BASE-width	400px	Width of the chat window
--cds-chat-BASE-height	600px	Height of the chat window
--cds-chat-BASE-bottom-position	0px	Distance from the bottom of the viewport
--cds-chat-BASE-right-position	0px	Distance from the right of the viewport
--cds-chat-BASE-border-radius-large	10px	Border radius of the chat window

Full-Screen Widget

To make the widget fill the entire viewport (e.g., for a dedicated support page):

<style>
  #RPDContainer.RPDContainer .RPD_Wrapper {
    --cds-chat-BASE-width: 100% !important;
    --cds-chat-BASE-height: 100dvh !important;
    --cds-chat-BASE-bottom-position: 0px;
    --cds-chat-BASE-right-position: 0px;
  }
</style>

Platform Integration Guides

WordPress

1. Go to Appearance > Theme File Editor (or use a plugin like Insert Headers and Footers)
2. Add the following before the closing </body> tag in your theme’s footer.php:

<script>
  window.chatbotConfig = {
    assistant_id: "YOUR_ASSISTANT_ID",
    token: "YOUR_PROJECT_CREDENTIAL_KEY",
  };
</script>
<script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>

3. Save and verify the widget loads on your site

Shopify

1. Go to Online Store > Themes > Edit Code
2. Open theme.liquid
3. Add the scripts before the closing </body> tag:

<script>
  window.chatbotConfig = {
    assistant_id: "YOUR_ASSISTANT_ID",
    token: "YOUR_PROJECT_CREDENTIAL_KEY",
  };
</script>
<script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>

4. Save and preview your store

Webflow

1. Go to Project Settings > Custom Code
2. Paste in the Footer Code section:

<script>
  window.chatbotConfig = {
    assistant_id: "YOUR_ASSISTANT_ID",
    token: "YOUR_PROJECT_CREDENTIAL_KEY",
  };
</script>
<script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>

3. Publish your site

Squarespace

1. Go to Settings > Advanced > Code Injection
2. Paste in the Footer section:

<script>
  window.chatbotConfig = {
    assistant_id: "YOUR_ASSISTANT_ID",
    token: "YOUR_PROJECT_CREDENTIAL_KEY",
  };
</script>
<script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>

3. Save and preview your site

Next.js

Use Next.js Script component in your root layout:

// app/layout.tsx (App Router)
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script id="rapida-config" strategy="beforeInteractive">
          {`window.chatbotConfig = {
            assistant_id: "${process.env.NEXT_PUBLIC_RAPIDA_ASSISTANT_ID}",
            token: "${process.env.NEXT_PUBLIC_RAPIDA_TOKEN}",
          };`}
        </Script>
        <Script
          src="https://cdn-01.rapida.ai/public/scripts/app.min.js"
          strategy="lazyOnload"
        />
      </body>
    </html>
  );
}

Vue / Nuxt

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          children: `window.chatbotConfig = {
            assistant_id: "YOUR_ASSISTANT_ID",
            token: "YOUR_PROJECT_CREDENTIAL_KEY",
          };`,
        },
        {
          src: "https://cdn-01.rapida.ai/public/scripts/app.min.js",
          defer: true,
        },
      ],
    },
  },
});

For plain Vue, add the script tags directly to public/index.html.

Angular

Add to src/index.html before the closing </body> tag:

<script>
  window.chatbotConfig = {
    assistant_id: "YOUR_ASSISTANT_ID",
    token: "YOUR_PROJECT_CREDENTIAL_KEY",
  };
</script>
<script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>

Static HTML / Any Website

Copy and paste the following into any HTML page:

<script>
  window.chatbotConfig = {
    assistant_id: "YOUR_ASSISTANT_ID",
    token: "YOUR_PROJECT_CREDENTIAL_KEY",
  };
</script>
<script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>

Self-Hosted Deployment

If you’re running Rapida on your own infrastructure, override the api_base to point at your assistant API:

<script>
  window.chatbotConfig = {
    assistant_id: "YOUR_ASSISTANT_ID",
    token: "YOUR_PROJECT_CREDENTIAL_KEY",
    api_base: "https://your-assistant-api.example.com",
  };
</script>
<script defer src="https://cdn-01.rapida.ai/public/scripts/app.min.js"></script>

You can also self-host the widget script itself. Build the react-widget SDK and upload the generated dist/app.min.js to your own CDN or static file server:

cd sdks/react-widget
yarn install
yarn build
# Upload dist/app.min.js to your CDN

Then reference your self-hosted script:

<script defer src="https://your-cdn.example.com/scripts/app.min.js"></script>

How It Works

When the widget script loads, it:

1. Reads configuration from window.chatbotConfig
2. Creates a <div id="rapida-chat-app"> element and appends it to the page <body>
3. Initialises a VoiceAgent instance using @rapidaai/react SDK with ConnectionConfig.WithSDK
4. Fetches the assistant’s web plugin deployment config (greeting, suggestions, voice settings)
5. Renders a floating button — clicking it opens the chat window
6. Supports both text input and voice input (with microphone visualizer, device selection, and mute controls)
7. Auto-detects language changes on the <html lang=""> attribute
8. Persists the user ID in localStorage (rpd__uuid) across sessions when no user.user_id is provided

Widget Features

The pre-built widget includes:

• Text chat — Type messages and receive markdown-rendered responses
• Voice input — Click the audio icon to switch to voice mode with real-time microphone visualization
• Microphone device selector — Choose from available input devices via a dropdown flyout
• Mute/unmute — Toggle microphone during voice conversations
• Quickstart suggestions — Clickable buttons from your deployment’s configured suggestions
• Session reset — Restart the conversation via the header button
• Auto-scroll — Chat automatically scrolls to the latest message

Input and Output Modes

Voice Input	Voice Output	User Experience
Disabled	Disabled	Text-only chat
Enabled	Disabled	Users speak, assistant replies with text
Disabled	Enabled	Users type, assistant replies with voice + text
Enabled	Enabled	Full voice conversation with text transcript

Troubleshooting

Issue	Solution
Widget does not appear	Verify assistant_id and token are correct. Check the browser console for errors — the widget logs "Please provide an assistant_id" or "Please provide an authentication token" if either is missing
Voice input not working	Ensure the page is served over HTTPS (required for microphone access). Check that the deployment has STT configured
Widget loads but shows no greeting	Ensure you have an active Web Widget deployment for this assistant (not an SDK/API deployment)
User ID resets across visits	The widget stores the auto-generated ID in localStorage as rpd__uuid. If localStorage is cleared, a new ID is generated. Pass a stable user.user_id in the config to avoid this
CORS errors in console	If self-hosting, ensure your reverse proxy allows requests from your website’s origin to the assistant API
window.chatbotConfig not read	Make sure the config script runs before app.min.js. Use a regular <script> tag (not defer) for the config, and defer on the widget script

Use Cases

Customer Support

Provide instant answers and reduce support ticket volume with 24/7 voice-enabled help.

Lead Generation

Engage visitors with qualifying questions and route them to your sales team.

Product Recommendations

Guide users through product catalogs with personalized suggestions.

Appointment Scheduling

Let users book appointments directly through conversational flow.

Related

• Create an Assistant — Set up your assistant before deploying
• Web App (React SDK) — Full SDK integration for custom React apps with complete UI control
• Credentials — Manage your project credential keys
• Conversation Logs — Monitor widget conversations
• Webhooks — Receive post-conversation events