Custom Tools

Let your AI call your own endpoints to fetch live, customer-specific data

Standard & Pro Plans

Ülevaade

Custom Tools let your AI agent call your own API endpoints during a conversation to fetch live, request-specific data — order status, shipment tracking, stock for a specific SKU, account details, and more.

Asyntai gives you three ways to feed live or customer-specific data to the AI. Custom Tools are the right choice when the value the AI needs only appears during the conversation:

Real-Time Data Feed — loads one fixed dataset (e.g. your whole product catalog) into every conversation. Best for shared data that's the same for all visitors.
User Context — your site pushes data it already knows about the current visitor (e.g. a logged-in customer's name, plan, or recent orders) at the start of the chat. Best when the visitor is identified up front.
Custom Tools — the AI calls your endpoint on demand, with values it extracts from the chat. Best when the value isn't known until the customer types it — like an order number from an anonymous visitor.

For example, when a customer asks “Where is my order #10294?”, the AI extracts the order number, calls your endpoint with it, and answers using the verified response. User Context can't cover this case on its own, because the order number isn't known until mid-conversation — that's exactly where Custom Tools fit. (Many stores use User Context for logged-in visitors and a Custom Tool for ad-hoc lookups.)

The AI decides when to call a tool based on the description you write. You decide what the tool does by pointing it at your endpoint. Asyntai makes the call server-side — you write no code and host no middleware.

Kuidas see töötab

You define a tool — a name, a description, your endpoint URL, and the parameters the AI should send.
The AI calls it when relevant — when the conversation matches your description, the AI calls the tool with values it extracts from the customer's message.
Asyntai calls your endpoint — our server makes the HTTP request to your URL and feeds the response back to the AI.
The AI answers — using the verified data your endpoint returned.

No code required: You only need an endpoint that already returns your data. You configure everything else in a dashboard form — there is no callback, webhook, or browser script to build.

Kasutusjuhud

Order status Look up an order by number and return its current status

Shipment tracking Return the latest tracking state for a tracking number

Stock check Return live availability for a specific product or SKU

Account lookup Return account or subscription details for an identifier

Seadistamine

Open Custom Tools Go to /custom-tools/ and click Add tool

Describe the tool Give it a name, a clear description, and your endpoint URL

Define parameters Add the inputs the AI should extract and send (e.g. order_number)

Save & test Save, then ask your bot a matching question to see it in action

Fields

Name — an identifier for the function (letters, numbers, underscores), e.g. get_order_status. The AI sees this name.
Description — the most important field. It tells the AI when to call the tool. Be explicit: “Call this whenever the customer mentions an order number. Do not ask for verification.”
Endpoint URL — the public HTTPS URL Asyntai will call.
HTTP method — GET (read-only, recommended) or POST (can change data — see Security below).
Parameters — the inputs the AI extracts from the conversation and sends. Each has a name, type, description, and required flag. For GET they are sent as query-string parameters; for POST as a JSON body.
Auth header (optional) — a header name + value sent on every call, e.g. X-API-Key. Use this if your endpoint requires a key.

Parameters are required for the AI to pass any value. If your endpoint needs an input (like an order number), you must add a parameter for it — without one, the AI has no slot to put the value in and will call the endpoint empty. Two things matter:

The parameter name must match exactly what your endpoint expects. A parameter named order_number is sent as ?order_number=... (GET) or {"order_number": "..."} (POST). If your endpoint reads id, name the parameter id.
You never type the value yourself — you only declare the parameter. The AI fills it in at call time from what the customer wrote.

Worked example: order status lookup

Suppose your store exposes this endpoint:

GET https://yourstore.com/api/order-status?order_number=10294

…which returns JSON like:

{
  "found": true,
  "status": "Accepted, preparing for shipment",
  "carrier": "DHL",
  "customer_message": "Your order has been accepted and is being prepared for shipment."
}

You would configure a tool like this:

Name: get_order_status
Description: “Look up the status of a customer order. Call this immediately whenever the customer provides an order number — do not ask for additional verification. Use the returned customer_message in your reply.”
Endpoint URL: https://yourstore.com/api/order-status
Method: GET
Parameter: order_number (string, required) — “The customer's order number, typically 8+ digits.”

When a customer writes “How is my order #10294?”, the AI calls get_order_status(order_number=10294), Asyntai requests your URL with ?order_number=10294, and the AI answers using the response.

Tip: The AI sends the values it decides on — you never pre-fill them. Keep parameter names and descriptions clear so the model knows exactly what to extract.

What your endpoint receives and should return

Request: a GET with your parameters in the query string, or a POST with a JSON body. Any auth header you configured is included.
Response: return JSON (preferred) or plain text. Asyntai passes the body back to the AI. A field the AI can quote directly — like customer_message — works well.
Not found / errors: return a clear payload (for example a JSON object with found: false and a customer_message) so the AI can respond truthfully instead of guessing.

Testing your tool

Each tool has a built-in Test this tool panel on the configuration page, so you can verify it works before any customer uses it — and without sending a message through the bot.

Enter sample values for the tool's parameters (e.g. a real order number).
Click Run test. Asyntai calls your endpoint exactly as the AI would — same query string or JSON body, same auth header, same 5-second timeout and safety checks.
You'll see the result instantly: a success/failure badge, the HTTP status, the response time, the exact URL we called, and your endpoint's raw response (pretty-printed if it's JSON).

This works on unsaved edits too, so you can adjust the URL, parameters, or auth header and re-test until it returns what you expect.

Note: Testing a POST tool really calls your endpoint and may change data — the test panel warns you before you run it. For read-only GET tools there's nothing to worry about.

Security — read this

Your endpoint is the security boundary, not the AI. The chat widget is public, and the AI can be manipulated by a visitor into calling a tool with any values. This is true of every AI tool-calling system. Design your endpoint accordingly:

Prefer GET / read-only. Lookups (order status, stock, tracking) are safe to expose. GET is the default for this reason.
POST requires acknowledgement. Because POST can change data, a POST tool can only be saved after you tick a checkbox confirming you are solely responsible for securing and authorizing requests on your own endpoint. Never connect refunds, cancellations, password changes, or money movement unless your endpoint independently verifies the request.
Guard against enumeration. If a lookup key is guessable (like sequential order numbers), require a second factor — e.g. order number and the email on the order, and verify they match — so a visitor can't read other customers' data by trying numbers.
Never trust the AI's arguments. Validate and authorize every request server-side as if it came from an anonymous attacker — because it effectively can.

Verifying live calls

Once your tool is live, every real invocation from a conversation is logged. For each call we record the tool name, the arguments the AI sent, the exact URL we requested, the HTTP status, the response, and the duration. This lets you confirm a tool fired in a real chat and see what your endpoint returned, without digging through your own server logs. (The Test this tool panel above is for checking the setup yourself; this log captures what happens during actual customer conversations.)

Limits & safeguards

Up to 10 tools per website.
5-second timeout per call; responses are capped at 10 KB.
Endpoints must be public http(s) URLs. Private, loopback, and internal-network addresses are blocked.
Available on Standard and Pro plans.
Billing: each tool call counts as one additional message on your plan. A normal reply uses 1 message; a reply where the AI calls one tool uses 2 (the reply plus the tool call), because a tool call requires an extra AI request.
If a tool call fails (timeout, error, blocked), the AI is told and answers gracefully — it won't crash the conversation.

Dokumentatsioon