Made in 10Docs
GuidesAPI
Website widget

Tools on your page

Let the character act on your website during a call in the bubble, like adding to the cart or opening a product, with your page's own code.

Most tools are your server's HTTPS endpoints. A tool can instead run on your website's page: during a call in the bubble there, when the character decides to use it, your page's own code does the work (add to the cart, open a product, fill in a form) and tells the character how it went. No server, no address, no secret.

1. Make the tool

In the dashboard, Connectors & tools, New tool, then Runs on: your website's page. Or through the API, with runs_on: "page" and no url:

curl https://talk.madein10.com/v1/tools \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "add_to_cart",
    "runs_on": "page",
    "description": "Adds a product to the visitor'\''s cart. Use it when they say they want to buy something.",
    "parameters": { "type": "object", "properties": { "sku": { "type": "string" }, "quantity": { "type": "integer" } }, "required": ["sku"] },
    "filler": "Adding it now."
  }'

Then give it to the character, as any tool. Where a tool runs is chosen when you make it; it never changes.

2. Answer it on your page

Every page with the bubble
<script>window.TalkWidget=window.TalkWidget||function(){(TalkWidget.q=TalkWidget.q||[]).push(arguments)}</script>
<script async src="https://talk.madein10.com/widget.js" data-key="pk_live_…"></script>
<script>
  TalkWidget("register_tool", "add_to_cart", async ({ sku, quantity }) => {
    const item = await myCart.add(sku, quantity ?? 1); // your own code
    return { added: item.name, cart_count: myCart.count() };
  });
</script>

Your function gets what the character filled in (the tool's parameters) and returns what the character should know: anything JSON can hold, at most 4 KB. Return nothing and the character hears it was done. TalkWidget.register_tool(name, null) takes it away again.

What the character hears

Your pageThe character hears
Answers in timeYour answer, as data from the page
Has no function for itThat it isn't available on this page, and carries on without it
Doesn't answer in time (the tool's time limit, 10 seconds unless you set it)The same
Throws, or answers more than 4 KBThat it didn't work just now, so it can say so

Your page also hears the misses as an error event (tool_no_handler, tool_timeout, tool_failed, tool_too_large, with the tool's name), so you can find them while you build. Every use is in the call's log in the dashboard, with how long it took; never the arguments or the answer.

Where it works

  • In the bubble on your sites: the deployment's sites only. Our call page checks the site when the call starts, and sends each tool call only to that exact origin.
  • Not on a share page, an API call, a meeting or the dashboard's test talk. Those have no page of yours: the share page answers "not available on this page", and the others never offer the tool to the character at all.
  • On stacks where we run the turns (hearing, mind, voice), as for every tool.

Keep it safe

Whatever runs on a page runs in the visitor's browser, which they control. So:

  • Treat the arguments as the visitor's input. The character fills them in from what the visitor said; check them as you would a form.
  • Don't trust the answer on your server. A page tool is for the page: the cart, the view, the form. For anything that charges, books or reads private data, use a tool on your server, which we sign.
  • The answer is data, not instructions. We tell the character so, and cut anything over 4 KB, but don't put text there you wouldn't want read out.

On this page