Tools & API Calls

Tools are reusable API integrations that your bots can call during a conversation. A tool wraps a single HTTP request -- complete with URL, headers, body template, and parameter definitions -- so it can be invoked by name from any bot flow without duplicating configuration.

Why Use Tools?

You can make API calls in two ways: with a one-off API Call node placed directly on the canvas, or with a Tool that is defined once and reused everywhere. Tools provide several advantages over inline API Call nodes:

Capability	API Call Node	Tool
Reuse across bots	No -- config lives on one node	Yes -- any bot can call the same tool
Centralized configuration	No -- each node has its own URL and headers	Yes -- update the tool once, all bots pick up the change
LLM tool calling	No -- the node runs at a fixed point in the flow	Yes -- the LLM can decide when to call the tool based on conversation context
Template library	No	Yes -- start from pre-built templates for common integrations
Test panel	Limited	Full test panel with parameter inputs and response preview
Version management	No	Yes -- enable, disable, or swap tools without editing flows

When to Use Which

Use a Tool when you want the LLM to decide when to call an API (agentic behavior) or when you need the same call in multiple bots. Use an API Call node for one-off calls at a fixed point in a specific flow.

How Tool Execution Works

When a tool is invoked during a conversation, the platform follows these steps:

1. Parameter resolution -- The orchestrator resolves parameter values from the conversation context (session variables, user input, or LLM-extracted values).
2. Variable substitution -- Placeholders like {{param.account_id}} and {{env.API_KEY}} in the URL, headers, and body are replaced with actual values.
3. HTTP request -- The platform sends the configured HTTP request to the external API.
4. Response mapping -- The response body is parsed and mapped to session variables using JSONPath expressions.
5. Result delivery -- The result is stored in the configured output variable and made available to subsequent nodes or to the LLM for generating a response.

Tool Categories

Tools are organized into four categories:

Category	Purpose	Examples
Routing	Control conversation flow	Escalate to Agent, Require Authentication, End Conversation
Data	Read or write data	Account Lookup, Search Knowledge Base, Set Context Variable
Integration	Call external APIs	Payment Processing, CRM Update, Order Status Check
Communication	Send messages or notifications	Schedule Callback, Send Email, Send SMS

System Tools

Every tenant has access to a set of built-in system tools that are always available:

• Escalate to Agent -- Transfer the conversation to a live agent.
• Search Knowledge Base -- Query indexed documents for relevant information.
• End Conversation -- Close the conversation with an optional summary.
• Require Authentication -- Trigger SSO-based user authentication.
• Set Context Variable -- Store a value in a session variable.
• Look Up Account -- Find a customer account by account number, phone, or email.

System tools cannot be modified or deleted. They appear in every bot's tool list automatically.

imageTools list page showing System Tools section and Custom Tools section with tool name, category, description, and status columns

The Tools list page

Custom Tools

You can create your own tools to integrate with any HTTP API. Custom tools are scoped to your tenant and can be shared across all bots within it. See Creating Tools for a step-by-step guide.

Getting Started

Creating Tools

Step-by-step guide to defining a new custom tool with parameters, authentication, and response mapping.

Tool Templates

Browse pre-built templates for common integrations and create tools in seconds.

Tool Authentication

Configure API keys, bearer tokens, OAuth2, and other authentication methods for your tools.

Testing Tools

Use the built-in test panel to verify your tool configuration before deploying it in a bot.

WARNING

Tools make real HTTP requests to external APIs. Always test with non-production credentials first, and be cautious with tools that modify data (POST, PUT, DELETE).