Chatbot Integration & Operations Guide

End-to-end instructions for creating Veritas chatbots, preparing data, issuing API keys, and embedding the widget on your website. Follow the sections below in order or jump straight to what you need.

Create a Chatbot

Launch the wizard at Dashboard → Chatbots → New. Provide a clear name, optional description, and keep sandbox mode on while testing. The wizard walks you through channel and model configuration—see the next sections for recommended defaults.

  1. Step 1: Fill in the bot name (e.g., "Support Assistant") and a short summary for teammates.
  2. Step 2: Choose the Web channel, select an API key, and keep the default model GPT-4o Mini.
  3. Step 3: Review and create. You can attach documents later if your knowledge base isn’t ready yet.

Create an API Key

Visit Settings → API to issue a key for the website widget. Scope permissions (e.g., chatbots.read, conversations.write) and store the secret in a safe place.

API Key Checklist
  • Name keys after their usage (e.g., "Marketing Widget").
  • Limit permissions to what the embed requires.
  • Set rate limits that align with expected traffic.
  • Copy the secret immediately—future views only show metadata.

Upload Documents

Go to Knowledge → Documents and upload PDFs, DOCX, or TXT files. Veritas extracts content, stores summaries, and generates embeddings automatically.

  • Use clean, up-to-date documents for best responses.
  • Split large manuals into topic-specific files.
  • Remove retired content to keep answers current.

Assign Documents to Chatbots

Edit your bot from Dashboard → Chatbots and pick the documents it should reference. A chatbot will only search the files you assign, so keep scopes tight for accurate answers.

Best Practices
  • Create separate bots for different product lines or regions.
  • Test the bot after uploading major content updates.
  • Detach outdated documents to prevent irrelevant responses.

Website Embed

Paste the snippet below immediately before your site's closing </body> tag. If you are self-hosting on a domain like https://app.tryveritas.dev ensure the script is loaded from that origin and add data-api-url="https://app.tryveritas.dev" so the widget can reach the backend. When using the cloud app (https://veritas.ai) no extra attribute is required.

Embed Snippet
<script src="https://tryveritas.dev/embed/chatbot.js"
  data-bot-id="YOUR_CHATBOT_ID"
  data-api-key="YOUR_API_KEY_HERE">
</script>

Replace YOUR_CHATBOT_ID with the chatbot ID shown on the Chatbots list (top-right of each card) andYOUR_API_KEY_HERE with the API key secret produced when you created the key. For self-hosted deployments change the script domain and add data-api-url so the widget calls your backend, e.g.

<script src="https://tryveritas.dev/embed/chatbot.js"
  data-api-url="https://tryveritas.dev"
  data-bot-id="YOUR_CHATBOT_ID"
  data-api-key="YOUR_API_KEY_HERE">
</script>

Environment Variables

Frameworks like Next.js let you keep secrets out of version control. The sample below loads the widget dynamically using process.env values.

Next.js Example
// .env.local or equivalent
NEXT_PUBLIC_VERITAS_CHATBOT_ID=your_chatbot_id
NEXT_PUBLIC_VERITAS_CHATBOT_API_KEY=your_api_key

// components/VeritasChatbot.tsx
import { useEffect } from "react"

export function VeritasChatbot() {
  useEffect(() => {
    const script = document.createElement("script")
    script.src = "https://tryveritas.dev/embed/chatbot.js"
    script.async = true
    script.dataset.botId = process.env.NEXT_PUBLIC_VERITAS_CHATBOT_ID ?? ""
    script.dataset.apiKey = process.env.NEXT_PUBLIC_VERITAS_CHATBOT_API_KEY ?? ""
    document.body.appendChild(script)
    return () => {
      document.body.removeChild(script)
    }
  }, [])

  return null
}

For React, Vue, or vanilla JS, inject the script after mount and source the IDs from your configuration service or env variables.

Customize Widget Appearance

Veritas allows you to fully customize your chatbot widget's appearance to match your brand identity. You can change colors, fonts, and text to create a seamless experience that aligns with your website's design.

Accessing the Customization Page
  1. Navigate to Dashboard → Chatbots to see all your chatbots.
  2. Find the chatbot you want to customize and click on it (or use the settings/gear icon).
  3. In the chatbot settings modal, locate the "Customize Widget" section.
  4. Click the "Customize Widget" button to open the customization page.

Alternatively, you can directly access the customization page at /dashboard/chatbots/[chatbot-id]/customize by replacing [chatbot-id] with your chatbot's ID.

Customizable Fields

1. Chatbot Title

Change the title displayed at the top of the chatbot widget. By default, this is "Veritas AI Assistant", but you can customize it to match your brand, such as "Support Assistant", "Help Center", or your company name.

2. Header Styling

Customize the header bar at the top of the chatbot widget:

  • Background Color: Set the header background color using a color picker or hex code (e.g., #1B1A55).
  • Text Color: Choose the text color for the chatbot title and header elements to ensure proper contrast and readability.

The header displays your customized title and provides the main visual identity for the widget.

3. Send Button Styling

Personalize the send button that customers use to submit messages:

  • Background Color: Set the send button background color. This can match your brand colors or complement your header design.
  • Text Color: Choose the text color for the "Send" label to ensure it's readable against your chosen background color.

The send button appears at the bottom right of the input container, next to the escalate button.

4. Font Family

Select the font family used throughout the chatbot widget. Available options include:

  • Manrope (default) - Modern, clean sans-serif
  • Inter - Professional and highly legible
  • Open Sans - Friendly and approachable
  • Lato - Warm and readable
  • Montserrat - Geometric and contemporary
  • Poppins - Rounded and friendly
  • Raleway - Elegant and sophisticated
  • Arial - Classic and widely supported
  • Georgia - Serif option for traditional designs

The selected font applies to all text within the chatbot widget, including messages, the header title, and button labels.

Live Preview

The customization page features a real-time preview panel that shows exactly how your chatbot will look on your website. As you change colors, fonts, or the title, the preview updates instantly, allowing you to see the results before saving.

The preview includes:

  • The chatbot widget header with your custom title and colors
  • A sample message area showing how messages appear
  • The input container with the escalate button (orange) and send button (customized colors)
  • All styling applied in real-time as you make changes
Saving Your Customization
  1. Make your desired changes to the chatbot appearance using the color pickers, input fields, and dropdown menus.
  2. Review the live preview to ensure everything looks as expected.
  3. Click the "Save Customization" button at the bottom of the page.
  4. Your changes will be saved to the database and applied immediately to all instances of the widget on websites where it's embedded.

Note: Changes take effect immediately after saving. Users visiting websites with your chatbot widget will see the updated appearance on their next interaction or page refresh.

Best Practices

  • Ensure sufficient contrast between text and background colors for accessibility (WCAG AA compliance recommended).
  • Use colors that align with your brand guidelines to maintain consistency across all customer touchpoints.
  • Test your customization on different devices and screen sizes to ensure readability.
  • Keep the title concise (20-30 characters) to fit properly in the header.
  • Choose fonts that are legible at small sizes, as the widget may appear smaller on mobile devices.

Verify the Widget

  • Refresh the page and confirm the Veritas launcher appears (usually bottom-right).
  • Open dev tools → Network tab to verify chatbot.js loads without errors.
  • Ask a few questions to ensure the bot references only the intended documents.
  • Verify that your customization settings (colors, fonts, title) are correctly applied to the widget.

Human Escalations & Support

When customers need help beyond what your chatbot can provide, they can create an escalation directly from the chatbot interface. This feature enables seamless handoff from AI to human support agents with end-to-end encrypted messaging.

How Escalations Work

1. Customer Creates Escalation

When a customer encounters an issue that requires human assistance, they can click the escalation button in the chatbot widget. They'll be prompted to select a reason (e.g., "Technical Issue", "Billing Question", "Complex Inquiry") and provide any additional details about their problem.

2. Email Notification

Once an escalation is created, the organization owner receives an email notification with details about the escalation, including the customer's message, the AI's response, reason for escalation, and priority level. This ensures you're immediately aware of issues that need human attention.

3. Escalation Appears in Dashboard

All escalations are automatically listed in the Escalations tab of your dashboard. You can filter escalations by status (Open, In Progress, Resolved, Closed) and priority (Low, Medium, High, Urgent) to prioritize your support efforts.

Escalation Stages & Workflow

1Open

The escalation is newly created and awaiting attention. You can see the customer's initial message and the AI's response. At this stage, you can:

  • Mark it as "In Progress" to indicate you're working on it
  • Use "Take Over Conversation" to chat directly with the customer
  • Mark it as "Resolved" if the issue is already addressed

2In Progress

The escalation is actively being handled by a support agent. When you click "Take Over Conversation", you establish an end-to-end encrypted chat session with the customer.

3Resolved

The customer's issue has been successfully resolved. You should mark an escalation as resolved after the customer's problem has been solved through direct conversation or other means.

4Closed

The escalation has been closed and archived. This status is typically set automatically or manually for completed escalations that no longer need attention.

Direct Customer Communication

Starting a Secure Chat

Click the "Take Over Conversation" button on any open or in-progress escalation to initiate a direct, end-to-end encrypted chat with the customer. This opens a secure chat interface where:

  • All messages are encrypted using RSA-OAEP 2048-bit encryption
  • You can see the conversation history including the customer's initial message
  • Messages are sent and received in real-time with automatic polling
  • Both you and the customer can see when messages are encrypted (indicated by a lock icon)

Sending Messages

Type your message in the chat input field and press Enter or click Send. Your message will be automatically encrypted with the customer's public key before being sent, ensuring only the customer can decrypt and read it. Messages appear in the chat interface immediately (optimistic UI) and are confirmed once successfully sent.

Receiving Customer Messages

Customer messages are automatically decrypted and displayed in the chat. The system polls for new messages every 3 seconds, so you'll see customer responses in near real-time. Messages from customers appear with a different styling (green gradient) to distinguish them from your messages.

Resolving Escalations

After you've successfully addressed the customer's issue through the direct chat or other means, you should mark the escalation as resolved:

  1. Verify that the customer's issue has been fully resolved
  2. Click the "Mark Resolved" button on the escalation card
  3. The escalation status will update to "Resolved" and move to the resolved filter
  4. The escalation remains in your dashboard for reference but is no longer active

Best Practice: Always mark escalations as resolved after the customer's issue has been solved. This helps track resolution times, identify patterns in escalations, and maintain a clean escalation queue.

Security & Privacy

All escalation conversations use end-to-end encryption (E2EE) with RSA-OAEP 2048-bit keys and SHA-256 hashing. This means:

  • Only you and the customer can read the messages
  • Messages are encrypted on the client side before being sent to the server
  • The server stores only encrypted content and cannot decrypt messages
  • Zero-knowledge architecture ensures maximum privacy for sensitive customer communications

Safety & Performance

  • Rotate API keys regularly and regenerate compromised keys immediately.
  • Enforce a Content Security Policy that whitelists https://veritas.ai for scripts and network calls.
  • Load the script with defer or dynamically to avoid blocking rendering.
  • Limit key scopes to the minimum features your embed requires.
Example CSP Snippet
Content-Security-Policy: script-src 'self' https://tryveritas.dev; connect-src 'self' https://tryveritas.dev

Tips & Troubleshooting

  • Laggy responses? Split large documents or trim redundant content.
  • Unexpected answers? Double-check assigned docs and remove outdated files.
  • Multiple client sites? Create separate bots and API keys per domain for easier rotation.
Customization Hook
window.addEventListener("veritas-chatbot-ready", () => {
  if (window.veritasChatbot) {
    window.veritasChatbot.updateTheme({
      primaryColor: "#1B1A55",
      launcherPosition: "bottom-right"
    })
  }
})

Contact Support

Need personalized help? Email us at hello@southbytelabs.com with your organization name and a quick summary of the issue.

Quick links: API Keys • Create Chatbot • Documents. Or go back to the Landing Page.