Meridial.dev React SDK

Installation

npm i @meridial/react

<Voicebox />

The single component you embed in your app. It renders a trigger button and the user-facing support widget for live voice support and cobrowse escalation.

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}`
}

You can find your publishable key in the Meridial dashboard.

| 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. |

Minimal example

"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)}
    />
  )
}

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. onToolCall is optional — pass it when you need to react in the UI after a tool runs (e.g. show a toast or log the result).

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.

When the Voicebox session is connected, useTool also returns an optional generateReply function. Call it to prompt the agent to speak with custom instructions — useful for onboarding flows you build yourself.

const { generateReply } = useTool({ tools })

async function handleOrgCreated() {
  await createOrg(data)
  generateReply?.(
    "The user just created their organization. Congratulate briefly and explain how to add their first contact."
  )
}

generateReply is undefined when the Voicebox is closed or not connected. Use optional chaining (generateReply?.(...)).

Note: 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";