JavaScript API
Open the widget, start and end a call, give the call context, hear what happens, and let the character use tools on your page.
The widget has one global, TalkWidget. Use its methods (TalkWidget.open()), or call it with a command name (TalkWidget('open')); both do the same.
Call it before it loads
The tag is async, so your code may run before the widget has arrived. Add this stub first, above the tag, and calls made early are queued and run once it loads (use the command form until then):
<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>Methods
| Method | Command | What it does |
|---|---|---|
open(), close(), toggle() | TalkWidget('open')… | Opens or closes the panel. Closing it ends a call |
start({ character, language, name, context }) | TalkWidget('start', {…}) | Opens the panel and starts the call at once, without the step before it (below) |
end() | TalkWidget('end') | Ends the call; the panel stays open |
show(), hide() | TalkWidget('show')… | Shows or hides the whole widget. Hiding closes the panel, which ends a call |
update(changes) | TalkWidget('update', {…}) | Changes the widget for this page (below) |
on(event, fn), off(event, fn) | TalkWidget('on', event, fn) | Listens to an event, or stops |
register_tool(name, fn) | TalkWidget('register_tool', name, fn) | Your page's code for one of the character's tools on your page |
TalkWidget('combine', {…}) | Puts your own chat in our launcher's chooser (Attributes) |
Start a call
start() opens the panel and calls straight away, for your own "Talk to us" flow. Everything is optional:
| Option | What |
|---|---|
character | One of the deployment's characters, by id (chr_…); else the tag's data-character, else its own |
language | The call's language (fa, de…): one the deployment offers; else the visitor's last pick, the page's, the character's |
name | The visitor's first name, for the greeting (at most 40 characters) |
context | What the character should know about this visit (below) |
The browser asks the visitor for the microphone the first time, as it does when they press Call. If a call is already running, start() leaves it alone. The panel still says, before anything else, that the character is an AI.
Context from your page
TalkWidget.update({ context: "Looking at: Oak dining table, 180 cm. Cart: 2 items." });context (in start() or update()) reaches the character before it greets the visitor. It comes from the visitor's browser, which they can change, so it is treated as information that may be wrong, never as instructions: at most 1,000 characters on one line, and the character is told it's from the page. Put what helps (the product they're looking at, their cart, their plan), and never anything the character must obey or keep secret. For context you trust, start the call from your server.
Events
| Event | When | Detail |
|---|---|---|
ready | The widget is drawn. A listener added later still hears it | |
open | The panel opened | |
close | The panel closed | |
call_started | The call is live | |
call_ended | The call ended | { reason, message }: person_left (the visitor's End), closed (the panel closed), ended (your end(), or your server), time_limit, silence, unavailable (the character couldn't join), error, failed (the connection dropped); message is our sentence |
transcript | A turn is over | { who: "person" | "ai", text, turn, interrupted }, one per final turn, and only while you listen for it |
unavailable | A call can't happen | { cause }: busy (the deployment's limits, or ours), visitor_limit (this visitor's calls for today), not_allowed (the key is wrong or revoked, or this site isn't one of the deployment's), offline |
error | Something went wrong for your code to know | { code, message }: mic_blocked, mic_missing, mic_busy, unsupported, start_failed, or for a tool tool_no_handler, tool_timeout, tool_failed, tool_too_large (with tool) |
call_start and call_end (the first names) still work. A handler that throws never stops the others, nor the widget.
Example: your button, the end of a call, a tool for the cart
<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_…" data-launcher="none"></script>
<button id="talk" type="button">Talk to Sara</button>
<script>
// showMessage and myCart stand for your own code.
// Open the call from your own button, with what the character should know.
document.querySelector("#talk").addEventListener("click", () => {
TalkWidget("start", { context: "Looking at: " + document.title });
});
// After the call: thank them, or offer another way.
TalkWidget("on", "call_ended", ({ reason }) => {
if (reason === "time_limit") showMessage("Want to keep going? Book a longer call.");
});
TalkWidget("on", "unavailable", ({ cause }) => {
if (cause === "busy") showMessage("Sara is busy right now. Try again in a few minutes.");
});
// A tool on your page: the character adds to the cart while you talk.
TalkWidget("register_tool", "add_to_cart", async ({ sku, quantity }) => {
const item = await myCart.add(sku, quantity ?? 1);
return { added: item.name, cart_count: myCart.count() };
});
</script>add_to_cart is a tool you make in the dashboard with Runs on: your website's page and give to the character (Tools on your page).
Changing it on one page
update takes any of these, and wins over the tag's attributes and the deployment's appearance:
TalkWidget("update", {
language: "fa",
theme: "dark",
position: "bottom-left",
offsetX: 24,
offsetY: 24,
launcher: "pill",
mobileLauncher: "icon",
label: "Ask Sophie",
title: "Sophie",
subtitle: "An AI assistant",
teaser: ["Questions about pricing? Ask me."],
teaserDelay: 10,
colors: { accent: "#1f5553", on_accent: "#f7f8fa", ink: "#15171c", paper: "#f4f5f7" },
context: "Plan: Pro. Looking at: invoices.",
});teaseris a string, a list of strings, orfalsefor none.colorsare{ accent, on_accent, ink, paper }for the theme in use, as#rrggbb.contextis for the next call (above).- The deployment's page rules (where the widget and the teaser show) are checked again at once.
How it hears about the call
The call runs in our own page, inside the panel's iframe. That page and the widget talk with postMessage, checked both ways: the widget takes messages only from the frame's own window at our origin, and our page takes them only from its parent window at your site's origin, and sends only to that exact origin, never to *. Your site's origin must be one of the deployment's sites: our page uses it for your tools and the transcript only after the call has started there. You don't need to listen to these messages yourself; the events above are the API.
Attributes
The tag's data attributes: corner, launcher, theme, colours, language, teaser and panel, for one site without changing the deployment.
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.