Skip to main content
A Web tool step runs one of your web tools: it asks the web page or app the caller is talking from to do something, such as fill in a form, open a page or read what’s in the cart, and waits for the page’s reply. The page does the work; the step sends the request, saves values from the reply, and moves on through On Success or On Failure.

Before you start

  • Create the web tool in APIs & MCPs. See Web tools.
  • Your web page or app must connect to the agent with the Hamsa web SDK and answer the tool by its name. See Embed on your website.
Web tool steps work on calls from your website or app. On a phone call there’s no web page to answer, so the step takes On Failure.

Add a Web tool step

1

Add the step

On the canvas, click Add node and choose Web tool (“Execute web-based tools”).
2

Pick the web tool

On the step’s card, click Select a web tool. In Choose a web tool (“The web tool this step runs.”), pick one. If you have none, the list shows “No web tools yet”.
The Choose a web tool dialog listing three web tools: read_cart, open_order_page and fill_return_formThe Choose a web tool dialog listing three web tools: read_cart, open_order_page and fill_return_form
3

Set its parameters

Open Tool configuration and decide where each parameter’s value comes from.
4

Save values from the reply

Paste an Example response, then add a Tool response variable for each value you need.
5

Connect both outcomes

Connect On Success and On Failure to their next steps.

Fields and sections

A Web tool step on the canvas with the read_cart web tool, and its panel open: Processing message, Transitions, Example response, Tool configuration, Variables and GlobalA Web tool step on the canvas with the read_cart web tool, and its panel open: Processing message, Transitions, Example response, Tool configuration, Variables and Global
Parameters filled by AI extraction work only when the call reaches the step through a Prompt transition. From a Router, a Tool step, a DTMF input or Auto transition, give each one a value, fixed or {{variable}}; the panel marks required ones Manual value required.

Paths for reply values

A web tool’s reply is used as it is. Write the JSON path with the reply’s own keys: for a reply {"cart": {"total": 120}}, the path cart.total saves 120.

Transitions

Both are created with the step and can’t be removed. You can also add Skip if to this step: when its conditions already hold as the call arrives, the call goes straight to its target and the step doesn’t run. See Skip if.

How it works on a call

  1. The step’s local variables are set.
  2. The processing message plays to the end, if there is one.
  3. The request goes to the caller’s page with the tool name and parameters. The step waits up to 15 seconds for the reply.
  4. On a JSON reply, your response variables are saved and the call takes On Success. Otherwise it takes On Failure.
The agent doesn’t speak the reply. To tell the caller what happened, connect the step to a Conversation step that uses the saved values.

Web tools

Create the tools your web page answers.

Embed on your website

Connect your page to the agent.

Tool step

Call an API from your servers instead.

Transitions

How the call moves between steps.