# Custom HTTP Actions

URL: https://aihio.ai/en/help/ai-agent/actions
Description: Define an HTTPS API call that the agent fills in and the server runs during a conversation. Credentials are stored encrypted and calls are protected.

With custom HTTP actions, the AI agent can call your own HTTPS API mid-conversation: for example, look up an order's status, book a time, or create a support ticket directly in your own system. You define the endpoint and parameters, the AI agent fills the parameters from the conversation, and Aihio's server runs the call securely.

## Requirements

- **An Aihio plan on Starter tier or above.**
- **An HTTPS endpoint** for the agent to call. Only `https` is accepted, and calls run server-side with SSRF protection (private and internal addresses are blocked).
- Optionally, an **endpoint credential** (Bearer token or API key).

## Creating an action

1. **Open the Actions tab**

   In the dashboard: **Chatbots → select a chatbot → Settings → Actions**. Choose **Add action**.
2. **Define the basics**
   - The **identifier** is the action's machine-readable name (snake\_case, e.g. `lookup_order`). The AI agent refers to the action by this name.
   - The **description** tells the AI agent *when* to use the action. Write it clearly, for example "Look up a customer's order status by order number."
   - The **URL** and **HTTP method** (GET, POST, PUT, PATCH or DELETE). The URL must start with `https://`.
3. **Add parameters**

   Parameters are values the AI agent gathers from the conversation and fills into the call. Give each one a name (snake\_case), a label and a type (text, email or phone). Reference a parameter in the URL, headers or body with double curly braces, for example `https://api.example.com/orders/{{order_number}}`.

   You can also give a parameter an optional AI hint (for example "Customer order number, such as ORD-123"). The hint improves how accurately the agent fills the field from the conversation.

   A parameter used in the request must be required, so the call never runs with missing data.
4. **Choose authentication**
   - **No authentication** for public endpoints.
   - **Bearer token** or **API key**: enter the credential once. It is stored encrypted (Supabase Vault) and never shown again; only the last few characters stay visible for identification.
5. **(Optional) Pass verified visitor details**

   If the chat widget verifies the visitor's identity (see [Identity verification](/en/help/ai-agent/identity-verification)), you can pass verified details into the call with references such as `{{identity.email}}`. This requires **Require verified identity** to be enabled on the action.

   **Identity fields require JWT verification.** Only the signed-JWT method exposes `{{identity.*}}` to HTTP actions. With the HMAC user-hash method the visitor is verified for display, but identity references resolve to nothing and the call fails closed. Use signed JWTs if your action sends identity fields.

   Because you are then sending personal data to your own system, make sure the processing is GDPR-compliant. Aihio shows a reminder about this.
6. **Enable and test**

   You can test the action before saving: enter sample values in the form's **Test the action** section and run the call to see the endpoint's response and status right away. Testing an authenticated action requires entering the credential.

   Once the action is ready, turn it on and try a conversation that triggers it. While the AI agent is performing an action, the chat widget shows an indicator to the visitor.

## How it works

When a conversation matches the action's description, the AI agent calls it: it fills the parameters, and Aihio's server runs the HTTP call and returns the response to the agent, which turns it into a reply for the customer. Calls are always `https`, SSRF-protected, and only the parameters you defined and verified identity details are passed; no other conversation content is sent to your endpoint automatically.

## Feature library

The top of the Actions page shows a feature library: cards for ready-made features such as knowledge answers, lead capture and human support. Each card tells you three things at a glance:

- **Status**: "Available" means the feature can be enabled right away; "Coming soon" means it is still in development.
- **Plan tier**: if a feature requires a higher subscription tier, the card shows a tier chip (for example Starter or Pro). The chip disappears once your plan covers it.
- **Configure**: the button takes you straight to the right settings view, for example the knowledge base or human support settings.

The **Test** button runs a readiness check for the feature: it verifies whether the feature is enabled on this chatbot, and, for the knowledge-answer card, whether the knowledge base has content. The result shows as a colored badge (ready, partly ready or needs attention), with details on hover. The test never sends messages or changes any settings.

## Security

- Credentials are stored encrypted and never exposed to the browser.
- Calls run server-side: `https` only, port 443, no redirects, a response size cap and a timeout.
- Private, internal and metadata addresses are blocked (SSRF protection).