Widget Integration

Embed a fully interactive Human Agent on your website with a single HTML tag.

Quick Start

Add the Ojin widget script to your page and drop in the agent tag:

<script src="https://widget.ojin.ai/ojin-agent.js"></script>
<ojin-agent agent-id="your-agent-id"></ojin-agent>

The widget script URL is available in your agent's settings page in the dashboard. Copy it from there to ensure you're using the latest version.

That's it. Your users get a live conversational agent with video, audio, and a real-time avatar — no backend code required.

Appearance & Layout

The widget renders as a floating overlay on your page. It includes the avatar video feed, audio controls, and session management — all self-contained.

Widget styling and positioning options are configured in your agent's settings in the dashboard. Check your agent's widget configuration for available customization options.

Finding Your Agent ID

After creating and configuring your agent, copy the agent ID from the agent settings page in the Ojin dashboard.

Controlling Access

Agents are private by default — connections from any website are rejected until you configure access.

Hostname Allowlist

In the dashboard, add the domains that are allowed to connect to your agent:

Configuration	Behaviour
No hostnames configured	Private — all connections rejected
myapp.com, staging.myapp.com	Only requests from those exact domains are accepted
*	Public — connections accepted from any domain

Using * (wildcard) allows anyone to connect to your agent. This is useful for demos but not recommended for production. Use specific hostnames to restrict access to your own domains.

No API key is needed in the widget. Access is controlled entirely by the hostname allowlist — the server checks the request's origin against your configured domains.

How It Works

When the widget loads on your page:

1. The widget calls the Session API (POST /v1/public/agents/connect) with your agent ID

2. The server validates the request origin against the hostname allowlist

3. On success, the server returns a WebRTC room URL and token

4. The widget connects to the WebRTC room directly

5. Audio, video, and signaling all flow over a single WebRTC connection

The entire handshake takes a few seconds. After that, your user is in a live conversation with the agent.

Custom Integrations

If you need more control than the widget provides — for example, building a native mobile app or a custom web experience — you can call the Session API directly from your backend and connect to the WebRTC room yourself.

See the Session API Reference for details.

Troubleshooting

Widget not loading

• Verify the widget script URL is correct and the script loads without errors (check browser console)

• Confirm the agent-id attribute matches your agent's ID in the dashboard

"agent_offline" error

• Check that your agent's status is set to online in the dashboard

• Ensure all required fields are filled — the dashboard won't let you go online with missing configuration

"auth_failed" error

• Verify your domain is in the agent's hostname allowlist in the dashboard

• Check that the Origin header sent by the browser matches one of your configured hostnames exactly

• If testing locally, add localhost or 127.0.0.1 to the allowlist

"concurrency_limit" error

• Your agent's maximum concurrent sessions are in use. Wait for an active session to end or increase the max concurrency setting in the dashboard

No audio or video

• Ensure the user's browser has granted microphone and camera permissions

• Check that the WebRTC connection is not blocked by a firewall or corporate proxy