> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatref.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Button Actions

> Give your bot a one-tap button it can show in the chat, then record the click and call your webhook.

A button action gives your bot a single, clear button it can show in the chat –
like a "Start my return" button for an online coffee store. The AI decides when
to show it; when the visitor clicks, Chatref records the click and calls a
webhook you choose.

## What you configure

* **Button Label** – the text on the button, e.g. "Start my return".
* **URL** (optional) – an external link to open when clicked, e.g. your returns
  page.
* **Style** – the button's look (its variant), so it fits the moment.
* **Confirmation Message** (optional) – a short "Are you sure?" prompt shown
  before the action runs. Leave it empty for no confirmation.
* **Payload** (optional) – extra data sent with the click, so your webhook knows
  the context.

## Create a button action

<Steps>
  <Step title="Open the Actions tab">
    In your agent's dashboard, go to the **Actions** tab and create a new action.
  </Step>

  <Step title="Choose Button">
    Pick **Button** as the action type.
  </Step>

  <Step title="Name it and describe when to use it">
    Name the action, like "Start a return", and write a description that tells the
    AI when to show it – for example, "Use this when a visitor wants to return an
    order."
  </Step>

  <Step title="Set up the button">
    Enter the **Button Label** and pick a **Style**. Optionally add a **URL** to
    open, a **Confirmation Message**, and a **Payload**.
  </Step>

  <Step title="Add your webhook">
    Enter the **Webhook URL** the click should call, plus any **Headers** your
    endpoint needs.
  </Step>

  <Step title="Save">
    Save the action. Your bot can now show this button when the chat matches your
    description.
  </Step>
</Steps>

## What happens on click

When a visitor clicks the button, Chatref records the click as a submission and
calls your webhook (sending the payload, if you set one). If you added a URL, it
also opens that link in a new tab.

<Tip>
  Keep labels short and action-led – 2 to 4 words like "Start my return" or "View
  plans". Have the bot explain the choice in its message, then show one clear
  button rather than several at once.
</Tip>

## Seeing clicks

Every click is saved in the **Action Submissions** table – see
[Custom Actions](/custom-actions/overview) for how to read it.

## Next steps

<CardGroup cols={2}>
  <Card title="Custom Actions" icon="bolt" href="/custom-actions/overview">
    How actions work and the three types.
  </Card>

  <Card title="Form action" icon="rectangle-list" href="/custom-actions/form-actions">
    Collect several details instead of one click.
  </Card>

  <Card title="API / Webhook action" icon="webhook" href="/custom-actions/api-webhook-actions">
    Let the bot call your API directly.
  </Card>

  <Card title="Inbox" icon="inbox" href="/inbox/conversations">
    Read the chats where the button was shown.
  </Card>
</CardGroup>