Skip to main content
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:
FieldDescription
NameParameter identifier (e.g., order_id)
Typestring, number, boolean, integer, array, or object
DescriptionWhat this parameter represents (helps the AI extract it)
RequiredWhether 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

OptionDescription
Speak DuringShow a message to the user while the API call is in progress (e.g., “Let me check that for you…”)
Speak AfterLet the AI formulate a response using the API result
Payload Args OnlySend 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.
1

Open the Function

Click on the function you want to test, or create a new one.
2

Open the Test Panel

Click the Test button at the bottom of the function modal.
3

Provide Test Arguments

The test panel auto-generates sample arguments based on your parameter schema. Edit them as needed.
{
  "order_id": "ORD-12345"
}
4

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.
Use the Test panel to verify your URL, headers, and authentication before going live. It sends a real request to your endpoint.

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