Tools — let Wilow call your backend mid-chat

Tools are how Wilow takes an action instead of just answering. You define a tool — name, description, JSON schema for its input, webhook URL, secret — and Wilow uses it when a visitor's question matches. Example: "Check my order status for #12345" → Wilow calls your check_order_status tool with { orderNumber: "12345" }, gets back a result, and speaks it in plain language.

Tools that touch per-user data (order status, billing, account state) need to know who's asking. That's a separate concern with its own setup — see Authenticated visitor tools.

When to define a tool

Define a tool when the answer changes per-user and exists in a system Wilow doesn't have access to: order status, account balance, stock availability, the next available appointment slot. RAG handles static facts ("what's your return policy"); tools handle state ("where's my order").

Don't define a tool when the answer is the same for everyone. RAG is cheaper, more reliable, and doesn't require you to run an endpoint.

Configure

Admin → Tools → New tool.

  1. Name — machine identifier (check_order_status). Lowercase, underscore-separated. Visible to Wilow; it uses this to pick which tool to invoke.
  2. Label — human name shown in the admin (e.g. "Order status lookup").
  3. Description — what the tool does. Wilow reads this verbatim to decide when to call it. Write it precisely (see Pitfalls).
  4. Input schema — JSON Schema for the tool's parameters. Validated before Wilow can submit anything; invalid shapes never reach your endpoint. Required fields must be marked required or Wilow won't fill them reliably.
  5. Webhook URL — HTTPS endpoint we POST the call to.
  6. Secret — signs every request with HMAC-SHA256.
  7. Hit Test — fire a synthetic call at your endpoint with representative arguments. You'll see the response inline. If it's anything other than 2xx, fix before saving.
  8. Hit Save — the tool goes live on the next widget turn.

Request shape

{
  "tenantId": "…",
  "tool": "check_order_status",
  "arguments": { "orderNumber": "12345" },
  "conversationId": "…",
  "visitorEmail": "[email protected]"
}

Every request carries X-Wilow-Signature: sha256=<hex> — HMAC of the raw body using your secret. Verify before trusting. Snippet for your stack: Webhook security → Verifying the signature.

Response — shaping the reply

Return any JSON. Wilow paraphrases whatever you send back into a natural reply. Plain strings work too; so do deeply-nested objects.

The cleaner your response, the cleaner the visitor-facing answer. Compare:

{"ok": true, "data": {"status": "shipped", "carrier": "DPD", "tracking": "1Z…"}}

vs.

{
  "message": "Order #12345 shipped with DPD on Monday. Tracking: 1Z…",
  "tracking_url": "https://dpd.example/track/1Z…"
}

Both work. The second gives Wilow a ready-made sentence and a URL to offer as a follow-up — less risk of mis-phrasing, fewer surprises.

For errors, return { "error": "order not found" } (or similar). Wilow will tell the visitor, apologise briefly, and offer handoff if it's configured.

Pitfalls

  • Keep descriptions precise. Vague descriptions ("does order stuff") lead Wilow to call the tool when it shouldn't. Write what the tool does AND when it's the right answer — e.g. "Looks up the current shipping status for an order by its order number. Use this when a visitor asks where their order is or whether it shipped."
  • Don't use tools as a retrieval substitute. If the answer lives in your knowledge base, let RAG find it — tools are for live state (orders, accounts, stock). Running a tool on every question would balloon your latency and your budget.
  • Validate server-side too. Even though we validate inputs against your JSON Schema, your endpoint should still check — somebody else's client could hit the same URL. Treat the webhook like any other public API.
  • Handle failures gracefully. If your webhook returns 500, Wilow tells the visitor it couldn't check and offers a handoff (if configured) instead of making something up.
  • Slow tools block the reply. Wilow waits for your response before answering. Target ≤ 2 s. If the underlying system is slower, return a "we're checking — you'll get an email shortly" string and do the real work async.
  • Don't expose destructive tools without care. A cancel_order or apply_refund tool hands Wilow authority to take money-moving actions on a visitor's behalf. Put authentication in front of it (Authenticated visitor tools) and keep the parameter set narrow.