⚡️ Widget functions

A function is what runs when the visitor interacts with the widget. Functions are declared on the editor's Functions tab and called from elements by functionName.

Important distinction: agent functions (Builder → Functions) render a widget; widget functions are triggered by the user.

🧰 The five types

1. call_api

Sends a request to your endpoint.

• url, method (GET … DELETE), headers, inputs.
• waitForResponse — wait for the response and merge it into the data.

2. set_variables

Updates the widget data with no external call. The simplest way to switch states: { "booked": true }.

3. send_message

Posts a message into the conversation. message supports {{token}}.

4. open_link

Opens url in a new tab; the URL supports tokens too.

5. dismiss

Closes the widget. The dismissal is remembered — a page reload does not bring it back.

🔑 Tokens

Any text field of a function (url, headers, inputs, message) may contain {{path}}. It resolves against the widget data overlaid with the additional inputs:

url:    https://api.example.com/orders/{{orderId}}
inputs: { "note": "{{note}}", "total": "{{order.total}}" }

➕ Additional inputs

These are values that exist only during the call — they are not variables. You declare the names on the function and supply the values at the call site:

function: track_order → additional inputs: orderId, note

<Button label="Track"
  onClickAction={{ functionName: 'track_order',
                   additionalInputs: { orderId: "{{order.id}}" } }} />

Security rule: the server accepts declared names only. For a form value to reach your API its field name must be in that list, otherwise it arrives empty. The editor flags tokens it cannot resolve from either the data or the declared inputs.

⏳ Loading behaviour

• none — no indicator.
• self — spinner on the element that was clicked.
• container — an overlay on the whole widget.

🔁 Follow-ups

Every function can run one more action when it finishes:

• call_api has onSuccess and onFailure.
• the others have a single after-execute action.
• A follow-up is either set_variables or dismiss.

call_api: confirm_booking
  onSuccess → set_variables { booked: true }
  onFailure → set_variables { error: "Booking failed" }

🔐 call_api security

• When a widget is delivered to a chat, its url, headers and inputs are stripped — the browser never sees them.
• The browser posts only the function name and the declared inputs; the server performs the call.
• That is why putting API keys in the headers is safe.

🪜 Multi-step widgets

For the server, the authoritative data is the state the widget was first rendered with. set_variables and onSuccess change the browser's copy only. So a value collected in an earlier step must be carried into the next call as an additional input.

🧱 What the Functions tab looks like

Each function is a collapsible row showing its name and a one-line summary (its type). Expanded, the fields stack full width, repeated values (variables, API inputs) appear as a small table with a header row, and a delete button sits at the bottom of the row.