How to create custom skills for the AI agent

HTTP skills let the agent call external APIs during a conversation. For example: check stock, look up an order status or record data in an internal system.

Available on: all plans.
Who can do it: admins.

---

What skills are

They're actions you set up for the agent to run when it needs external information. When it identifies the need, the agent fires the configured HTTP call and uses the returned data to answer the lead.

Create a skill

1. Go to Settings > Knowledge base > Skills

2. Click + Create skill

3. Fill in the Skill title (a descriptive name that will be displayed)

4. Select HTTP in the Type field

5. Configure the tabs below

HTTP Configuration tab

HTTP method: select the request method (GET, POST, PUT, PATCH, DELETE)

API URL: enter the full endpoint URL. Use :variavel for dynamic path params (e.g. https://api.exemplo.com/v1/users/:userId/orders)

Timeout (ms): maximum time to wait for the API response (between 1,000 and 120,000 ms). The default is 30,000 ms

HTTP headers: add the headers you need by clicking + Add Header (e.g. Authorization, Content-Type)

Query Parameters: add URL parameters by clicking + Add Parameter. For each parameter, set the Name and the value's Source:

• Fixed value — literal text, the same for every call (e.g. v2 in api_version)

• Smart field — the value comes from a field in the conversation context (contact, company, conversation), chosen in the field picker

• AI-generated — the AI extracts the value from the conversation in real time based on a prompt you write (e.g. “Extract the tax ID provided by the lead”); there's a switch to mark the field as required

Auth & Retry tab

Authentication: set how the skill will authenticate with the API. The available types are:

• Bearer Token: enter the authentication token

• API key: enter the API key

• HMAC (signature): Nuvia signs each request with a shared secret (see below)

HMAC authentication (per-request signature)

Some APIs don't accept a fixed token: they require each request to be signed with a secret, to prove the call is legitimate and hasn't been replayed. This is the standard used by payment gateways, banks and many Brazilian APIs built with Laravel.

Choose HMAC (signature) as the authentication type and fill in the fields according to the documentation of the API you're going to call.

Building the signed string template. Use the placeholders below, separating lines with \n:

{method} · {path} · {path_with_query} · {path_relative} · {query} · {url} · {host} · {body} · {body_sha256_hex} · {timestamp} · {api_key}

The Use common format button fills in the template with {method}\n{path_with_query}\n{timestamp}\n{body} and sets the timestamp format to ISO 8601 microseconds — the most frequent arrangement. If the API you use asks for a different order, edit it by hand.

Where the signature is sent. By default, Nuvia sends three separate headers, whose names you can change:

Single header (optional). Some APIs ask for everything packed into a single header. Fill in Single header name (e.g. X-Auth) and Header value template (e.g. hmac {api_key}:{timestamp}:{signature}), using the placeholders {api_key}, {timestamp} and {signature}.

When you fill in the single header template, the API key and signature header name fields disappear from the screen, since they're no longer used. The timestamp header is still sent separately.

Retry: defines the behavior when the call fails:

• Max Attempts: maximum number of attempts (1 to 10)

• Delay (ms): initial interval between attempts

• Multiplier: exponential backoff factor between attempts

Parameters tab

Defines the parameters the agent extracts from the conversation to use in the call. Configure them using the Parameters Schema (JSON Schema):

• Field name: the parameter's identifier

• Type: data type (Text, Number, etc.)

• Description: instruction for the agent on how to extract this value from the conversation

Click + Add property to add new parameters. For advanced settings, switch to the Advanced tab and edit the JSON Schema directly.

When the value is empty

For each parameter, you define what Nuvia sends to the webhook when the agent can't fill in that field in the conversation:

• Don't send the field (default) — the key is omitted from the request body (same behavior as before)

• Send empty (“”) — sends the field with empty text

• Send null — sends the field with the value null

This option is available for top-level fields. Use it when the API on the other side expects the key to always be present (even without a value) instead of simply missing.

Response tab

Set how the agent interprets the API response through Response Mapping (optional). When enabled, it lets you map specific fields from the API response for use in the conversation.

Test Request tab

Use the Test Request tab to fire the HTTP call on its own and see the response without running a whole conversation with the agent. It's for validating the endpoint, authentication and payload before putting the skill into production. The tab appears both when creating and when editing HTTP skills.

How to test:

1. Open the Test Request tab

2. In the Parameters (JSON) field, adjust the test values. The field comes pre-filled with the parameters declared in the Parameters tab — each one's value shows the parameter's description as an example, for you to replace with a real value

3. Click Test Request

What the result shows:

• Response Status (green for success, red for error) and response Time in milliseconds

• URL called, Headers sent and Body sent — exactly what was fired. For security, the authentication token is hidden in the output

• Response Body (raw): what the API returned

• Response Body (mapped): the result after the Response Mapping configured in the Response tab

• Recent test history: keeps the latest runs (up to 10) so you can compare results; click any of them to review it

Warnings that help you configure:

• If you type a field that isn't declared in the Parameters tab, Nuvia warns that it will be ignored in the test — the same filter the real agent applies (it only sends what's in the schema)

• If no parameters are declared in the Parameters tab, the test sends an empty body and shows a warning asking you to declare the parameters there

Use cases

• Check product stock

• Look up order status

• Schedule a technical visit

• Calculate shipping

• Register a lead in an external CRM

Frequently asked questions