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:

• In the Ojin dashboard when configuring an agent — the agent's tools editor.

• Programmatically via the REST API.

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:

{
  "tool_call_message": {
    "name": "get_order_status",
    "parameters": "{\"order_id\":\"A123\"}",
    "tool_call_id": "call_abc",
    "response_required": true,
    "tool_type": "function"
  }
}

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.

The webhook request is not signed — there is no secret header. Treat the webhook URL itself as a secret, serve it over HTTPS, and validate the payload before acting on it.

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:

  { "result": "Your order shipped on Tuesday." }

  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:

window.addEventListener("ojinToolCall", (event) => {
  const { function_name, tool_call_id, arguments: args } = event.detail;
  // Run the browser-side action for `function_name` using `args`.
  // `args` is already an object — no parsing needed.
});

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:

curl -X PATCH https://api.ojin.ai/v1/agents/$AGENT_ID \
  -H "X-API-Key: $OJIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": [
      {
        "enabled": true,
        "function": {
          "name": "open_pricing",
          "description": "Open the pricing page for the user.",
          "parameters": {
            "type": "object",
            "properties": { "plan": { "type": "string" } }
          }
        },
        "delivery": { "mode": "client" }
      },
      {
        "enabled": true,
        "function": {
          "name": "create_ticket",
          "description": "File a support ticket.",
          "parameters": {
            "type": "object",
            "properties": { "summary": { "type": "string" } }
          }
        },
        "delivery": {
          "mode": "webhook",
          "url": "https://example.com/hooks/ticket",
          "wait_for_response": true
        }
      }
    ]
  }'

The tools array is full-replace. Tools are matched by function.name: a name already on the agent is updated in place, a new name is created, and any existing tool whose name is not in the array is deleted. To change one tool, send the complete set. To leave tools untouched, omit tools from the request entirely.

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

window.addEventListener("ReceivedTranscriptUser", (event) => {
  const { text, final } = event.detail;
  if (final) console.log("User said:", text);
});

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

• Create & Configure — set up the agent these tools belong to

• Widget Integration — embed the agent on your page

• REST API — full schema for programmatic management