Custom actions

An action is an HTTP endpoint of yours that the assistant may call while it is talking to a visitor: check availability, look up an order, apply a discount, book a slot, hand off to a person. The model decides when to call it, from the description you write; you decide what it is allowed to send.

Workspace → Actions.

Anatomy

Part	What it is
Slug	The name the model sees. Verb-shaped, e.g. check_stock.
Description	When to use it, and when not to. The model reads only this.
Parameters	The arguments the model fills in.
Fixed values	Server-set values merged over whatever the model produced.
Endpoint	URL, headers, timeout, retries.
Auth	None, bearer token, custom header — plus optional HMAC signing.
Context	What of the conversation travels with the call.
Limits	Per conversation, per visitor per day, per agent per day, cooldown.
Result	Which response fields the model may see, and how to present them.

An action belongs to the workspace and can be scoped to one agent or left available to all of them.

Parameters

Each parameter has a name, a type, a description and a required flag.

• string — optionally constrained by an anchored regular expression and a maximum length
• number, boolean
• enum — one of a fixed list of values
• product — resolved against the agent’s product catalog, optionally restricted to a subset of it, so an action can cover three products without covering the fourth

The description is not documentation, it is instruction. “The order number, which the visitor must give you — never guess it” produces very different behaviour from “order number”.

Validate on your side anyway

Types, patterns and enums are enforced before the call goes out, and fixed values overwrite anything the model put in the same key. That is a real boundary, but it is not your only one: the arguments still originate from a language model reading a stranger’s message. Treat the request like any other untrusted input.

What the call carries

Everything is off by default except the transcript, which is the reason the feature exists. You can additionally send: a one-paragraph summary of the conversation, the captured lead, the page the visitor is on, coarse visitor context (country, city, language, device — never the raw IP), the conversation id and its admin link, the agent’s identity, and the list of files the visitor uploaded.

Send the least that makes your endpoint work. Every field you enable is a field that leaves the platform on every call.

Authentication

Three modes — none, Authorization: Bearer <token>, or a header name of your choosing carrying the token.

Independently of the mode, setting a signing secret adds an HMAC over the request body. Verify it and you know the call came from Engadin and was not altered, which matters more than the token when the endpoint does something irreversible.

Retries reuse the same delivery id, so your endpoint can be idempotent on it.

Limits

Four dials, and all of them should be set on anything that costs money or changes state:

• per conversation — successful runs one visitor may cause
• per visitor per day
• per agent per day — the circuit breaker
• cooldown — minimum seconds between runs

Zero means unlimited. Unlimited is the wrong answer for an action that issues a discount code.

What comes back

Your response is not shown to the visitor raw. You map the fields the model is allowed to see, by dotted path, each with a label — so a response with forty keys becomes three facts, and internal identifiers stay internal.

The instruction tells the model how to present them. The optional card renders a structured result under the reply in the widget, with one field marked copyable — which is what you want for a booking reference or a code.

Watching them run

Every run is logged with its arguments, outcome and duration. The log is on the action itself, on the conversation that triggered it, and available to your own tooling as list_action_runs over MCP.

Actions work identically for REST API callers — an n8n workflow talking to an agent gets the same capabilities as a visitor, minus the widget’s result card.