Custom actions

Let the AI agent call your HTTP APIs mid-conversation — order lookups, account checks, ticket creation.

View as Markdown

A custom action is an HTTP request the agent can make during a conversation. You define the request and tell the agent when to use it; the agent collects the inputs you specify from the customer, calls your API, and uses the response in its reply — on every channel and in the Playground. Manage actions at app.asks.app/ai-agent/actions.

Plans allow 5 actions All plans, 15 Business and up, or 50 Premium. The full matrix is in Plans and limits.

Actions page with the New action button, the how-it-works explainer, and the custom actions usage meter — The Actions page under Tools.

You don't have to build the form by hand. In the action editor, describe the action in one sentence — "Look up an order's delivery status by tracking number" — and Describe it and we'll draft it generates a full draft: name, description, inputs, and request. Review it and verify the endpoint before saving.

Anatomy of an action

Action namestringrequired

What the action is called in your dashboard. The tool name the AI sees is derived from it at creation and stays fixed — renaming the action later doesn't change it.

What it does (for the AI)stringrequired

The description the model reads: when to invoke the action, what it returns, how to use it. This is the single biggest lever on whether the agent calls it at the right moment.

What to ask the user firstinputs

The parameters the agent collects before calling — each with a name, type, description, required flag, and optionally a fixed list of allowed values.

Method + URLrequestrequired

GET, POST, PUT, PATCH, or DELETE against an https URL template.

Headers, query, bodyrequest

Static values plus {{variable}} placeholders. Body mode is none, JSON, or form. Individual header values can be marked secret — they're encrypted, never shown again, and left blank on edit to keep the stored value.

Authenticationnone | bearer | api key | basic

Bearer token, API-key header (you name the header), or basic credentials. Secrets are encrypted at rest and never returned to the dashboard.

Variable templating

Collected inputs are inserted into the request with {{variable}} placeholders — in the path, query string, headers, or body. They are never allowed in the scheme or host: the destination of a request is fixed at design time, so a manipulated conversation can't redirect calls to another server. Built-ins {{conversation_id}}, {{channel}}, {{customer_id}}, and {{workspace_locale}} are also available.

Safety rails and advanced settings

Write methods require a domain allowlist. POST, PUT, PATCH, and DELETE actions must list at least one allowed domain; requests outside it are refused. Write actions are also rate-limited and audit-logged.
Timeouts — 1 to 30 seconds per call, 10 seconds by default.
Response filtering — optional JSONPath filters (like $.order.status) limit what the model sees from the response; empty means the full response.
Links off by default — URLs from the response only appear in replies if you enable "Allow links from the response in replies".
Save to memory — store a response value under a key that later actions in the same conversation can reference.
Thinking message — optional text shown to the customer while the action runs, like "Checking your order…". Widget only.

Advanced settings section of the action editor with the thinking message field, response filter JSONPath list, save-to-memory keys, timeout field, allowed domains input, and the response-links switch — Advanced settings in the action editor.

Manage and monitor

Each action card has an Enable action switch — pause an action without deleting it — plus badges for disabled and write actions, a call counter, and the status of the last call. Recent calls opens the last 20 invocations across all conversations with status, duration, and any error. Deleting an action deletes its stored credentials and call history with it.

Worked example: order status

Describe it for the AI

Name it Delivery status and describe it as: "Look up an order's delivery status by order number. Use when the customer asks where their order is. Returns status, items, and tracking link."

Add the input

One collected parameter: order_number, type text, required — "The customer's order number, e.g. #1234".

Define the request

GET https://api.example.com/orders/{{order_number}} with an API-key header for auth.

Filter the response

Add response filters like $.order.status and $.order.tracking_url so the model sees only what it needs.

Test and save

Use the editor's built-in test run with a sample order number, check the response, then save. Testing a write method performs a real request, behind a confirmation. The agent can call the action immediately.

Verify in the Playground: ask "where is my order?" and confirm the agent asks for the order number, calls the action, and answers from the response.

For tools that live outside your own API, see MCP servers.

← Previous

Escalation & handoff

MCP servers