> ## 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.

# API / Webhook Actions

> Let your bot call your own API mid-chat – no visitor form – and use the response to keep answering.

Use this when your bot needs a live answer from your own system mid-chat – an
order status, a price, a stock count.

An API / Webhook action lets your bot call your own API in the middle of a
conversation. There's no form for the visitor to fill in. The bot gathers what
it needs from the chat, calls your endpoint, and uses the response to keep
answering. A travel agency could check live prices this way. An online coffee
store could add a "Check order status" action that looks up an order by its
number.

## How it works

1. The visitor asks something your bot can't answer from its training alone –
   like "Where's order 4172?".
2. The AI fills in the request from the chat (here, the order number) and calls
   your endpoint.
3. Your API replies with the data.
4. Chatref feeds that reply back to the bot, which uses it to finish its answer –
   "Order 4172 shipped yesterday and arrives Friday."

## What you configure

* **Method** – the HTTP method, defaulting to **POST**. You can also pick GET,
  PUT, PATCH, or DELETE.
* **URL** – your API endpoint.
* **Request Body Fields** – the inputs the AI fills from the chat. Each field has
  a **Field Name**, a type, whether it's **Required**, and a **Description** that
  tells the AI what to put there. These become the inputs the bot supplies when
  it calls your API.
* **Headers** – extra header keys and values. Put auth tokens here.

<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 API / Webhook">
    Pick **API / Webhook** as the action type.
  </Step>

  <Step title="Name it and describe when to use it">
    Name the action, like "Check order status", and write a description that tells
    the AI when to call it – for example, "Use this to look up an order by its
    order number."
  </Step>

  <Step title="Set the method and URL">
    Choose the **Method** (default **POST**) and enter your endpoint **URL**.
  </Step>

  <Step title="Add request body fields">
    Click **Add Field** for each input the AI should send – for an order lookup,
    one field named `orderNumber`. Add a **Description** for each so the AI knows
    what value to fill in.
  </Step>

  <Step title="Add headers and save">
    Click **Add Header** for any auth tokens or content type your endpoint needs,
    then save. Your bot can now call your API whenever the chat matches your
    description.
  </Step>
</Steps>

<Warning>
  Secure your endpoint. The bot can call it with values it gathered from a public
  chat, so your API should validate every request and only return data that's safe
  to share. Keep secrets – API keys, tokens – in **Headers**, never in the URL or a
  request field.
</Warning>

## Seeing calls

Each call is recorded in the **Action Submissions** table – see
[Custom Actions](/custom-actions/overview) for how to read it. GET lookups are
not recorded; other methods are.

## 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 details from the visitor instead.
  </Card>

  <Card title="Button action" icon="square-mouse-pointer" href="/custom-actions/button-actions">
    Show a one-tap button in the chat.
  </Card>

  <Card title="Knowledge Base" icon="file" href="/knowledge-base/overview">
    Train your bot on your own content.
  </Card>
</CardGroup>