Skip to main content
This guide shows how to embed Meridial Voicebox in your React app.

​
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 cobrowse 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?",
      ]}
      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 setups (Vite, CRA, etc.) you can omit it.

​
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[]
}
PropDescription
childrenCustom content for the trigger button. Defaults to a “Help” label with an icon.
publishableKeyYour Meridial publishable key.
identifierOptional identifier for the current user. Used to associate sessions with a specific user in the dashboard.
baseUrlMeridial API base URL. Defaults to the hosted service.
firstMessageThe agent’s opening message when a session starts.
instructionsSystem instructions that shape the agent’s behavior.
metadataArbitrary key-value data attached to the session. Surfaces in the dashboard against the session record. Values must be strings.
onErrorCallback invoked when the widget encounters an error. Defaults to logging to the console.
toolsTools the agent can call during a session. See Agent tools below.
sampleQuestionsSuggested prompts shown in the widget before a session starts.

​
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 app (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 app",
      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.

​
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";