Skip to main content

Quickstart

In this quickstart, you build a minimal chat interface in your React application on the Kapa Chat SDK and ask it your first question.

By the end, you will have:

  • A Custom Frontend integration configured for your domains.
  • A working chat in your app, answering from your knowledge base through Kapa's managed agent.

Before you start​

Before you start, you should have:

  • A Kapa project with indexed knowledge sources. If you have not done this yet, complete Index your first source first.
  • Permission to edit the Kapa project; if buttons in the platform are greyed out, contact a team admin.
  • A React application to integrate into.

Create the integration​

  1. Open app.kapa.ai, navigate to Integrations (under Configuration in the sidebar), and click Add new integration.
  2. Choose Custom Frontend and give it a name.
  3. Under Enabled domains, add the domains your app runs on, production and staging. Only requests from enabled domains can submit questions; this powers the bot protection that lets the SDK run fully client-side without exposing an API key. For local development, http://localhost is enabled by default.
  4. Copy the integration ID from the integration row's Actions column.

Install the SDK​

npm install @kapaai/react-sdk

Add the provider and a chat component​

Wrap your application (or the part that hosts the chat) with KapaProvider, then build the interface with the useChat hook:

import React, { useState } from 'react';
import { KapaProvider, useChat } from '@kapaai/react-sdk';

function ChatApp() {
  return (
    <KapaProvider integrationId="your-integration-id" callbacks={{}}>
      <ChatInterface />
    </KapaProvider>
  );
}

function ChatInterface() {
  const [message, setMessage] = useState('');
  const { conversation, submitQuery, isGeneratingAnswer, isPreparingAnswer } = useChat();

  const handleSubmit = (e) => {
    e.preventDefault();
    if (message.trim()) {
      submitQuery(message);
      setMessage('');
    }
  };

  return (
    <div className="chat-container">
      <div className="conversation">
        {conversation.map((qa) => (
          <div key={qa.id || `temp-${qa.question}`} className="qa-pair">
            <div className="question">{qa.question}</div>
            <div className="answer">{qa.answer}</div>
          </div>
        ))}
        {isPreparingAnswer && <div className="loading">Preparing answer...</div>}
      </div>

      <form onSubmit={handleSubmit}>
        <input
          type="text"
          value={message}
          onChange={(e) => setMessage(e.target.value)}
          placeholder="Ask a question..."
          disabled={isGeneratingAnswer}
        />
        <button type="submit" disabled={isGeneratingAnswer}>
          Send
        </button>
      </form>

      {/* Required unless contractually agreed otherwise */}
      <div className="powered-by">
        Powered by <a href="https://kapa.ai" target="_blank" rel="noopener noreferrer">kapa.ai</a>
      </div>
    </div>
  );
}

The "powered by kapa.ai" attribution is required in your chat interface unless contractually agreed otherwise; you can style it to match your design, as long as it stays visible and legible.

Verify​

Run your app and ask a question about your product. The answer streams in, grounded in your knowledge base. If nothing comes back, check that the domain you are testing on is in the integration's Enabled domains.

Summary​

You created a Custom Frontend integration, enabled your domains, and built a minimal chat interface on KapaProvider and useChat, answering from your knowledge base through Kapa's managed agent.

Next steps​