The React SDK for Proficient AI provides you with ready-to-use and customizable interfaces where your users can interact with your agents. Internally, it uses the JS Client SDK to connect to your agents. The React SDK currently comes with one component named InteractionView, which can be themed and customized to your application’s needs.

​
Installation

You can install the React SDK via npm or Yarn.

npm i -E @proficient/react

Since we are at an early stage and moving fast, we recommend using the exact version for each SDK (hence the -E flag). This will prevent sudden undesired changes in your application.

​
Quickstart

You can connect your application to Proficient AI in just a few minutes.

Prerequisite: Make sure you’ve created and activated an agent before proceeding further. See creating my first agent for more details.

Copy the publishable API key associated with your project from Project Settings. Add it as a NEXT_PUBLIC_PROFICIENT_API_KEY environment variable to your app.

For details on how to add an environment variable to your Next.js app see the official docs.

Now add the InteractionView component to the page where you want your users to interact with your agent.

import { InteractionView } from "@proficient/react";

export default function App() {
  // Agent ID can be hardcoded or retrieved from the API
  const agentId = "ag_Lad8YCGGiDLiqIZPWRXmc2ix";
  // User external ID should be accessed dynamically
  const userExternalId = "gtLIK8ELsHTr0Fajg28Ud9eFpJJ3";
  return (
    <div>
      <InteractionView
        // Your publishable API key that starts with `pk_`
        apiKey={process.env.NEXT_PUBLIC_PROFICIENT_API_KEY}
        agentId={agentId}
        userExternalId={userExternalId}
      />
    </div>
  );
}

The userExternalId variable above simply refers to the unique ID of your user. For more details see User External ID.

​
InteractionView

A chat interface component that allows your users to interact with your Proficient AI agent.


This is currently the only component that the React SDK offers. Let us know if you need other types of components. We’d love to support your use case!

​
Props

apiKey
string
required

The publishable API key associated with your project. This can be found in the admin dashboard.

agentId
string
required

The unique ID of the agent. This can be found in the admin dashboard.

userExternalId
string
required

The unique ID of the user within your system. See User External ID for more details.

userHmac
string | () => Promise<string>

Either the HMAC hash for the given user or a function that returns a Promise resolving to the HMAC hash. This is required if the project has HMAC authentication enabled. Internally, the component caches the HMAC hash so that it is not computed on every render. See HMAC Authentication for more details.

layout
"casual" | "formal"
default: "casual"

The type of the chat interface layout.

  • "casual": looks like iMessage/WhatsApp.
  • "formal": looks like ChatGPT.
chatSectionHeight
number
default: 320

Chat section height in pixels. Must be greater than or equal to 240.

headerSectionHeight
number
default: 54

Header section height in pixels. Must be greater than or equal to 54.

autoAsk
boolean
default: true

If set to true, sending a message to the agent will automatically trigger an Ask request and the agent will reply to the message. This is the intuitive option but if you disable it, users will be able to send multiple messages before asking for a reply.

sendOnEnter
boolean
default: true

If set to true, pressing Enter will send the current text input as message.

inputPlaceholder
string
default: "Type something..."

The placeholder for the text area.

theme
ProficientTheme

The theme object including your brand colors. Can be created with the createTheme(params) factory function. See custom themes for more details.

​
Custom themes

You can use a custom theme to preserve your brand identity and ensure that the component interface matches the rest of your application.

Custom themes can be created with the createTheme(params) factory function which currently takes three colors as parameters. We then dynamically compute the rest of the colors that the component uses based on these three values.

import { createTheme } from "@proficient/react";

const theme = createTheme({
  colors: {
    background: "#1d1822",
    primary: "#9c0588",
    text: "#fff",
  },
});

Simply pass the theme object to the component as the theme prop.

<InteractionView
  // ... other props
  theme={theme}
/>

If you’re not happy with the dynamically computed theme, you can create it yourself instead of using createTheme(params). A theme is just a plain object that conforms to the ProficientTheme interface so you can create it any way you want.

OverviewJavaScript Client SDK