1. [Help](https://nuvia.ai/en/docs) 2. [Pipeline and Smart Funnels (AI agents)](https://nuvia.ai/en/docs/colecoes/19377999-pipeline-and-smart-funnels-ai-agents) 3. [Smart Funnels](https://nuvia.ai/en/docs/colecoes/19431085-smart-funnels) # How to create custom skills for the AI agent How to create and configure HTTP tools (Custom HTTP) that let the AI agent call external APIs during conversations. Available on all plans Who can do it admins Updated on September 9, 2026 [Smart Funnels](https://nuvia.ai/en/docs/colecoes/19431085-smart-funnels) 1. [How to create custom skills for the AI agent](https://nuvia.ai/en/docs/artigos/14590394-how-to-create-custom-skills-for-ai-agent) 2. [How to write the agent's goal, knowledge, and communication pillars](https://nuvia.ai/en/docs/artigos/16515436-write-agent-goal-knowledge-communication-pillars) 3. [How to write the instructions for a stage](https://nuvia.ai/en/docs/artigos/16515466-how-to-write-stage-instructions) 4. [Standard stages of a sales funnel: how to design the agent's flow](https://nuvia.ai/en/docs/artigos/16515486-standard-sales-funnel-stages-agent-flow) 5. [How to archive a Smart Funnel by transferring its conversations](https://nuvia.ai/en/docs/artigos/16624949-how-to-archive-smart-funnel-transferring-conversations) 6. [How recent conversation reopening works in the Smart Funnel](https://nuvia.ai/en/docs/artigos/16644378-how-recent-conversation-reopening-works-smart-funnel) 7. [How to feed the Knowledge Center](https://nuvia.ai/en/docs/artigos/14579639-how-to-feed-the-knowledge-center) 8. [How to set up and use Smart Follow-ups in Nuvia](https://nuvia.ai/en/docs/artigos/14580483-how-to-set-up-use-smart-follow-ups-nuvia) On this page 1. What skills are 2. Create a skill 3. HTTP Configuration tab 4. Auth & Retry tab 5. Parameters tab 6. Response tab 7. Test Request tab 8. Use cases 9. Frequently asked questions **On this page9 sections** 1. What skills are 2. Create a skill 3. HTTP Configuration tab 4. Auth & Retry tab 5. Parameters tab 6. Response tab 7. Test Request tab 8. Use cases 9. Frequently asked questions 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. Field What it's for **API key** Public identifier, sent along with the signature. Required **Secret** The secret used for signing. Required. The field is masked on screen, like a password field **Signed string template** Defines exactly which text is signed. Required — each API builds it its own way **Prefix removed from the signed path** Optional. Used by {path_relative}. The trailing slash decides whether a slash remains: /api/ produces customers, /api produces /customers. Blank = full path **Timestamp format** ISO 8601 microseconds (Laravel/Carbon) · ISO 8601 milliseconds · Unix (seconds) · Unix (milliseconds). Default: ISO 8601 microseconds **Algorithm** HMAC-SHA256 (default) or HMAC-SHA512 **Signature encoding** Hexadecimal (default) or Base64 **Signature prefix** Optional. Text placed before the signature, e.g. sha256= **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. ⚠️ A mistyped placeholder won't go through. If you write something like {pathwithquery}, Nuvia refuses to save and tells you which placeholder is invalid, along with the list of accepted ones. This is on purpose: a wrong placeholder that slipped through would turn into an unexplained 401 error in the middle of a real conversation. Where the signature is sent. By default, Nuvia sends three separate headers, whose names you can change: Header Default name API key X-API-Key Timestamp X-Timestamp Signature X-Signature **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. 💡 Getting a 401 even though everything looks right? The number one suspect is the timestamp format; it must match exactly what the API on the other side expects. Also check that the Prefix removed from the signed path matches what the API documentation describes. Use the Test Request tab to validate before putting the skill into production. **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** 💡 Good to know: when you test, the skill's changes are saved automatically (creating or updating it) and the request runs on the backend, simulating the real scenario. You don't need to save manually first. **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 ## Frequently asked questions **Do I need to run a conversation to test the skill?** No. The **Test Request** tab fires the call on its own and shows the response right away, without starting a conversation with the agent. **Does the test use the version on screen or the saved one?** When you click test, Nuvia saves the skill automatically (creating or updating it) and runs the request against that saved version, so the test always reflects what you've just configured. **Does the authentication token show up in the test result?** No. Authentication headers are hidden in the test output. **Can I see the HMAC Secret after saving?** The field is masked on screen, like a password field. Hiding it in the **Test Request** result applies to that test's authentication headers; it doesn't stop someone with access to the skills screen from retrieving the configured secret. Treat the Secret as a company credential and limit who has access to the Skills area. **Does the test repeat the call on failure, like Retry?** No. The test makes a single call (no retry), so you can see exactly what happens in one attempt. Retry still applies when the agent runs it for real. **Does the agent decide on its own when to use the skill?** Yes, based on the description and the conversation context. **What happens if the agent doesn't fill in a parameter?** It depends on that parameter's **When the value is empty** option: by default Nuvia **omits** the key; you can choose to send empty (“”) or **null**, depending on what the external API expects. The setting applies to top-level fields. **What happens if the API returns an error?** The agent adapts its answer and lets the contact know. In the test, the error shows up with the status and message returned by the API (or “Network error” when the call doesn't even complete). [NextHow to write the agent's goal, knowledge, and communication pillars](https://nuvia.ai/en/docs/artigos/16515436-write-agent-goal-knowledge-communication-pillars) Was this article helpful? ## Related articles - [How to manage API keys in Nuvia](https://nuvia.ai/en/docs/artigos/15230128-how-to-manage-api-keys-in-nuvia) - [How to create and edit Smart Funnels through MCP (Agent Builder)](https://nuvia.ai/en/docs/artigos/16074655-create-edit-smart-funnels-through-mcp-agent-builder) [Smart Funnels](https://nuvia.ai/en/docs/colecoes/19431085-smart-funnels) 1. [How to create custom skills for the AI agent](https://nuvia.ai/en/docs/artigos/14590394-how-to-create-custom-skills-for-ai-agent) 2. [How to write the agent's goal, knowledge, and communication pillars](https://nuvia.ai/en/docs/artigos/16515436-write-agent-goal-knowledge-communication-pillars) 3. [How to write the instructions for a stage](https://nuvia.ai/en/docs/artigos/16515466-how-to-write-stage-instructions) 4. [Standard stages of a sales funnel: how to design the agent's flow](https://nuvia.ai/en/docs/artigos/16515486-standard-sales-funnel-stages-agent-flow) 5. [How to archive a Smart Funnel by transferring its conversations](https://nuvia.ai/en/docs/artigos/16624949-how-to-archive-smart-funnel-transferring-conversations) 6. [How recent conversation reopening works in the Smart Funnel](https://nuvia.ai/en/docs/artigos/16644378-how-recent-conversation-reopening-works-smart-funnel) 7. [How to feed the Knowledge Center](https://nuvia.ai/en/docs/artigos/14579639-how-to-feed-the-knowledge-center) 8. [How to set up and use Smart Follow-ups in Nuvia](https://nuvia.ai/en/docs/artigos/14580483-how-to-set-up-use-smart-follow-ups-nuvia) ## Still need help? Customers reach support through the chat inside the platform. Not a customer yet? Talk to our team. [Talk to support in the platform](https://app.nuvia.ai) [I'm not a customer yet](https://nuvia.ai/en/contact) --- Source: https://nuvia.ai/en/docs/artigos/14590394-how-to-create-custom-skills-for-ai-agent