Custom Functions

Give your AI persona access to tools it can call during the meeting — an inventory lookup, a CRM write, a booking API, a scoring function, or an action on the page the visitor is looking at. When the conversation reaches a moment the tool covers, the AI calls it, uses the result to shape the next turn, and (optionally) narrates a filler while the call is in flight.

Two places a tool can run

Pick the mode from where the work belongs. It is the first decision, and it changes what you build.

Webhook mode

We POST the arguments to your endpoint and hand the AI what you return. Use it for anything that lives on your servers — CRM, booking, pricing, scoring.

Client mode

The tool runs in your visitor’s own browser, inside the session they are already signed into. Use it to act on the page in front of them.

The reason client mode exists is where the credentials live. The work happens in your page, as the signed-in user, so Waterr never receives your users’ cookies, tokens or API keys.

Webhook mode

Define the function

Go to Developer → Tools and create a Custom Function: name, description, JSON-schema arguments, and the URL Waterr will call when the AI invokes it.

Mention it in a scenario prompt

Open your scenario, put your cursor in the script, and @-mention the function. The mention wires it to the scenario for that meeting.

(Optional) Set filler + on-resolve behavior

on_call — what the AI says when it decides to invoke the function.
static_filler — a fixed phrase spoken while the tool call is in flight, so the participant hears something instead of silence.
on_resolve — how the AI weaves the result back into the conversation.

Your endpoint receives a signed request and whatever it returns becomes the tool result. Full payload, signature verification and error shapes: Custom Functions API.

Client mode — acting on your website

The assistant in your site’s chat widget can move the visitor around, prefill a form, or read their account — by asking your page to do it. Your page decides whether and how.

Define the function

Developer → Tools → New tool, and set Execution mode to Client. Leave the webhook URL empty.Give the arguments an enum, not free text. The model then picks from things you actually have, and nothing said in conversation can be turned into an arbitrary URL.

{
  "name": "navigate_to",
  "description": "Take the visitor to a page on this site when they ask to see something that lives on another page.",
  "parameters_schema": {
    "type": "object",
    "properties": {
      "page": { "type": "string", "enum": ["pricing", "billing", "docs"] }
    },
    "required": ["page"]
  },
  "execution_mode": "client"
}

Attach it to your scenario

@-mention it in the scenario script, the same as any other tool.

One handler per tool name, next to your embed snippet:

<script src="https://waterr.ai/embed/widget.js"
        data-waterr-scenario="<scenario-id>" async></script>

<script>
  // The loader is async, so queue — Waterr.on drains this on startup.
  window.Waterr = window.Waterr || { q: [] };

  window.Waterr.q.push(["navigate_to", ({ page }) => {
    const route = { pricing: "/pricing", billing: "/settings/billing", docs: "/docs" }[page];
    if (!route) throw new Error("unknown page: " + page);
    router.push(route);
    return { navigated_to: route };
  }]);
</script>

Once the loader has landed you can register directly with Waterr.on(name, fn).

Try it

Open your site, start the call, and ask in plain language — “show me your pricing.”

What you return is what the AI hears

Handlers may be sync or async. The return value becomes the tool result, and throwing tells the persona the action failed so it can say so and carry on:

Waterr.on("refund_order", async ({ order_id }) => {
  const res = await fetch(`/api/orders/${order_id}/refund`, { method: "POST" });
  if (!res.ok) throw new Error("that order can't be refunded");
  return { refunded: true };
});

Your handlers are the security boundary

The AI can only invoke names you registered — no matter what someone says to it. Authorize inside the handler: check the user, throw if they are not allowed, or show your own confirmation dialog before acting. Never register something you would not let a visitor trigger by asking for it politely.

Don’t hard-navigate. window.location.href = ... reloads the document, which destroys the widget’s iframe and drops the call mid-sentence. Use your router’s soft navigation — and mount the widget from a root layout, outside the routed subtree, or your framework will unmount it on route change and do the same thing.

Client-mode tools need a page listening for them, so they work on the sidebar widget only. The same scenario used in a meeting room or over the phone will call the tool and time out. See which embeds support this.

Use cases

CRM lookups

Fetch account context when the participant identifies themselves.

Booking

Schedule a follow-up call at the end of a discovery session.

Live scoring

Score a participant answer against a rubric and adapt the next question.

Inventory / pricing

Quote real numbers instead of the AI guessing.

Guided navigation

Walk a visitor to the page they just asked about, mid-sentence.

Account self-service

Read the signed-in visitor’s plan or usage without them leaving the chat.

Custom Functions API — full schema, endpoints, the client-mode wire protocol, and limits.
Live Website Events — the other direction: your site telling the assistant what the visitor is doing.
Embed API — putting the widget on an authenticated page.

Overview

Get Started

Capabilities

Sharing with Others

Customization

Security

Two places a tool can run

Webhook mode

Client mode

Webhook mode

Client mode — acting on your website

What you return is what the AI hears

Your handlers are the security boundary

Use cases

CRM lookups

Booking

Live scoring

Inventory / pricing

Guided navigation

Account self-service

​Two places a tool can run

Webhook mode

Client mode

​Webhook mode

​Client mode — acting on your website

​What you return is what the AI hears

​Your handlers are the security boundary

​Use cases

CRM lookups

Booking

Live scoring

Inventory / pricing

Guided navigation

Account self-service

​Related

Two places a tool can run

Webhook mode

Client mode — acting on your website

What you return is what the AI hears

Your handlers are the security boundary

Use cases

Related