Tools and events in the panel: your own API

A tool lets the assistant ask your own system a question while it answers — your catalogue, your plan grid, an order’s status — and answer from what comes back. An event lets it show the result in your own page’s interface: a product grid, a plans window, a modal. Both are set up on the Tools screen of a site, and both are part of the Growth plan and above.

The endpoint itself is your developer’s part. What it should return, and how this site’s own plan grid and shop are built, is in the developer’s worked example.

The screen

Tools & events has two lists: Custom tools and Custom events, each with its New tool or New event button. A row shows the name, and a tool that sends an event carries the badge emits event; the event it sends carries auto-emitted. A click on a row opens its form; its menu has Edit, Enable or Disable, and Delete; and its Test (a tool) or Simulate (an event) button opens the panel beside the lists, where you try it without leaving the screen.

A tool

The form is in the order you fill it. Save at the top stores it.

Basics

• Display name — what you see in the panel.
• Name — what the assistant sees: letters, digits, - and _, unique on the site (plan_grid, order_status).
• Enabled — a disabled tool is kept but not used.
• Agent scope — one agent of the site, or All agents.
• When to use it — the situations in which the assistant should call it, in plain words. This is what it reads to decide, so write it the way a visitor asks: «any question about plans, prices or which plan suits them; never answer prices from memory».

Request

• Method — GET to read, POST to send.
• URL — your endpoint’s https address.
• Headers and Query params — fixed values sent with every call, such as Authorization: Bearer {{secret.api_token}}.
• Body template (JSON) — for a POST, the body to send.
• Timeout — in milliseconds, 5000 unless you change it, 10 seconds at most.

Parameters — what the assistant fills in from the conversation. Each has a Name, a Type (string, number, integer, boolean, array), Required, a Location (query, body, path, header) and a Description — one line telling the assistant what to put there. Mark a search term Required, so every call is a search; leave filters optional, so the assistant uses only those the visitor’s question gives.

Secrets — your API’s tokens, stored encrypted. Save the tool first, then add a Name and a Value and press Add; Copy placeholder gives you {{secret.name}} to paste into a header. A secret saves the moment you add it, and its value is never shown again.

Response

• What the response means — every field your endpoint returns, in a sentence each, with its unit: «price_usd is US dollars a month». The assistant reads this before the data.
• Response path — where the list is in the response, written with dots (plans, data.items). The assistant then sees only that part.
• Under Advanced: Cache answers (rarely-changing data) — leave it off for live data — and Language: if your endpoint takes a language, list the Languages the API supports and the Language param: every call then carries the visitor’s language when your API speaks it, and your site’s main language when it does not.

Availability — Every screen, or Only screens that name it with the Screens where it is available. A tool on every screen is offered on every message; keep those few and tie the rest to the pages where they make sense.

Emits event — pick an event, and every time the tool returns something, that event is sent to your page with the whole result. The assistant no longer sends that event itself.

An event

Basics — Display name, Name (your page listens for it), Enabled, Agent scope, and When to emit it.

Payload fields — what the event carries. For a list of results, one field of type array.

Behaviour

• Don’t suggest opening a page — your page shows the result itself, so the assistant does not also offer to take the visitor somewhere.
• Reply briefly instead of in full — the assistant says it found the answer and your page shows it. For a product grid: yes. For «which plan is the cheapest?», where the visitor wants a sentence: no.
• Ask for consent first — the assistant asks before the event fires, and sends it on the visitor’s yes.

Availability, as for a tool. Binding lists the tools that send this event.

Test and Simulate

Test runs a saved tool for real: fill the Example params and press Run to see your endpoint’s answer and, with Emits event, what the event Would emit. A test always calls your endpoint, so it shows what your system answers right now.

Simulate fires an event with Example values and shows the Action a host receives and a Host listener snippet to copy for your developer.

Your plan

Tools and events run on Growth, Pro and Business. On another plan the screen says your plan does not include them, New tool and New event wait for a plan that does, and tools you already made are kept, marked Not on your plan, ready for when you change plan.

Tools on other screens

The same tools are picked elsewhere in the panel:

• Agent → Escalation → Send each request to your system — a POST tool that receives every contact a visitor leaves. Agent.
• A source’s For applications → Tools available on this screen and Proactive analysis — tools tied to a screen of your app, and a check the assistant runs there by itself. Sources.