Custom HTTP Actions

With custom HTTP actions, an AI agent can call your HTTPS API during a conversation: for example, look up an order’s status or create a support ticket in your system. You define the endpoint and parameters, the agent fills them from the conversation and Aihio’s server runs the call. Your endpoint remains responsible for authorization and input validation.

• A subscription that includes HTTP actions and permission to edit the agent’s settings.
• 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).

1. Open the Actions tab

   Open Oma Aihio, select the agent and open 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 guides field completion but does not replace input validation in your endpoint.

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

   Pass only information needed by the action and restrict its use in the receiving system. Do not treat an order number supplied in conversation as proof of access to another customer’s information.

6. Enable and test

   You can test the action before saving: enter test values in the form’s Test the action section and run the call to see its response and status code. This makes a real HTTP request, so use a test environment for actions that write data. Testing an authenticated action requires entering the credential.

   Once the action is ready, enable it and try a conversation that needs it. Check both the agent’s answer and the actual result in your system. A successful status code alone does not prove that the correct order was retrieved, for example.

The agent selects actions based on their description and the conversation; this is not an exact-keyword rule. It fills parameters, Aihio’s server makes the HTTP call and the agent uses the result to answer the customer. The endpoint receives the request you configured and its referenced data, not the entire conversation automatically.

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.

A feature card’s readiness check inspects configuration. It differs from the HTTP action test, which actually calls your endpoint. Verify the final behavior with a conversation and the result in the receiving system.

• Stored credentials are not displayed in full again. Never put them in an action description or example parameters.
• 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).

• The action is not selected: clarify its description and test both relevant and unrelated questions.
• The endpoint rejects the request: check the status code, credential and required parameters in a test environment.
• Identity information is missing: check the valid JWT and the action’s verification requirement.
• A write repeats: prevent duplicate processing in your endpoint. Do not assume the AI calls an action only once.

Disable an action that produces the wrong result. Fix and test the receiver before enabling it again. Disabling the action does not undo changes already made through the endpoint.