Tool Integration for VoiceBot
This documentation covers the full lifecycle of defining and deploying a Tool, using the Console UI for all steps.
I. Step 1: Tool Creation and API Configuration
This section focuses on defining the external API endpoint and its interface.
A. Initial Tool Setup
- Navigate to Tool Integration: From the main dashboard, select Build Bot -> Tool Integration from the side menu.
- Start Creation: Click the "Create tools" button in the top right corner. The "Create custom API Integration" panel will appear.
- Define Tool Metadata:
- Integration Name*: Provide a unique, non-editable identifier (e.g., get_order_status).
- Integration Description*: A short internal note.
- Helps AI understand when to use this integration: This is the natural language prompt that guides the LLM (AI) on when to execute this tool. Be specific (e.g., "Get Order Status").
B. Defining the Endpoint
- HTTP Method: Select the appropriate REST verb (e.g., GET, POST, PUT, DELETE).
- Base Domain*: Enter the root URL of your API (e.g., https://api.example.com).
- URL Path*: Enter the specific endpoint path (e.g., /order-status).
- Headers: Click "Add Header" to define key-value pairs for authentication, content-type, or other necessary request headers.
C. Defining Tool Parameters
Parameters define the data inputs your tool expects from the bot's conversation.
- Click "Add Parameter" under the Parameters section.
- Key Name: The internal name for the variable.
- Parameter Type: Specify where the data will be sent in the HTTP request:
- Path: Data is substituted into the URL Path (e.g., /users/{id}).
- Query: Data is appended to the URL as key-value pairs (e.g., ?city=Bangalore).
- Base Type: Specify the expected data format: String, Number, Boolean, or Object.
II. Step 2: Testing and Activating the Tool
A tool must pass a successful test to prove it is functional before it can be marked as Active and integrated into a bot.
A. Testing the Integration
- Click the "Test API Integration" tab.
- Enter Test Data: Input test values for any Path Parameters, Query Parameters, or Body Parameters (for POST/PUT requests).
- Note: The UI will provide a warning: "Test your API configuration before saving the integration. A successful test is required to save."
- Execute Test: Click "Test API".
B. Tool Status Management (Activation/Inactivation)
The Tools listing shows the current status of all your integrations.
- Status Display: The Status column shows whether a tool version is Active (available for bots) or Inactive (unavailable).
- Activation/Inactivation: Click the three-dot menu (...) next to any tool to manage its status:
- If a tool is Inactive, the menu may contain an option to Mark as Active (typically after a successful test).
- If a tool is Active, the menu contains the option to Mark as Inactive.
III. Step 3: Integrating the Tool into Your Bot
Once a tool is marked Active, you can attach it to a bot and define how the conversational input maps to the tool's parameters.
A. Attaching the Tool
- Navigate to Build Bot (in bot editing view).
- Scroll down to the Tools section: "Let the agent perform specific actions."
- Toggle Switch: Find your active tool (e.g., get_order_status) and toggle the switch to the ON position to attach it to the bot.
B. Configuring Parameter Mapping
After attachment, you must specify how the tool receives its input during a live conversation.
- Edit Parameters: Click on the attached tool's name or the gear icon to open the Edit Parameters panel.
- Define Inputs: For each parameter, select the Value Type:
- LLM Prompt: The AI will use the description provided to extract the required value (e.g., a city name or order id) directly from the user's utterance. This is the most common choice for conversational input.
- Constant Value: A fixed value that is always passed to the API (e.g., a static API key).
- Dynamic Variable: A value retrieved from a system or user-defined variable (not shown in the provided images, but an available option).
- Save: Click "Save" to finalize the parameter mapping.
IV: Step-by-Step Example: Integrating a Public API
This example uses a public, simple GET API that requires no authentication or parameters to demonstrate the full integration workflow.
1. Create the HTTP Tool
- Go to Tool Integration and click "Create tools".
- In the API Configuration panel, enter the following details:
- Integration Name: get_a_random_joke
- Integration Description: Get a random joke from a public API.
- Helps AI understand when to use this integration: Get a random joke.
- HTTP Method: GET
- Base Domain*: https://official-joke-api.appspot.com/
- URL Path*: /random_joke
- Headers/Parameters: Do not add any Headers or Parameters as this API does not require them.
- Click the "Test API Integration" tab.
- Click "Test API". The system will execute the GET call. You should see a successful 200 OK status and a JSON response containing the joke's setup and punchline.
- Click "Save". The tool will now appear in the list with an Active status.
2. Integrate the Tool into the Bot
- Navigate to Build Bot and edit an existing one or create a new bot.
- In the bot objective, just add: "To tell a joke, call the get_a_random_joke API."
- Scroll down to the Tools section and enable the toggle switch next to the tool named get_a_random_joke.
- Click "Save" to update the bot configuration.
3. Test the Bot
- Navigate to Talk to Bot.
- Ask the bot: "Can you tell me a random joke?"