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)

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

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

For actions that should happen in the participant’s browser (open a doc, prefill a form), set execution_mode: "client" and omit webhook_url. The backend short-circuits the tool call with:

{
  "name": "open_pricing_page",
  "status": "client_handled",
  "function_id": "fn-uuid"
}

Your frontend SDK listens for the tool-call event on the Daily data channel and responds to the LLM directly. (Web SDK integration is rolling out — until then, prefer webhook mode for production.)

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`

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.

Getting Started

Meetings

Personas

Scenarios

Embed Scenario

Post-Meeting Data

Goals

Avatars

Voices

Tools

Users

Guides

Integrations

Agent Skills

Tools (Custom Functions)

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

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

​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

Errors

Limits

API surface

Worked example — booking a meeting