Tools

Tools are what let the agent do things — not just answer questions. Every Seny widget comes with a built-in set of tools for navigating your site, filling forms, and searching your content. You can also define your own tools that POST to your backend.

Built-in tools

These are enabled by default and configurable from the Tools tab. Toggle any of them off if you'd rather the agent not use them.

navigate

Takes the visitor to a specific page on your site. The agent calls it with the path it wants to go to — /pricing,/contact, etc. The widget performs a client-side navigation so the current conversation continues seamlessly across pages.

fill_form

Populates a form on the current page with values the visitor provided by voice. The agent receives a description of every form on your site (discovered during the crawl) and picks the right one. Visitors never type — they just say their name, email, and question.

scroll_to

Scrolls the page to a specific section when the visitor asks to see something on the current page. "Show me your pricing" scrolls to the pricing section if the agent can find it.

click

Clicks a button or link on the current page — accept cookies, open a menu, expand an FAQ. The agent can only click elements it discovered during the crawl.

search_site

Full-text search across every page Seny indexed during the initial crawl. The agent uses this when a visitor asks about something specific that isn't on the current page — "do you cater vegan?" triggers a search and the agent answers from the results.

Custom webhook tools

Define your own tools to connect the agent to your backend. Good examples: check inventory, book an appointment, look up an order, create a quote, send a notification to Slack.

Defining a tool

On the Tools tab, click Add custom tool and provide:

• A name the agent will use —check_inventory, book_appointment.
• A short description of when to call it. The agent decides from this, so be specific.
• A JSON schema of the arguments. Example:

{
  "type": "object",
  "properties": {
    "sku":     { "type": "string", "description": "Product SKU" },
    "quantity":{ "type": "integer", "description": "Quantity requested" }
  },
  "required": ["sku"]
}

• A webhook URL on your side that receives a POST with the arguments.

Request format

POST https://your-backend.example.com/seny-tools/check-inventory
Content-Type: application/json
X-Seny-Signature: sha256=abc123...
X-Seny-Widget-Id: wgt_abc123

{
  "tool": "check_inventory",
  "conversation_id": "conv_xyz",
  "arguments": {
    "sku": "BBQ-RIBS-RACK",
    "quantity": 4
  }
}

Response format

Respond with JSON. Whatever you return, the agent sees and speaks to the visitor:

{
  "result": "4 racks of ribs available for pickup tomorrow after 3pm",
  "status": "ok"
}

Signature verification

Every webhook includes an X-Seny-Signatureheader computed as HMAC-SHA256 over the raw body using your widget's signing secret (shown in the Tools tab). Verify it before trusting the payload:

import crypto from "node:crypto";

function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return signature === `sha256=${expected}`;
}

Tool call timing

Webhook calls time out after 5 seconds. If your backend is slow, the agent tells the visitor it's checking and retries once. Keep tool endpoints fast.