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

# Custom Functions

> Extend your agent's capabilities with custom API integrations

**Custom Functions** (also known as Tool Calling) allow your agent to interact with external systems, fetch real-time data, or perform actions on behalf of the user.

## How Custom Functions Work

1. **Definition**: You define a function in the dashboard with a name, description, and required parameters.
2. **Detection**: When a user asks a question that requires the function (e.g., "What is my order status?"), the AI detects that it needs to call that function.
3. **Execution**: The system sends a request to your configured API endpoint with the extracted parameters.
4. **Response**: Your API responds with the data.
5. **Answer**: The AI uses that data to provide a final answer to the user.

## Configuring a Function

Navigate to your agent's editor page and scroll to the **Custom Functions** section.

### 1. Basic Info

* **Function Name** — A descriptive identifier (e.g., `get_order_status`).
* **Description** — Tell the AI when to use this function (e.g., "Retrieves the status of a customer's order using their order ID"). The more specific, the better.

### 2. API Endpoint

* **Method** — `GET`, `POST`, `PUT`, or `DELETE`.
* **URL** — The full webhook URL on your server.
* **Timeout** — How long to wait for a response (in seconds) before timing out.

### 3. Headers & Query Params

Add custom headers (e.g., authentication tokens) and query parameters using the key-value editors:

```
Authorization: Bearer sk-your-secret-key
Content-Type: application/json
```

### 4. Parameters

Define the inputs the AI needs to extract from the user's message:

| Field           | Description                                                    |
| --------------- | -------------------------------------------------------------- |
| **Name**        | Parameter identifier (e.g., `order_id`)                        |
| **Type**        | `string`, `number`, `boolean`, `integer`, `array`, or `object` |
| **Description** | What this parameter represents (helps the AI extract it)       |
| **Required**    | Whether the AI must collect this before calling the function   |

Parameters are defined as a JSON Schema object. You can use the JSON editor to define complex nested structures.

### 5. Behavior Options

| Option                | Description                                                                                         |
| --------------------- | --------------------------------------------------------------------------------------------------- |
| **Speak During**      | Show a message to the user while the API call is in progress (e.g., "Let me check that for you...") |
| **Speak After**       | Let the AI formulate a response using the API result                                                |
| **Payload Args Only** | Send only the extracted parameters in the request body (no extra metadata)                          |

## Testing Your API

You can test your function directly from the dashboard without creating a real conversation.

<Steps>
  <Step title="Open the Function">
    Click on the function you want to test, or create a new one.
  </Step>

  <Step title="Open the Test Panel">
    Click the **Test** button at the bottom of the function modal.
  </Step>

  <Step title="Provide Test Arguments">
    The test panel auto-generates sample arguments based on your parameter schema. Edit them as needed.

    ```json theme={null}
    {
      "order_id": "ORD-12345"
    }
    ```
  </Step>

  <Step title="Run the Test">
    Click **Send Test Request**. The panel will show:

    * **Status Code** — HTTP response code.
    * **Response Body** — The JSON response from your API.
    * **Duration** — How long the request took.
  </Step>
</Steps>

<Tip>
  Use the Test panel to verify your URL, headers, and authentication before going live. It sends a real request to your endpoint.
</Tip>

## Response safety (what your API may return)

To keep agents predictable and safe, Deflect applies **guardrails** to responses from your custom API **before** the model consumes them:

* **Content type** — Only **text** and **JSON** responses are accepted; binary downloads (PDFs, images, executables, etc.) are blocked so the model never ingests unexpected payloads.
* **Size limit** — Responses are capped (with streaming where applicable) so a misbehaving endpoint cannot overwhelm the assistant or your bill.

The **Test API** panel surfaces the same rules as production, so a blocked or truncated response in testing is expected when you simulate a bad endpoint.

## Example use cases

* **E-commerce**: Check order status, track shipments, or check inventory.
* **SaaS**: Reset passwords, upgrade plans, or fetch usage stats.
* **Booking**: Check availability, book appointments, or cancel reservations.
* **CRM**: Look up customer profiles or update records.

<Warning>
  Ensure your webhook endpoint is secure and can handle requests from Deflect. We recommend using HTTPS and validating incoming requests with an API key or secret.
</Warning>