How AI actions work
An AI Action is a typed tool the chatbot can call mid-conversation. You define an action once (URL, method, schema, auth), the bot decides when to call it based on the conversation, and every call is recorded.
In this guide:
- The mental model
- Anatomy of an action definition
- How the bot decides to call an action
- Execution and idempotency
- Where actions appear in the UI
The mental model
Without actions, your chatbot is read-only — it answers questions but can’t change anything in the outside world. With actions, the bot becomes a thin agent — it can lookup, create, update, and delete records in your other systems.
The framework draws a clear line:
- Knowledge is what the bot knows — websites, documents, articles. Read-only, retrieval-based.
- Actions are what the bot can do — HTTP calls to external APIs. Side-effectful, parameterized.
Most useful chatbots use both.
Step 1: Open the Actions tab
On your chatbot detail page, click Actions in the left rail. You’ll see the list of currently-configured actions plus a New action button.
Screenshot: The Actions tab with several configured actions.
Anatomy of an action definition
Every action has these fields:
| Field | Purpose |
|---|---|
| Name | Display name shown to the bot (“Create Salesforce Lead”). The bot reads this to decide when to call. |
| Slug | Stable internal identifier. Auto-generated. |
| Description | What the action does, written in natural language. The bot uses this to decide when to call. |
| Endpoint | The HTTP URL to call. Supports template variables ({userId}, {orgId}). |
| Method | GET / POST / PUT / PATCH / DELETE. |
| Authentication | none / api-key / oauth. OAuth is the most common for third-party APIs. |
| Headers | Additional headers, including auth headers. |
| Body template | JSON template with placeholders the bot fills from the conversation. |
| Output mapping | How to interpret the response — pluck data.id as the new record ID, etc. |
requires_confirmation | If true, the bot pauses and asks the user to approve before firing. → Confirmation flows |
rate_limit_per_minute | Max calls per minute, per chatbot. Prevents accidental floods. |
Step 2: How the bot decides to call
When a user message arrives, the model considers:
- The conversation history.
- The chatbot’s Guidelines.
- The list of available actions (their names and descriptions).
- The knowledge sources retrieved for the question.
If an action’s name + description matches the user’s intent, the bot proposes calling it with parameters extracted from the conversation. The user (or, with requires_confirmation: false, the bot directly) confirms, and the call fires.
The clearer your action description, the more reliably the bot picks it. “Create a Salesforce lead from contact info captured in chat” is much better than “sf_lead_create”.
Step 3: Execution
When an action fires:
- The bot fills in the body template from the conversation.
- Hilal Chatbot signs the request with the configured auth.
- The HTTP call goes out (over Hilal’s backend, so secrets stay server-side).
- The response is parsed using the output mapping.
- The result is fed back to the bot, which uses it to generate a reply.
Every call is recorded in the audit log with: timestamp, action, parameters, response body, and HTTP status. → Confirmation flows & audit log
Idempotency
Each action call gets a client-generated idempotency key. If the same call is retried (network hiccup, user double-clicks confirm), the framework deduplicates — the side-effect runs once, the user sees the cached result.
Idempotency only works if your backend respects the Idempotency-Key header. Most modern APIs (Stripe, Shopify, Salesforce) do.
Where actions appear in the UI
- Actions tab on the chatbot — list, create, edit, delete actions.
- Template picker — start from a built-in template (HTTP GET, Stripe presets, Shopify write-backs).
- Action audit log — per-action execution history.
- Chat UI — when an action requires confirmation, a confirmation card appears inline.
Permissions
Action management is gated by permissions:
actions.read— see the actions list.actions.create/update/delete— manage actions.actions.execute— fire actions in conversations (usually granted to the chatbot itself, not humans).