For the complete documentation index, see llms.txt. This page is also available as Markdown.

Tools & Events

Let your Human Agent call functions during a conversation, and react to the agent from your own page.

Tool Calling

Tools (function calling) let the agent's LLM trigger actions while it talks — look something up, submit a form, update your UI, or notify a backend system. You define each tool's name, description, and JSON-schema parameters; the LLM decides when to call it and with what arguments.

Tools are configured per agent. You can manage them two ways:

Each tool has an enabled flag. A disabled tool keeps its configuration but is hidden from the LLM, so you can turn a tool off without losing its setup.

Delivery Modes

Every tool declares how its calls are delivered. There is no agent-wide default — each tool picks its own mode.

Mode
Where the call goes
Your responsibility

Webhook

Ojin POSTs the call to a URL you configure, server-side

Stand up the endpoint; no browser code

Client

The widget emits a DOM event in the user's browser

Listen for the event on the embedding page

Use webhook delivery for backend actions (write to a database, call an API, send a notification). Use client delivery for things that happen in the user's browser (navigate the page, open a modal, update on-page state).

Webhook Delivery

When a webhook tool fires, Ojin sends an HTTP request to the tool's configured URL:

  • Method POST, header Content-Type: application/json.

  • A 30-second timeout.

The request body carries the call under a tool_call_message object. The fields you'll use:

Field
Meaning

name

The tool that was called

parameters

The call arguments, as a JSON string (parse it before use)

tool_call_id

Unique id for this call

response_required

true when the agent is waiting for your response (see below)

The body also includes additional session metadata fields alongside tool_call_message; you can ignore them for most integrations.

Waiting for a response

Each webhook tool has a wait for response setting:

  • On (response_required: true) — the agent waits for your endpoint, then feeds the result back into the conversation so the LLM can use it. Return HTTP 2xx with a JSON body:

    If you omit the result key, the entire JSON body is used as the result. An empty body (or 204) is treated as an empty result. A non-2xx status, a timeout, or an unparseable body surfaces an error result to the LLM instead.

  • Off (response_required: false) — fire-and-forget. Ojin sends the request and does not wait; the LLM immediately continues with a neutral acknowledgement. Anything your endpoint returns is ignored.

Client Delivery

When a client tool fires, the widget dispatches a DOM CustomEvent named ojinToolCall. The event fires on window (not on the <ojin-agent> element), so add the listener to window:

The arguments field is renamed to args above because arguments is a reserved word inside regular functions.

event.detail carries:

Field
Type
Meaning

function_name

string

The tool that was called

tool_call_id

string

Unique id for this call

arguments

object

The call arguments, already parsed

Client delivery is one-way. There is no path to send a value back to the agent from the browser — the agent continues as soon as it dispatches the call. If the LLM needs to use a result, use webhook delivery with wait for response turned on.

Managing Tools via the REST API

Agent endpoints accept your API key, so you can manage tools programmatically. Authenticate with the X-API-Key header (see Get your API key).

Tools live on the agent itself. Set them with the agent update endpoint, PATCH /v1/agents/{agent_id}, using the tools array:

To read an agent's current tools (each returned with its server-assigned tool_id), use GET /v1/agents/{agent_id}. For the full schema, see the REST API reference.

Widget Events

Beyond ojinToolCall, the <ojin-agent> widget emits DOM events you can listen for to build custom UI, transcripts, or telemetry around the conversation. All events fire on window.

Conversation events

Event

detail

Fires when

ojinToolCall

{ function_name, tool_call_id, arguments }

A client-delivered tool is called (see above)

botIsSpeaking

{ isSpeaking: boolean }

The agent starts or stops speaking

ReceivedTranscriptUser

{ text, timestamp, user, final }

A user speech transcript arrives (final: false for interim)

ReceivedTranscriptBot

{ text }

A chunk of the agent's response text arrives

BotTtsStopped

no payload (detail is null)

The agent's current spoken turn ends or is interrupted

UserStartedSpeaking

no payload (detail is null)

The user starts speaking

UserStoppedSpeaking

no payload (detail is null)

The user stops speaking

ConnectionTimeout

{ duration_s, bot_state, connection_state }

Connection setup exceeds its timeout; the widget resets and shows an error

Advanced / telemetry events

These carry fine-grained audio and timing signals, useful for meters, latency dashboards, or debugging. They are more granular than the conversation events above and may change — don't depend on them for core logic.

Event

detail

Fires when

userSpeakingChanged

{ isSpeaking: boolean }

Browser voice-activity detection toggles

userVolume

{ volume: number }

The user's microphone level is sampled

botVolume

{ volume: number }

The agent's playback level is sampled

LatencyReport

per-utterance latency breakdown

The agent reports timing for a turn

ConnectionTimingReport

connection timing breakdown

The session finishes connecting

Next Steps

Last updated

Was this helpful?