Add an agent to a website

Publish an agent in audentic and add your website's exact origin in Test & publish before installing the widget. The widget requests a connection from audentic; the OpenAI API key stays on the audentic server.

Working with Codex, Claude Code, or another coding assistant? Download the integration skill or plugin, give it your published agent ID, and ask it to add the widget to your website. To create the agent first, follow the OpenAI voice agent guide.

React

Install the package in your website project:

npm install @audentic/react@0.7.0

Render SessionControl with your published agent ID. In a Next.js App Router project, put it in a Client Component:

"use client";

import { SessionControl } from "@audentic/react";

export function VoiceAssistant() {
  return <SessionControl agentId="YOUR_AGENT_ID" />;
}

The package supports React 18.2 and React 19. It includes its own widget styling; the host app does not need Tailwind or an audentic stylesheet. The default API URL is https://www.audentic.org/api. If you run a different audentic deployment, pass its API URL, including /api:

<SessionControl
  agentId="YOUR_AGENT_ID"
  apiBaseUrl="https://YOUR_AUDENTIC_DOMAIN/api"
  showTranscript
/>

Optional props include widgetConfiguration for presentation overrides, showTranscript to open captions initially, onStatusChange for connection status, and onTranscriptChange for transcript items. Model choice, instructions, business knowledge, tools, and session limits are configured in audentic rather than browser props.

Recovery and typed input

Version 0.7.0 includes Type instead, idle warnings, and Resume conversation with a compatible audentic backend. Typed mode does not request microphone access but still uses the provider connection and admission allowance. Realtime can return text-only output; Live keeps a duration-billed Live session with audio playback suppressed. It is not an offline fallback.

Resume credentials stay in widget memory and are scoped to the agent and origin. A reload or unmount can lose them. Resuming starts a new provider connection with bounded saved conversation context; confirmed actions come from server records and are not replayed. Older backends can continue regular calls without enabling recovery.

Owners can save contactUrl and contactLabel in the builder’s widget settings. React consumers can override them with props of the same names; custom elements accept contact-url and contact-label. Use an HTTPS contact page, mailto: address, or tel: number. The widget only displays a validated supplied destination.

Any website

Use the script and custom element generated in Test & publish. For an audentic instance at https://www.audentic.org, the snippet is:

<script src="https://www.audentic.org/embed.js" defer></script>
<audentic-embed
  agent-id="YOUR_AGENT_ID"
  api-base-url="https://www.audentic.org/api"
></audentic-embed>

Place the snippet where visitors should see the agent. For a different audentic deployment, replace both audentic URLs with that deployment's origin. The script registers a audentic-embed custom element, bundles its own React runtime, and isolates the widget in a shadow root. The element also accepts show-transcript and a JSON widget-configuration attribute.

Browser requirements and checks

  • The agent must be published and the website's exact origin must be in its allowed website list. Include the port for local development, such as http://localhost:4000.
  • Voice requires HTTPS or localhost, a WebRTC-capable browser, and microphone permission.
  • An iframe needs allow="microphone; autoplay" on the parent iframe element.
  • A restrictive Content Security Policy must permit the audentic script, the audentic API in connect-src, the audentic host in frame-src for custom interactive views, and the widget's inline styles.
  • Test a real microphone conversation on the deployed website. The builder preview tests the saved agent but does not check the external site's permissions or origin.

The browser fetches the public agent configuration, then sends a WebRTC SDP offer (with microphone capture only in voice mode) to /api/voice/session. audentic authorizes the origin, connects the visitor to the selected voice model, and returns a signed session token for the widget's server-backed tools and transcript finalization. There is no OpenAI key in the browser.

Updated · Written by the audentic team