React setup - Meridial

This guide shows how to embed Meridial Voicebox into any React application, including frameworks such as Next.js, Remix, React Router, Gatsby, Vite, and more.

1) Install the package

npm i @meridial/react

2) Embed Voicebox in your app

<Voicebox /> is the single component you embed. It renders a trigger button and the user-facing support widget for live voice support and human support escalation. Add it where you want in-app support to be available:

"use client"

import { Voicebox } from "@meridial/react"

export function VoiceboxWidget({
  publishableKey,
  userId,
}: {
  publishableKey: string
  userId?: string
}) {
  return (
    <Voicebox
      publishableKey={publishableKey}
      identifier={userId}
      firstMessage="Hi, I'm your assistant. How can I help?"
      instructions="You are a helpful assistant that can answer questions and guide users through the product."
      metadata={{ orgId: "org_123", plan: "pro" }}
      sampleQuestions={[
        "How do I reset my password?",
        "Where can I update billing?",
      ]}
      shaderColor="#6941c6"
      onError={(err) => console.error("[Voicebox]", err)}
    />
  )
}

publishableKey comes from your Meridial dashboard. Use identifier to associate sessions with a specific user.

The "use client" directive is required in Next.js App Router. In other React frameworks you can omit it as per your framework’s documentation.

Props

interface VoiceboxProps {
  children?: React.ReactNode
  baseUrl?: string
  publishableKey?: string
  identifier?: string
  firstMessage?: string
  instructions?: string
  metadata?: Record<string, string>
  onError?: (error: string) => void
  tools?: VoiceboxTools
  sampleQuestions?: string[]
  shaderColor?: `#${string}`
}

Prop	Description
`children`	Custom content for the trigger button. Defaults to a “Help” label with an icon.
`publishableKey`	Your Meridial publishable key.
`identifier`	Optional identifier for the current user. Used to associate sessions with a specific user in the dashboard.
`baseUrl`	Meridial API base URL. Defaults to the hosted service.
`firstMessage`	The agent’s opening message when a session starts.
`instructions`	System instructions that shape the agent’s behavior.
`metadata`	Arbitrary key-value data attached to the session. Surfaces in the dashboard against the session record. Values must be strings.
`onError`	Callback invoked when the widget encounters an error. Defaults to logging to the console.
`tools`	Tools the agent can call during a session. See Agent tools below.
`sampleQuestions`	Suggested prompts shown in the widget before a session starts.
`shaderColor`	The primary color of the shader in the chat widget. Defaults to `#6941c6` when not provided.

Custom trigger

Pass children to replace the default trigger button content:

<Voicebox publishableKey={publishableKey}>
  <img src="/support-avatar.png" alt="Get help" className="size-10 rounded-full" />
</Voicebox>

Agent tools

The SDK exports tool and useTool so the agent can perform actions in your application (navigate, fill forms, read state, and so on). Define a tool with a Zod input schema and an execute handler:

import { Voicebox, tool } from "@meridial/react"
import { z } from "zod"

<Voicebox
  publishableKey={publishableKey}
  tools={{
    navigateToPath: tool({
      description: "Navigate to a path in the application",
      inputSchema: z.object({ path: z.string() }),
      execute: async ({ path }) => {
        router.push(path)
        return `Navigating to ${path}`
      },
    }),
  }}
/>

Registering tools from child components

When a tool needs access to local component state (for example, a form on the current page), use useTool instead of passing tools through <Voicebox /> props:

import { tool, useTool } from "@meridial/react"
import { z } from "zod"

const schema = z.object({
  firstName: z.string(),
  lastName: z.string(),
})

function SettingsPage() {
  const form = useForm({ /* ... */ })

  useTool({
    tools: {
      enterPersonalInformation: tool({
        description: "Fill in the user's personal information",
        inputSchema: schema,
        execute: async (input) => {
          form.reset(input)
          return "Personal information updated."
        },
      }),
    },
    onToolCall: (event) => {
      console.log("Tool called:", event.toolId, event.response)
    },
  })

  return <form>{/* ... */}</form>
}

Tools registered via useTool are merged with any tools passed to <Voicebox />. On key conflicts, hook-registered tools take precedence.

Prompting the agent

When the Voicebox session is connected, useTool returns an optional generateReply function. Call it after app milestones (e.g. onboarding steps) to have the agent speak with custom instructions.

const { generateReply } = useTool({ tools })

await createOrg(data)
generateReply?.(
  "The user just created their organization. Congratulate briefly and explain the next step."
)

generateReply is undefined when the Voicebox is closed or not connected.

Instructions passed to generateReply are truncated to a maximum of 1,000 characters. This limit is enforced on both the client and the agent as a safeguard against issues with overly long prompts.

Styling

The component uses Tailwind CSS and is designed to work with existing Tailwind / shadcn setups. Two options:

Option 1: scan the package with your Tailwind build

In your global stylesheet:

@source "../node_modules/@meridial/react/dist/**/*.{js,mjs}";

Adjust the relative path to match your stylesheet’s location.

Option 2: import the prebuilt CSS

If you don’t want Tailwind to scan the package:

@import "@meridial/react/dist/styles.css";

​1) Install the package

​2) Embed Voicebox in your app

​Props

​Custom trigger

​Agent tools

​Registering tools from child components

​Prompting the agent

​Styling

​Option 1: scan the package with your Tailwind build

​Option 2: import the prebuilt CSS

1) Install the package

2) Embed Voicebox in your app

Props

Custom trigger

Agent tools

Registering tools from child components

Prompting the agent

Styling

Option 1: scan the package with your Tailwind build

Option 2: import the prebuilt CSS