# Custom HTTP Actions

URL: https://aihio.ai/en/docs/chatbot/actions
Description: Define an HTTPS API call that the AI agent fills in and the server runs during a conversation. Credentials are stored encrypted and calls are SSRF-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/docs/chatbot/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.

## 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).