Tools (Custom Functions)

A tool is a function in your code that the LLM can call during a live meeting. You define it once on your account, attach it to one or more scenarios, and the runtime invokes it (over webhook or in the browser) when the LLM emits a tool call. The wire format is identical to OpenAI / Tavus function-calling — port your existing tools with a name change.

When to use a tool

Look up a CRM record, calendar slot, or knowledge-base entry mid-call
Place an order, book a meeting, or write back to your system
Branch the dialogue on real-world state (account tier, inventory, eligibility)
Surface UI in the participant’s browser (open a doc, prefill a form)
Navigate the visitor around your own site mid-conversation (example)

The Tool object

Field	Type	Required	Description
`name`	string	✓	Function name the LLM calls. Pattern `^[a-zA-Z0-9_-]{1,64}$`. Unique per account.
`description`	string	✓	One-sentence prompt that tells the LLM when to call this tool.
`parameters_schema`	object	–	JSON Schema for the arguments. Top-level `type` must be `"object"`. Defaults to `{}`.
`execution_mode`	enum	–	`webhook` (default) or `client`. See below.
`webhook_url`	string	conditional	HTTP(S) endpoint. Required when `execution_mode = "webhook"`.
`webhook_secret`	string	–	HMAC-SHA256 signing secret. Write-only — never returned after creation.
`timeout_ms`	integer	–	Webhook response timeout. Range `1000`–`30000`. Default `10000`.
`on_call`	enum	–	What the persona says/does while the tool runs. `silent` (default) / `static_filler` / `generate_filler` / `passthrough`. See Conversational modes.
`static_filler`	string	conditional	Phrase the persona speaks during the call. Required when `on_call = "static_filler"`.
`on_resolve`	enum	–	What happens with the result after it returns. `generate_response` (default) / `add_to_context` / `response_in_result` / `fire_and_forget`.
`tool_spec`	object	read-only	The OpenAI-shaped spec the LLM sees. Computed from the fields above.

Example tool object

{
  "id": "4f8a6c50-9d3b-4c1f-9c0a-7a3b6e2d1f10",
  "name": "lookup_account",
  "description": "Fetch the participant's CRM record so you can reference their plan, MRR, and last contact date.",
  "parameters_schema": {
    "type": "object",
    "properties": {
      "account_id": { "type": "string", "description": "e.g. cus_XXXX" }
    },
    "required": ["account_id"]
  },
  "execution_mode": "webhook",
  "webhook_url": "https://your-app.com/waterr/tools/lookup_account",
  "has_webhook_secret": true,
  "timeout_ms": 8000,
  "on_call": "static_filler",
  "static_filler": "Sure, let me grab that for you.",
  "on_resolve": "generate_response",
  "tool_spec": {
    "type": "function",
    "function": {
      "name": "lookup_account",
      "description": "Fetch the participant's CRM record so you can reference their plan, MRR, and last contact date.",
      "parameters": {
        "type": "object",
        "properties": { "account_id": { "type": "string" } },
        "required": ["account_id"]
      }
    }
  },
  "created_at": "2026-06-18T12:34:56.000Z",
  "updated_at": "2026-06-18T12:34:56.000Z"
}

Execution modes

Mode	What happens	Use when
`webhook` (default)	We POST args to `webhook_url`, await JSON within `timeout_ms`, return the body to the LLM. Synchronous.	Your tool needs to compute or fetch a result server-side.
`client`	We short-circuit with `{ status: "client_handled" }`. Your frontend handles the call over the Daily data channel.	The action lives in the participant’s browser — open a doc, prefill a form.

Conversational modes

A tool call can take 1–8 seconds. Two extra fields control what the persona does during and after the call so the conversation doesn’t go dead.

`on_call` — what the persona does while the tool runs

Mode	What happens
`silent` (default)	Persona goes quiet. Matches legacy behavior.
`static_filler`	Persona speaks the literal `static_filler` phrase. Pre-rendered at meeting start — zero added latency.
`generate_filler`	Persona speaks one of a generic pool (“let me check on that”, “one moment”).
`passthrough`	Stay silent AND skip the LLM follow-up turn on the result (useful for analytics/CRM writes that shouldn’t enter the conversation).

{
  "on_call": "static_filler",
  "static_filler": "Sure, let me grab that for you."
}

static_filler is required when on_call = "static_filler" and forbidden otherwise.

`on_resolve` — what happens with the result

Mode	What happens
`generate_response` (default)	Result is fed to the LLM; persona speaks about it naturally.
`add_to_context`	Result is stashed in context, no spoken acknowledgment. Persona uses it on the next user turn.
`response_in_result`	Persona speaks the result text verbatim (skips LLM rewrite). Predictable for compliance disclaimers or fixed messaging.
`fire_and_forget`	Don’t wait for the webhook. Persona moves on; the result is logged but never surfaces in the conversation.

{
  "on_call": "static_filler",
  "static_filler": "One moment.",
  "on_resolve": "add_to_context"
}

On Gemini Live, response_in_result falls back to add_to_context — the native-audio API can’t be forced to speak an exact string. The result is still in context for the next turn. Use cloud-TTS providers (OpenAI, ElevenLabs, Cartesia) for true verbatim playback.

How it works at runtime

┌──────────────┐   1. tool_call         ┌──────────────────┐
│  LLM (in     │ ─────────────────────▶ │ meetingMLservice │
│  meeting)    │                        │ (Pipecat brain)  │
└──────────────┘                        └────────┬─────────┘
        ▲                                        │ 2. POST /meetings/{id}/tool-calls
        │ 4. result                              ▼
        │                                ┌──────────────────┐
        │                                │   CoreBackend    │
        │                                │   resolves +     │
        │                                │   signs + relays │
        │                                └────────┬─────────┘
        │                                        │ 3. POST <your webhook>
        │                                        │    X-Waterr-Signature: sha256=…
        │                                        ▼
        │                                ┌──────────────────┐
        └────────────────────────────────│   Your server    │
                                         │   returns JSON   │
                                         └──────────────────┘

1. Create a tool

Most people do this in Developer → Tools → New tool in Studio; the API is here for provisioning tools from your own code.

curl -X POST https://api.waterr.ai/v1/custom-functions \
  -H "Authorization: Bearer wai_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lookup_account",
    "description": "Fetch the participant'\''s CRM record so you can reference their plan, MRR, and last contact date.",
    "parameters_schema": {
      "type": "object",
      "properties": {
        "account_id": { "type": "string" }
      },
      "required": ["account_id"]
    },
    "execution_mode": "webhook",
    "webhook_url": "https://your-app.com/waterr/tools/lookup_account",
    "webhook_secret": "whsec_replace_me_with_random_64_chars",
    "timeout_ms": 8000
  }'

Response — 201 Created:

{
  "data": {
    "id": "fn-uuid",
    "name": "lookup_account",
    "...": "see full Tool object above",
    "has_webhook_secret": true
  }
}

webhook_secret is never returned — only has_webhook_secret: true. Rotate it any time by PATCHing the tool with a new value; every attached scenario picks up the change instantly.

2. Attach to a scenario

curl -X POST https://api.waterr.ai/v1/scenarios/{scenarioId}/custom-functions/{toolId}/attach \
  -H "Authorization: Bearer wai_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{ "active": true, "position": 0 }'

Response — 201 Created (or 200 OK if already attached):

{
  "data": {
    "id": "attachment-uuid",
    "scenario_id": "scenario-uuid",
    "custom_function_id": "fn-uuid",
    "active": true,
    "position": 0,
    "custom_function": { "...": "embedded tool definition" }
  }
}

Per-scenario fields

Field	What it does
`active`	When `false`, the tool is persisted on the scenario but hidden from the LLM. Pause without detaching.
`position`	Display order in the UI. Runtime ignores this.

# Disable the tool on one scenario only
curl -X PATCH https://api.waterr.ai/v1/scenarios/{scenarioId}/custom-functions/{toolId} \
  -H "Authorization: Bearer wai_<your_key>" \
  -d '{ "active": false }'

# Detach (definition is kept, attachment is removed)
curl -X DELETE https://api.waterr.ai/v1/scenarios/{scenarioId}/custom-functions/{toolId} \
  -H "Authorization: Bearer wai_<your_key>"

3. Handle the webhook

When the LLM calls the tool, CoreBackend POSTs this payload to your webhook_url:

{
  "id": "9b6c…",
  "type": "tool_call",
  "created_at": "2026-06-18T12:35:01.000Z",
  "data": {
    "function_id": "fn-uuid",
    "function_name": "lookup_account",
    "arguments": { "account_id": "cus_4f8a" },
    "tool_call_id": "call_abc123",
    "meeting_id": "meeting-uuid",
    "scenario_id": "scenario-uuid"
  }
}

Request headers

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`Waterr-CustomFunction/1.0`
`X-Waterr-Event`	`tool_call`
`X-Waterr-Function-Id`	The function UUID
`X-Waterr-Function-Name`	The declared `name`
`X-Waterr-Signature`	`sha256=<hex>` HMAC of the raw body

Respond with the result

Return any JSON within timeout_ms. Your response body IS the tool result the LLM sees on its next turn.

{
  "name": "Aanya Iyer",
  "plan": "Pro Annual",
  "mrr_usd": 299,
  "last_contact": "2026-05-30"
}

Non-JSON body → wrapped as { "result": "<your-text>" }
Responses larger than 256 KB are truncated
Non-2xx response → LLM sees { status: "error", error_code: "http_error", http_status: 500 } and recovers gracefully

Verify the signature

const crypto = require('crypto');

app.post('/waterr/tools/lookup_account',
  express.raw({ type: 'application/json' }),  // raw, not parsed
  async (req, res) => {
    const expected = 'sha256=' + crypto
      .createHmac('sha256', process.env.WATERR_TOOL_SECRET)
      .update(req.body)
      .digest('hex');

    const signature = req.headers['x-waterr-signature'];
    if (!signature || !crypto.timingSafeEqual(
      Buffer.from(signature), Buffer.from(expected)
    )) {
      return res.status(401).send('invalid signature');
    }

    const { arguments: args } = JSON.parse(req.body).data;
    const account = await crm.lookup(args.account_id);
    res.json(account);
  }
);

Use the raw request body for HMAC verification. express.json() and similar parsers mutate whitespace and break the signature.

Client-mode tools

Set execution_mode: "client" and omit webhook_url — in Studio, that is Developer → Tools → New tool with Execution mode set to Client. Use it when the action belongs in the participant’s browser rather than on a server — navigating your app, prefilling a form, opening a record, or calling your own API as the user who is already signed in. The point of client mode is where the credentials live. The tool runs inside your page, in the visitor’s existing session, so Waterr never holds your users’ cookies, tokens, or API keys. Your handler is also the authorization boundary: the agent can only invoke tools you registered, and your code decides whether this particular visitor may run them.

The round trip

  your page (app.example.com) — visitor already signed in
  ┌──────────────────────────────────────────────────────┐
  │  Waterr.on('navigate_to', fn)                        │
  │              ▲                    │                   │
  │   waterr:tool_call        waterr:tool_result          │
  │       (postMessage)          (postMessage)            │
  │              │                    ▼                   │
  │  ┌────────────────────────────────────────┐          │
  │  │  <iframe> Waterr embed                 │          │
  │  └──────▲─────────────────────┬───────────┘          │
  └─────────┼─────────────────────┼──────────────────────┘
            │  client_tool_call   │  client_tool_result
            │                     ▼
              meeting brain (holds the LLM turn open)

The persona’s turn stays parked until your handler answers or the timeout fires — it will never narrate an action your page did not perform.

Handling a call

If you embed with the standard loader snippet, register one handler per tool name. That is the whole integration:

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

<script>
  // The loader is async, so queue first — 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" }[page];
    if (!route) throw new Error(`unknown page: ${page}`);
    router.push(route);          // soft navigation — see the warning below
    return { navigated_to: route };
  }]);
</script>

Once the loader has landed you can also register directly:

Waterr.on("get_account", async () => {
  const res = await fetch("/api/me");   // your session, your cookies
  return res.json();
});

Waterr.off("get_account");              // and to remove one

Handlers may be sync or async. Whatever you return becomes the tool result the LLM reads on its next turn, 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 };
});

The handler map is your authorization boundary. The agent can only invoke names you registered, and your code decides whether this visitor may run them — check and throw, or show your own confirmation dialog first.

A hard navigation kills the call. window.location.href = ... reloads the document, which destroys the widget’s iframe and tears down the WebRTC session mid-sentence. Use your router’s soft navigation, and mount the widget from a root layout outside the routed subtree so your framework does not unmount it on route change either. If you must hard-navigate, expect the session to drop and reconnect.

Return a page name from an enum in your parameters_schema, not a URL. The model then picks from routes you actually have instead of inventing a 404, and no string from the conversation can be turned into a redirect.

If you embed the iframe yourself

The loader adds ?host=<your origin> to the iframe URL, and the widget refuses to send tool calls to an unidentified origin — a tool call asks your page to act, so broadcasting it to "*" is not an option. Hand-rolling the iframe means adding that yourself and speaking the protocol directly:

https://waterr.ai/embed/sidebar/SCENARIO_UUID?t=...&host=https://app.example.com

const WATERR_ORIGIN = "https://waterr.ai";

window.addEventListener("message", async (event) => {
  if (event.origin !== WATERR_ORIGIN) return;
  const msg = event.data;
  if (!msg || msg.type !== "waterr:tool_call") return;

  const reply = { type: "waterr:tool_result", call_id: msg.call_id };
  try {
    reply.result = await handlers[msg.name](msg.arguments ?? {});
  } catch (err) {
    reply.error = String(err.message ?? err);
  }
  frame.contentWindow.postMessage(reply, WATERR_ORIGIN);
});

Prefer the loader unless you have a reason not to — it handles the origin, the trust gates, call_id matching and error replies for you.

Timing and limits


Time your handler has to answer	`timeout_ms` on the tool (1000–30000, default 10000)
On timeout	The persona is told the action did not complete and continues
Result size	16 KB — larger results come back `{ truncated: true, preview }`
Duplicate `call_id`	Answered once; later replies are dropped

Client-mode handlers run in a page, so they should return in well under a second. If yours needs to do real work, do it asynchronously: return { status: "started" } immediately and let the persona ask again, or use webhook mode instead.

Which embeds support this

Client-mode tools need a page listening for them, so they work on the sidebar widget only:

Surface	Client-mode tools
Sidebar widget (`embed/widget.js`)	✅
Button, inline and avatar-assist embeds	✗
Meeting room, phone calls, Meet/Zoom/Teams bot	✗ (no host page at all)

Attaching a client-mode tool to a scenario used on another surface is not an error, but nothing will answer the call: the persona plays its filler line, waits out timeout_ms, and tells the participant the action did not complete. If a scenario is reused across surfaces, keep its client-mode tools on a variant that only the widget uses.

Example: navigating your site

curl -X POST https://api.waterr.ai/v1/custom-functions \
  -H "Authorization: Bearer wai_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "navigate_to",
    "description": "Take the visitor to a page on this site when they ask to see something that lives on another page. Only call when they clearly want to go there.",
    "parameters_schema": {
      "type": "object",
      "properties": {
        "page": {
          "type": "string",
          "enum": ["pricing", "billing", "docs", "contact"],
          "description": "Which page to open."
        }
      },
      "required": ["page"]
    },
    "execution_mode": "client",
    "timeout_ms": 5000,
    "on_call": "static_filler",
    "static_filler": "Sure — pulling that up.",
    "on_resolve": "generate_response"
  }'

Attach it to the scenario and the persona can move the visitor around your site mid-conversation, narrating as it goes.

Errors

Status	When
`400`	Invalid payload — bad `name` pattern, `parameters_schema.type` not `"object"`, `webhook_url` missing in webhook mode, or `timeout_ms` out of range. Body lists every error.
`401`	Missing or invalid API key.
`404`	Tool, scenario, or attachment not found on this account.
`409`	Tool name already in use on this account.

{
  "message": "Invalid payload",
  "errors": [
    "name must be a string matching ^[a-zA-Z0-9_-]{1,64}$ (OpenAI tool-name rule)",
    "webhook_url is required when execution_mode='webhook' (the default)"
  ]
}

Limits

Limit	Value
`name` length	64 chars, unique per account
`timeout_ms`	1000 – 30000 (default 10000)
Webhook response size	256 KB (truncated past this)
Webhook retries	None — failures surface to the LLM as `http_error`
Client-mode result size	16 KB (returns `{ truncated: true, preview }` past this)
Client-mode host origin	Required — the loader must pass `?host=<origin>`
Client-mode surfaces	Sidebar widget only today — see below

API surface

Tools (account-scoped):

Method	Path	Operation
`GET`	`/custom-functions`	List tools
`POST`	`/custom-functions`	Create a tool
`GET`	`/custom-functions/{id}`	Get a tool
`PATCH`	`/custom-functions/{id}`	Update a tool
`DELETE`	`/custom-functions/{id}`	Delete a tool

Scenario attachments:

Method	Path	Operation
`GET`	`/scenarios/{id}/custom-functions`	List attached tools
`POST`	`/scenarios/{id}/custom-functions/{toolId}/attach`	Attach a tool
`PATCH`	`/scenarios/{id}/custom-functions/{toolId}`	Update attachment
`DELETE`	`/scenarios/{id}/custom-functions/{toolId}`	Detach

Worked example — booking a meeting

Two tools (list_slots, book_slot) defined once, attached to both a sales and a support scenario.

# Define list_slots once
curl -X POST https://api.waterr.ai/v1/custom-functions \
  -H "Authorization: Bearer wai_<key>" \
  -d '{
    "name": "list_slots",
    "description": "List the user'\''s next 7 days of bookable 30-min slots.",
    "parameters_schema": {
      "type": "object",
      "properties": { "timezone": { "type": "string" } },
      "required": ["timezone"]
    },
    "webhook_url": "https://your-app.com/waterr/list_slots"
  }'
# → { "data": { "id": "fn-list-slots", ... } }

# Define book_slot once
curl -X POST https://api.waterr.ai/v1/custom-functions \
  -H "Authorization: Bearer wai_<key>" \
  -d '{
    "name": "book_slot",
    "description": "Book a slot the user just confirmed. Call ONLY after they say yes to a specific time.",
    "parameters_schema": {
      "type": "object",
      "properties": {
        "slot_iso": { "type": "string" },
        "title": { "type": "string" }
      },
      "required": ["slot_iso", "title"]
    },
    "webhook_url": "https://your-app.com/waterr/book_slot"
  }'

# Attach both to two scenarios
for scenario in salesScenarioId supportScenarioId; do
  for fn in fn-list-slots fn-book-slot; do
    curl -X POST https://api.waterr.ai/v1/scenarios/$scenario/custom-functions/$fn/attach \
      -H "Authorization: Bearer wai_<key>"
  done
done

During a meeting:

User: “Can we set up a follow-up sometime this week?”
LLM calls list_slots(timezone="Asia/Kolkata").
Your webhook returns [{slot:"2026-06-20T10:00:00+05:30"}, …].
LLM proposes the slots verbally.
User: “Friday at 10 works.”
LLM calls book_slot(slot_iso="2026-06-20T10:00:00+05:30", title="Follow-up").
Your webhook books it and returns { "ok": true, "booking_id": "bk_…" }.
LLM confirms: “Booked — you’ll get a calendar invite shortly.”

No frontend changes, no SDK. The conversation just works.

​When to use a tool

​The Tool object

​Example tool object

​Execution modes

​Conversational modes

​on_call — what the persona does while the tool runs

​on_resolve — what happens with the result

​How it works at runtime

​1. Create a tool

​2. Attach to a scenario

​Per-scenario fields

​3. Handle the webhook

​Request headers

​Respond with the result

​Verify the signature

​Client-mode tools

​The round trip

​Handling a call

​If you embed the iframe yourself

​Timing and limits

​Which embeds support this

​Example: navigating your site

​Errors

​Limits

​API surface

​Worked example — booking a meeting

When to use a tool

The Tool object

Example tool object

Execution modes

Conversational modes

`on_call` — what the persona does while the tool runs

`on_resolve` — what happens with the result

How it works at runtime

1. Create a tool

2. Attach to a scenario

Per-scenario fields

3. Handle the webhook

Request headers

Respond with the result

Verify the signature

Client-mode tools

The round trip

Handling a call

If you embed the iframe yourself

Timing and limits

Which embeds support this

Example: navigating your site

Errors

Limits

API surface

Worked example — booking a meeting