API Tools — How to Connect Your AI Agent to External Systems
Learn what API Tools are, when to use them, how to create them, how to configure the API connection, and how to test them — with real examples for GET and POST requests.
What is an API Tool?
An API Tool connects your AI Agent to an external system — like your CRM, booking platform, property database, or any third-party service that provides an API. When a customer asks a question that requires live data, the agent collects the required information and calls the API to fetch or send data in real time.
Unlike Bot Tools that trigger a journey inside Bot Studio, API Tools call an external URL directly and return the result to the agent, which then uses it to respond to the customer.
When Should You Use an API Tool?
Use an API Tool when the agent needs to pull live data or push data to an external system. Here are some common scenarios:
Customer asks "What is the status of my order?"
Fetches order details from your system using the order ID
Customer shares their phone number
Looks up their record in your CRM
Customer asks "What properties are available in Mumbai?"
Fetches a list of properties filtered by city
Customer wants to book a site visit
Sends the booking details to your scheduling system
Customer says "Register me as a lead"
Creates a new lead record in your CRM
Customer asks "What time slots are available on Saturday?"
Fetches available slots from your booking system
If the answer depends on live data from another system, an API Tool is the right choice.
How API Tools Work
A customer sends a message on WhatsApp.
The AI Agent reads the message and matches it to an API Tool based on the tool's description.
If the tool has parameters, the agent collects each piece of information from the customer.
Once all required information is collected, the agent calls the external API.
The API returns data to the agent.
The agent uses the returned data to respond to the customer.
The entire process happens automatically — the customer simply chats, and the agent handles the API call behind the scenes.
Key Fields in an API Tool
Every API Tool has the same basic fields as a Bot Tool — Name, Description, Type, and Parameters. But because it connects to an external system, it has additional fields:
Name
A clear name describing what the tool does — for example, Get Lead By Phone or Book Site Visit
Description
Tells the agent when to use this tool. Write it clearly — the agent reads this to decide when to trigger it
Type
Set to API
Parameters
Information the agent collects from the customer before calling the API
Import from cURL
Paste a cURL command to auto-fill the Method, URL, Headers, and a basic skeleton of the request body including parameters. Useful if your developer shares a cURL command with you
Method
The type of API request — GET, POST, PUT, PATCH, or DELETE
URL
The external API endpoint the tool will call
Headers
Authentication details — click Add Header to add key-value pairs like an API key
Request Body
For POST and PUT requests, enter the JSON body here. Use {{parameter_name}} to insert collected values
Test API
Sends a test request using your sample values to verify the connection before saving
Got it. The current article has the order wrong — it adds parameters before importing the cURL, but the correct workflow is the other way around. You import the cURL first, understand what parameters are needed from the skeleton it gives you, then create and map them. Let me rewrite just the step-by-step guide section with the correct flow.
How to Set Up an API Tool
Open the AI Agent you want to configure and navigate to the Tools section. Click the AI Tool panel to open it. This is where all your API Tools are created and managed.
Step 1 — Create the Tool
Click the Add Tool button.
Fill in the following fields:
Name — Give the tool a clear name that describes what it does. For example: Book Site Visit or Get Lead By Phone.
Description — Describe when the agent should use this tool. The agent reads this to decide when to trigger it, so be specific.
Type — Select API.
Step 2 — Import from cURL
Click the Import from cURL dropdown and paste the cURL command. The Method, URL, Headers, and a basic skeleton of the request body will be auto-filled automatically.
Once imported, review the skeleton carefully. The request body will show you what fields the API expects — this tells you exactly which parameters you need to create in the next step and whether they are mandatory or optional.
If you do not have a cURL command, you can fill in the Method, URL, and Headers manually.
Step 3 — Create Parameters
Based on what the imported cURL skeleton shows, add the required parameters one by one.
For each parameter, fill in:
Name — Match this exactly to the field name in the API request body.
Type — Select String for text values or Number for numeric values.
Description — Describe what this parameter is, where it is used, and any restrictions or accepted formats. For example: "Visit date in YYYY-MM-DD format" or "Must be a valid property ID from the system."
Required — Mark as required if the API cannot function without this value. Mark as optional only if the API can still return a meaningful response without it.
Step 4 — Map Parameters in the Request Body
Go to the Request Body field and update the JSON skeleton to reference the parameters you just created. Use {{parameter_name}} wherever the API expects a dynamic value.
For example:
Make sure the names inside {{ }} exactly match the parameter names you created in Step 3. A mismatch will cause the API call to fail.
Remember: String values must be wrapped in quotes — "{{visit_date}}". Number values must not be wrapped in quotes — {{customer_id}}.
Step 5 — Add Sample Values
Go back to each parameter and enter a sample value. This is a realistic test value that represents what a customer would provide — for example, 2026-06-15 for a date or 1234 for a customer ID.
These sample values are what the Test API button will use in the next step, so make sure they are accurate and match the correct data type.
Step 6 — Test the API
Click the Test API button. The test runs using the sample values you entered and the {{parameter_name}} notations in the request body. Review the response to confirm the API is returning the expected data.
If the test fails, check for the most common issues — wrong API key in Headers, parameter name mismatch in the Request Body, or incorrect data types in sample values.
Do not save the tool until the test passes successfully.
Step 7 — Save the Tool
Once the test is successful, click Create to save the tool.
After saving, make sure the toggle next to the tool is turned on (green). The agent will not use a tool that is disabled.
In live conversations, the static sample values are automatically replaced by the actual values the agent collects from the customer in real time.
Summary
In this article, you learned how to open the AI Tool panel, what API Tools are and when to use them, how to import a cURL command to auto-fill the connection details, how to add parameters with clear descriptions and limitations, how to use sample values for testing, how to configure the Request Body using {{parameter_name}}, and how to test the API connection before saving. You also saw real examples and common mistakes to avoid.
In the next article, we will cover Unresolved Intents — how to review questions your agent could not answer and improve its knowledge over time.
Last updated