Functions

Functions define the behavior behind interactive widget elements like buttons and forms. You attach a function to an element by referencing its function name, and the function’s type determines what happens when a user triggers it.

Function Types

Each function type serves a different purpose. Select the type that matches the action you want to perform.

Server Function

Makes a request to an external API. The configuration is never visible to the end user.

Setting	Description
URL	The endpoint to send the request to. Supports template tokens.
Method	HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`.
Headers	Key-value pairs sent as request headers. Supports template tokens.
Parameters	Query parameters appended to the URL. Supports template tokens.
Body	Request body (for `POST`, `PUT`, `PATCH`). Supports template tokens.
Return Fields	Fields to extract from the response for use in follow-up actions.
On Start	Follow-up action that runs before the request is sent.
On Success	Follow-up action when the request succeeds.
On Failure	Follow-up action when the request fails.
Additional Inputs	Extra data passed in at the call site in the code. See Additional Inputs.

Upload File Function

Sends files from the visitor’s browser straight to your endpoint as multipart/form-data, one request per file. Chatbase never stores the files. Use it with the Dropzone and FileInput components, or attach it to a Button to open the visitor’s file picker. See the File Uploads guide for the endpoint contract and security practices.

Setting	Description
Endpoint	Your upload URL and method, `POST` or `PUT`. Must start with `https://` or `http://`. Supports template tokens.
File field	The multipart part name the file is sent under. Default `file`.
Target field	The variable that stores the file records when a `Button` or `Form` triggers the upload. Components use their own `name`.
Headers	Key-value pairs sent as request headers. Sent from the visitor’s browser, so values are visible to them. `Content-Type` is not allowed.
Query parameters	Query parameters appended to the URL. Supports template tokens.
Form fields	Extra multipart parts sent with every file. Supports template tokens.
Accepted types	Comma-separated extensions or MIME types, for example `.pdf, .png, image/`. Empty accepts any type.
Max size (MB)	Per-file size limit, up to 30 MB.
Allow multiple files	Whether the field can hold more than one file. When off, a new file replaces the previous one.
Max files	How many files the field can hold, up to 5.
URL field	Path in the JSON response that holds the uploaded file’s URL, for example `data.url`.
Return fields	Response fields to keep on each file record.
On start	Follow-up action that runs once per upload, before any file is sent. It does not run per file.
On success (per file)	Follow-up action that runs once for each uploaded file.
On failure (per file)	Follow-up action that runs once for each file that failed.
Additional Inputs	Extra data passed in at the call site in the code. See Additional Inputs.

Besides the widget’s variables, the endpoint, headers, query parameters and form fields can use {{conversationId}}, {{chatbotId}}, {{widgetId}}, and {{file.name}}, {{file.size}}, {{file.type}}.

Client Function

Sends a message to the parent webpage. This is designed for widgets embedded inside iframes that need to communicate with the host page.

Setting	Description
Wait for Response	Whether to wait for a response from the parent page (up to 60 seconds).
Inputs	Key-value pairs sent in to the client side code. Supports template tokens.
Return Fields	Fields to extract from the client side code’s response.
On Start	Follow-up action that runs before the message is posted to the parent page.
On Success	Follow-up action when the parent responds successfully.
On Failure	Follow-up action when the communication fails.
Additional Inputs	Extra data passed in at the call site in the code. See Additional Inputs.

Handling the function on your pageRegister a handler on your website with registerWidgetFunctions. The key must match the function’s name in the widget. The handler receives the function’s Inputs as one object and returns a result. Only Inputs reach the handler, so to pass an additional input, add an input that references it. This example assumes the function’s Inputs are classId set to {{classId}} and email set to {{email}}:

window.chatbase('registerWidgetFunctions', {
  bookClass: async ({ classId, email }) => {
    try {
      const response = await fetch('/api/bookings', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ classId, email })
      })

      if (!response.ok) {
        return { status: 'error', error: 'Booking failed' }
      }

      const booking = await response.json()
      return { status: 'success', data: { bookingId: booking.id } }
    } catch {
      return { status: 'error', error: 'Booking failed' }
    }
  }
})

The result must be one of these two shapes. Anything else is treated as an error.

Result	Shape
Success	`{ status: 'success', data: { ... } }`
Error	`{ status: 'error', error: 'message' }`

Each field in data can be used as a template token in the On Success follow-up. In the example above, a Set Variables follow-up can save {{bookingId}} to a widget variable.When Wait for Response is off, the widget doesn’t wait for the handler and runs On Success right away, so the handler’s return value is ignored:

window.chatbase('registerWidgetFunctions', {
  trackPlanSelected: ({ plan }) => {
    window.dataLayer?.push({ event: 'plan_selected', plan })
  }
})

Register every widget function in a single registerWidgetFunctions call. Calling it again replaces the functions registered earlier.
Return { status: 'error', error } instead of throwing. On the website widget, a handler that throws sends no response, so the widget waits the full 60 seconds before failing.
Only successful results expose data to follow-ups. On Failure cannot read fields from the handler’s response.

Using Center Stage? Register the same handlers with window.chatbaseCenterStage('registerWidgetFunctions', { ... }).

Send Message Function

Sends a message into the current conversation.

Setting	Description
Message Template	The message content. Use `{{fieldName}}` template tokens to insert dynamic values.
Hide Message	When enabled, the message is sent in the background and not displayed to the user.
On Execute	Follow-up action that runs after the message is sent.
Additional Inputs	Extra data passed in at the call site in the code. See Additional Inputs.

Link Function

Opens a URL in a new browser tab.

Setting	Description
URL	The URL to open. Supports template tokens.
On Execute	Follow-up action that runs after the link is opened.
Additional Inputs	Extra data passed in at the call site in the code. See Additional Inputs.

Dismiss Function

Closes the widget. There are two ways to use this:

Directly — Attach it to a button so the user can close the widget on click.
As a follow-up — Use it as the follow-up action on another function (e.g., close the widget after a successful API call).

Dismissal state is persisted. If a user dismisses a widget, it stays dismissed even after a page refresh.

Set Variables Function

Updates widget data values without making any external calls. Useful for storing user selections or transforming data between steps.

Setting	Description
Variables	Key-value pairs to set. Values support template tokens.
Additional Inputs	Extra data passed in at the call site in the code. See Additional Inputs.

Loading Behavior

When a function runs, you can control how the UI indicates progress.

Value	Behavior
None	No loading indicator is shown.
Self	The triggering element displays a spinner.
Container	The entire widget shows a loading overlay.

Additional Inputs

Sometimes a function needs extra context that depends on where it is called. For example, you might have a list of classes, each with a “Book” button that should pass a different classId to the same function.

{classes.map((item) => (
  <Button
    label={item.name}
    onClickAction={{ functionName: "bookClass", additionalInputs: { classId: item.id } }}
  />
))}

Once provided, you can reference additional inputs as template tokens anywhere the function accepts them — in the URL, headers, body, or parameters. For the example above, use {{classId}} to insert the value.

Additional inputs are not variables. They only exist for the duration of the function execution. If you need to persist a value, use a Set Variables action in On Start or in a follow-up that runs after the function.

After a Function Runs

Every function supports a follow-up action that runs after it completes. Some functions can also run one before it starts.

Server Function and Client Function provide three follow-up slots: On Start, On Success, and On Failure.
Upload File Function provides the same three slots. On start runs once per upload, before any file is sent. On success and On failure run once for every file, and in them {{file.url}}, {{file.name}}, {{file.error}} and any Return field are available as template tokens.
Send Message, Link, Dismiss, and Set Variables functions provide a single On Execute slot.

Each follow-up action can do one of the following:

Action	Description
Dismiss	Closes the widget. The dismissal is persisted across page refreshes.
Set Variables	Updates widget data values. For server and client function follow-ups, you can reference response data using template tokens.

On Start runs before the call is made. The variables it sets are applied to the widget right away, so a state like Loading shows while the request is in flight, and they are already available as template tokens in that same request. If On Start dismisses the widget, the function still runs. Values set by any follow-up are saved with the conversation, so they survive a page reload. A common pattern is a status variable that drives states:

Slot	Set Variables
On Start	`fetchStatus` to `loading`
On Success	`fetchStatus` to `loaded`
On Failure	`fetchStatus` to `error`

Then add Loading, Loaded, and Error states whose conditions check fetchStatus equal to loading, loaded, or error.

Reset any value On Start sets in both On Success and On Failure. Otherwise a failed call can leave the widget stuck on its loading view.

Template Tokens

Template tokens are placeholders written as {{fieldName}} that get replaced with current values at runtime. You can use them in any setting that supports dynamic content, including URLs, headers, body content, messages, and variables. In a Server function body, a token inside quotes, such as "{{message}}", is escaped automatically when its value would break the JSON, for example a quote or a line break a visitor typed into a form.

For follow-up actions on Server and Client functions, template tokens can also reference fields from the response data. This lets you capture API results and store them as widget variables for use elsewhere.

Results

Every function produces one of two outcomes:

Outcome	Description
Success	The function completed. For server and client functions, the result may include response data that can be referenced in follow-up actions via template tokens.
Error	The function failed. The result includes an error message describing what went wrong.

Getting Started

Website Integration

Advanced Integration

Widgets

Function Types

Loading Behavior

Additional Inputs

After a Function Runs

Template Tokens

Results

​Function Types

​Loading Behavior

​Additional Inputs

​After a Function Runs

​Template Tokens

​Results

Function Types

Loading Behavior

Additional Inputs

After a Function Runs

Template Tokens

Results