Functions and states

Widget functions respond to visitor selections, and states control which sections appear. Reference function settings, placeholders, saved variables, and condition operators.

A function is a named behavior that runs when a visitor selects a button or list item. A state is a named section that appears when its visibility rules allow it. Configure both in the widget builder.

Function types

In Functions, select Add your first function, or Add function when functions already exist. Each function needs a unique Function name and a Function type. Names match ^[A-Za-z_][A-Za-z0-9_]{0,63}$, such as pickProduct.

Functions do not run while the conversation is busy.

Call API

Call API functions send HTTP requests from Chatvox to your backend through a saved API connection when a visitor selects a button or list item. They cost no credits and do not invoke an LLM. Only one Call API function can run at a time per reply widget.

Configuration

A Call API function includes:

• Function name: unique identifier matching ^[A-Za-z_][A-Za-z0-9_]{0,63}$.
• Additional inputs: up to 10 keys passed when the button is clicked (such as slot).
• API connection: choose a saved connection for this agent, or create one from the function editor. It supplies the base URL, authentication, and headers.
• Method: GET, POST, PUT, PATCH, or DELETE.
• Path and query: the endpoint path, such as /bookings/{{order_id}}. The request uses the connection’s base URL. The base URL and final request must use HTTPS and reach a public address.
• Send fields as: JSON body or Query params. GET requests always send declared inputs as query parameters.
• JSON body (optional): a JSON template for methods other than GET. Use placeholders such as {{appointmentSlot}} to include widget data or input values. When you set a template, it defines the JSON body; Chatvox does not add declared inputs to it automatically. If Send fields as is Query params, declared inputs still go in the URL when you set a JSON body.
• Return schema: up to 20 return fields mapping a field key to a dot path in the JSON response (for example, bookingRef ← data.reference).
• Success path (optional): dot path in the JSON response that must contain a value Chatvox parses as true, such as true, 1, or "yes", for the call to count as a success. If omitted, any 2xx HTTP response status is considered successful.
• Timeout (seconds): request timeout from 1 to 15 seconds (default 8 seconds).
• Loading: visual feedback while the request runs:
  • None: buttons are disabled only.
  • Button: the clicked Button or ListViewItem shows an inline spinner.
  • Whole widget: a semi-transparent overlay with a spinner covers the card.

Tokens and precedence

The path, connection header values, and request body support double-brace tokens such as {{date}}. Values resolve with the following precedence (highest precedence wins):

1. Built-ins: conversation.id, contact.* (verified contact details), page.url, and utm.*. These values come from the conversation; contact values are available for verified contacts.
2. Declared inputs: values passed in additionalInputs matching declared input keys.
3. Variables: current visitor widget variables (including values from form inputs).
4. Data: the widget’s initial reply data from message metadata.

Tokens in the path are URL-encoded. JSON body templates are decoded and re-encoded, preserving a value’s type when it consists of one placeholder.

Follow-ups

Call API functions use lifecycle follow-ups instead of a single After it runs setting:

• On start: runs locally as soon as the visitor clicks (None, Dismiss widget, or Set variables).
• On success: runs when the request returns a 2xx status and, if defined, its Success path parses as true. Values in Set variables can read returned fields, such as {{bookingRef}}.
• On failure: runs when the request fails, times out, or returns a non-success response (None, Dismiss widget, or Set variables). If On failure is set to None, an inline alert displays: Couldn’t complete that. Try again.

State changes are saved to the server in a single save after the request settles. If a visitor reloads during an in-flight request, the card restores to its pre-click state.

Testing in the builder

The widget builder provides two tools for Call API functions. Both send a real request to your API:

• Run: in the function editor, enter test values for declared inputs and select Run. Chatvox sends a test request and displays the status badge, response time, extracted return fields, and raw JSON response.
• Populate from API: select Populate from API to run the request and inspect leaf paths in the JSON response. Selecting paths adds them directly to your return schema without typing.
• Preview result toggle: in the preview pane, use the Call API result: Success | Failure toggle to simulate both success and failure flows without calling your backend.

Follow-ups for other functions

After it runs chooses one follow-up:

For example, a Send message function with Message set to I choose {{productName}} and After it runs set to Dismiss widget sends the selection and hides the card. An invalid link or empty message stops before its follow-up. Follow-ups cannot call another named function.

Follow-up placeholders use the original click scope. They do not read variables newly assigned by the main function during that same click.

Call a function from code

Use onClickAction on a Button or ListViewItem. Its functionName must be a literal string naming a function you defined. additionalInputs is an optional object of values for that click.

<Card>
  <Button
    label="Choose this product"
    onClickAction={{
      functionName: "pickProduct",
      additionalInputs: { productName: product.name },
    }}
  />
</Card>

Declare product.name as a widget field. Define pickProduct in Functions, for example as Send message with Message set to I choose {{productName}}.

In a loop, additional inputs can read the current item:

<Card>
  <ListView>
    {products.map((product) => (
      <ListViewItem
        onClickAction={{
          functionName: "pickProduct",
          additionalInputs: { productName: product.name },
        }}
      >
        <Text value={product.name} />
      </ListViewItem>
    ))}
  </ListView>
</Card>

Declare products as a List field with visitor-safe items. Click inputs are not saved automatically. Use Set variables to retain a selected value.

Placeholders

Open link URLs, messages, and Set variables values support double-brace placeholders such as {{order.number}}. These templates are separate from JSX expressions such as {order.number} in code.

Variables override widget data with the same key. Loop parameters override matching keys inside their loop. Additional inputs override matching keys for the function call.

Paths contain letters, digits, underscores, and dots. Use {{products.0.name}} for a numeric segment. Bracket notation such as {{products[0].name}} is not supported in placeholders. Prototype-related path segments are blocked. Open link, message, and Set variables placeholders read widget data, saved variables, loop values, and click inputs. Call API functions can also use the built-in conversation values listed above; they do not expose API credentials to the widget.

In Open link URLs and messages, values become text. Missing or null values become empty text. Open link values are not URL-encoded, so use data that is safe for the destination URL. For example, with {"order":{"number":"A-1234"}}, Order {{order.number}} becomes Order A-1234.

Set variables rules

A value containing only one placeholder preserves its underlying type. For example, {{quantity}} preserves a numeric quantity, while Quantity: {{quantity}} produces text. Entering true directly in the value input produces the text "true", not a boolean. A null template assigns null; a missing single-placeholder value leaves the variable unchanged.

Assignments use the original click values. An earlier assignment does not feed a later assignment in the same call.

Variables and dismissal are saved with the widget on its specific reply and restored when the conversation reloads. They do not change another reply’s card or the widget definition. Sent messages remain visitor messages. The reply retains its original widget definition and data after action or widget edits.

State tags

In States, select Add your first state, or Add state when states already exist. Each State name must be unique and match ^[A-Z][A-Za-z0-9]{0,39}$. Use a distinct name such as Picked, then wrap components in a tag with that exact name. State tags have no props.

<Card>
  <Picked>
    <Text value="You have selected a product." />
  </Picked>
</Card>

Conditions read widget data and variables by dot path, such as order.status or pickedName. Variables override data fields with the same key. Inside loops, states can also read the current item’s scope.

Condition operators

Under Show when, enter a Condition field, select a Condition operator, and enter a comparison value when needed. Comparison values are text. Matches are case-sensitive.

Numeric conversion follows JavaScript Number: empty text and null become zero, booleans become zero or one, and missing or nonnumeric text becomes NaN. Comparisons involving NaN are false. Contains with empty expected text matches every text value.

For example, order.status Equals Shipped matches "Shipped" but not "shipped". tags Contains sale matches ["sale", "new"], but not ["wholesale"].

Conditions and groups

And requires both the result so far and the next condition to match. Or requires either to match. Conditions combine left to right, without normal expression precedence. Groups evaluate separately, then their results also combine left to right. The first condition and first group do not need a connector.

For example, A Or B And C means (A Or B) And C. To express A Or (B And C), put A in one group and B And C in a second group. Use Or as the second group’s connector.

Combined example: show a picked state

Declare product.name as a Text field and use this default data:

{
  "product": { "name": "Canvas bag" }
}

Configure the function:

Configure the state:

Use this code:

<Card>
  <Title value={product.name} />
  <Button
    label="Choose product"
    onClickAction={{
      functionName: "pickProduct",
      additionalInputs: { productName: product.name },
    }}
  />
  <Picked>
    <Text value={`You picked ${pickedName}`} />
  </Picked>
</Card>

Before selection, pickedName is missing and Picked stays hidden. Selecting Choose product saves Canvas bag to pickedName, so the state appears. The selection survives a conversation reload. In the builder preview, Reset clears it.

Walkthrough: Book an appointment without a second action

This walkthrough converts the Appointment slots template from sending a chat message to booking directly through an API using a Call API function.

{
  "date": "Monday, October 19",
  "slots": [
    { "label": "9:30 AM" },
    { "label": "11:00 AM" },
    { "label": "1:30 PM" },
    { "label": "3:00 PM" }
  ],
  "picked": "",
  "status": "",
  "bookingRef": ""
}

{
  "date": "{{date}}",
  "time": "{{picked}}",
  "conversation_id": "{{conversation.id}}",
  "customer_email": "{{contact.email}}"
}

<Card size="md" status={{ text: "Book a call", icon: "calendar" }}>
  <Col gap={1}>
    <Title value="Pick a time" size="md" />
    <Caption value={date} />
  </Col>
  <Row gap={2} justify="between" wrap={true}>
    {slots.map((slot) => (
      <Col width="48%">
        <Button
          label={slot.label}
          variant={picked === slot.label ? "solid" : "outline"}
          size="md"
          block={true}
          iconStart={picked === slot.label ? "check" : ""}
          onClickAction={{ functionName: "pickSlot", additionalInputs: { slot: slot.label } }}
        />
      </Col>
    ))}
  </Row>
  <Picked>
    <Divider />
    <Row gap={2} align="center">
      <Icon name="check-circle" color="success" />
      <Text value={`${date} at ${picked}`} weight="medium" />
    </Row>
    <Button
      label="Confirm booking"
      variant="solid"
      size="md"
      block={true}
      iconStart="calendar"
      onClickAction={{ functionName: "bookSlot" }}
    />
  </Picked>
  <Booked>
    <Divider />
    <Box border={true} radius="lg" padding={3} gap={2} align="center">
      <Icon name="check-circle" color="success" size={24} />
      <Text value={`Booked for ${date} at ${picked}`} weight="semibold" />
      <Caption value={`Reference: ${bookingRef}`} />
    </Box>
  </Booked>
  <BookingFailed>
    <Divider />
    <Box border="error" radius="lg" padding={3} gap={1} align="center">
      <Icon name="triangle-alert" color="error" />
      <Text value="Could not complete booking. Please try another time." />
    </Box>
  </BookingFailed>
</Card>