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
<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 page | The character hears |
|---|---|
| Answers in time | Your answer, as data from the page |
| Has no function for it | That 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 KB | That 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.