Call API (Webhooks)
Connect your AI agent to external systems through webhooks for advanced integrations. Features a built-in test playground and cURL import.
Real-Time Integration
Send data to your systems instantly during conversations.
Built-in Test Playground
Test your API calls with simulated variables before deploying.
Secure & Reliable
HTTPS support with authentication headers for secure API calls.
Import from cURL
Quickly configure by pasting cURL commands from your API docs.
Overview
The Call API (Webhooks) tool empowers your AI agent to interact with external HTTP REST APIs, enabling it to perform a wide range of actions beyond its default capabilities. By configuring this tool, you can integrate your agent with other systems, automate tasks, and enhance conversations with real-time data.
The Call API tool allows your AI agent to:
- Send Data to External APIs: Collect information during a conversation and send it to an external system.
- Receive and Utilize API Responses: Use data returned from the API call to inform or enhance the ongoing conversation.
- Automate Workflows: Trigger actions in other systems, such as creating support tickets, updating records, or retrieving information.
How Variables Work
Use $variableName in your URL, headers, or body. Add instructions in your agent's prompt telling it what information to collect for each variable. The AI will automatically extract values from the conversation and pass them to this API.
Example: https://api.example.com/orders/$orderId → "Ask for their order ID and pass $orderId to search order tool."
Configuration Parameters
1. Description
A brief explanation of what the tool does. This helps you reference the tool in your instructions.
Example: "Submit Ticket"2. URL
The endpoint URL of the API you want to call.
Example: "https://api.example.com/tickets"3. Method
The HTTP method to use for the request (GET, POST, PUT, DELETE).
Example: "POST"4. Headers
Any custom headers required by the API, such as authentication tokens or content types.
{
"Authorization": "Bearer your_api_token",
"Content-Type": "application/json"
}5. Query String Parameters
Parameters to include in the URL's query string. You can use variables collected from the conversation.
Example: "?email=$email&status=open"6. Body
The request body for POST or PUT requests, formatted as valid JSON. Variables from the conversation can be inserted here.
{
"name": "$name",
"email": "$email",
"message": "$additional_info"
}7. Response Identifiers
Specify keys from the JSON response that the agent can access, using dot notation. This limits the data the agent can use in the conversation.
Example: "ticket_id", "status", "assigned_to.name"How to Use the Call API Tool
Set Up Your API Endpoint
Create an HTTPS endpoint that can receive requests:
// Example Node.js/Express endpoint
app.post('/webhook/echowin', async (req, res) => {
const { variables, conversation } = req.body;
// Process the data
const response = await processData(variables);
// Return response for the AI to use
res.json({
success: true,
message: response
});
});Example Scenario: When a customer wants to submit a support ticket.
Configure the Tool in echowin
Add the Call API tool with your configuration. You can either configure manually or import from a cURL command:
Quick Setup: Import from cURL
If you have a cURL command from your API documentation, simply paste it and click "Import" to automatically populate the URL, method, headers, and body.
curl -X POST 'https://api.example.com/tickets' \
-H 'Authorization: Bearer abc123token' \
-H 'Content-Type: application/json' \
-d '{"name": "$name", "email": "$email"}'Manual Configuration:
- Description: "Submit Ticket"
- URL: "https://api.example.com/tickets"
- Method: "POST"
- Headers:
{
"Authorization": "Bearer abc123token",
"Content-Type": "application/json"
}- Query String Parameters: (Leave blank if not needed)
- Body:
{
"customer_name": "$name",
"customer_email": "$email",
"issue": "$issue_description"
}Test with the Built-in Playground
Use the side-by-side Test Playground to verify your configuration before deploying:
Test Playground Features:
- •Simulate Variables: Enter test values for your $variables to see how they'll be replaced
- •Request Preview: See the exact URL and body that will be sent
- •Live Response: View status code, headers, response time, and body
- •Click-to-Add Response Mapping: Click any key in the JSON response to automatically add it to your response identifiers
Tip: The test playground runs requests through our secure proxy, so you can test APIs without CORS issues directly from the configuration panel.
Write Instructions for Your Agent
Tell your AI agent when and how to call the API:
Instruction Example:
"Collect the caller's name, email, and a description of their issue. Then, use the 'Submit Ticket' tool with variables $name, $email, and $issue_description. Once the ticket is created, inform the caller of their ticket ID."This tells the agent to:
- ✓Collect Information: Gather necessary details from the caller
- ✓Call the API: Use the tool to send data to the external API
- ✓Utilize the Response: Extract specific information from the API response to continue the conversation
Handle the Response
Your API can return data that the AI will use. Use Response Mapping to specify which fields to extract:
{
"success": true,
"message": "Appointment confirmed for John at 3 PM",
"additionalData": {
"confirmationNumber": "APT-12345",
"duration": "30 minutes"
}
}Response Mapping Tip:
In the Test Playground, when you receive a JSON response, you can click on any key to automatically add it to your Response Mapping. This makes it easy to specify exactly which data your agent can access.
Example:
Scenario: Confirming a support ticket
Agent: "Thank you, $name. Your support ticket has been created. Your ticket ID is $ticket_id. Our team will reach out to you shortly."
Examples
Example 1: Checking Order Status
Scenario:
A customer wants to check the status of their order.
Instructions:
- Ask for the customer's order number.
- Use the "Check Order Status" tool with variable $order_number.
- Inform the customer of their order status using the response from the API.
Configuration:
- Description: "Check Order Status"
- URL: "https://api.example.com/orders/status"
- Method: "GET"
- Query String Parameters: "?order_number=$order_number"
- Response Identifiers: "status", "estimated_delivery"
Agent's Dialogue:
Agent: "May I have your order number to check the status?"
Customer: "It's 12345."
(Calls the webhook and receives the response)
Agent: "Your order is currently '$status' and is expected to be delivered on $estimated_delivery."
Example 2: Scheduling an Appointment
Scenario:
A client wants to schedule an appointment.
Instructions:
- Collect the client's name, preferred date, and service required.
- Use the "Schedule Appointment" tool with variables $name, $date, and $service.
- Confirm the appointment details with the client.
Configuration:
- Description: "Schedule Appointment"
- URL: "https://api.example.com/appointments"
- Method: "POST"
- Body:
{
"client_name": "$name",
"appointment_date": "$date",
"service_type": "$service"
}- Response Identifiers: "confirmation_number", "scheduled_time"
Agent's Dialogue:
Agent: "Could you please provide your name?"
Customer: "Alex Johnson."
Agent: "What date would you like to schedule the appointment?"
Customer: "Next Monday."
Agent: "Which service are you interested in?"
Customer: "Haircut."
(Calls the webhook and receives the response)
Agent: "Your appointment is confirmed for $scheduled_time on $date. Your confirmation number is $confirmation_number."
Advanced Webhook Response Handling
When the API returns a JSON response, you can specify which parts of the response the agent can access using response identifiers.
Example Response:
{
"ticket": {
"id": "TICKET123",
"status": "open",
"assigned_to": {
"name": "Support Agent",
"email": "support@example.com"
}
},
"message": "Ticket created successfully."
}Response Identifiers:
- "ticket.id": Accesses the ticket ID
- "ticket.status": Accesses the status of the ticket
- "ticket.assigned_to.name": Accesses the name of the assigned support agent
By specifying these identifiers, you control what information the agent can use, enhancing security and relevance.
Best Practices
🧪 Use the Test Playground
Always test your API configuration using the built-in Test Playground before deploying. Enter sample values for your variables and verify the response matches your expectations. Click on response keys to quickly set up response mapping.
✓ Ensure Valid JSON
The body of POST, PUT, or PATCH requests must be valid JSON. The Monaco editor in the configuration panel will help highlight syntax errors.
🔒 Secure Data Transmission
Use HTTPS URLs and include necessary authentication headers to protect your data during transmission.
📝 Variable Naming
Use clear and consistent variable names (e.g., $orderId, $customerEmail) that match the data being collected. Variables are automatically detected and shown in the Test Playground.
⚠️ Error Handling
Instruct the agent on what to do if the API call fails or returns an error.
Example Instruction: "If the 'Submit Ticket' tool fails, apologize to the caller and inform them that we will follow up via email."📋 Import from cURL
When working with API documentation that provides cURL examples, use the "Import from cURL" feature to quickly configure your tool. This automatically extracts the URL, method, headers, and body from the cURL command.
Advanced Usage
Using Dynamic Query Strings
You can include variables in the query string to pass data via the URL. Your agent already knows a lot of information from the conversation, things like current date and time, caller's caller ID information (if available), callers phone number (if on a phone call) and more.
Example 1:
- URL: "https://api.example.com/findCustomer"
- Query String Parameters: "?phoneNumber=$phone_number&limit=10"
- Instructions: "When the caller wants to know their account balance, find the customer using variables $phone_number"
Example 2:
- URL: "https://api.example.com/search"
- Query String Parameters: "?query=$search_term&limit=10"
Customizing Headers
Include custom headers for APIs that require them, such as:
"X-Custom-Header": "CustomValue"Handling Different HTTP Methods
- GET: Retrieve data without a body
- POST: Send data to create a new resource
- PUT: Update an existing resource
- DELETE: Remove a resource
Ensure the method matches the API's requirements.
Utilizing API Responses to Enhance Conversations
Use the data returned from the API to make the conversation more informative.
Example:
Scenario: Providing real-time stock levels
Agent: "Let me check the availability of that item."
(Calls the webhook and retrieves the stock level)
Agent: "We currently have $stock_quantity units available."
Technical Details
Supported Channels
The Call API tool is available for all communication channels:
HTTP Methods
Supported HTTP methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS.
Note: Request body is only sent for POST, PUT, and PATCH methods.
Response Format
The tool supports JSON responses. HTML or other formats are not recommended as they may not be processed correctly. Use Response Mapping to specify which fields from the JSON response your agent can access.
Variable Replacement
Variables in the format $variable_name are automatically replaced with values collected during the conversation. This works in URLs, headers, query parameters, and request bodies. Variables are automatically detected and displayed in the Test Playground.
Error Logging
All API calls are logged, including successful responses and errors. This helps with debugging and monitoring your integrations.
Summary
The Call API (Webhooks) tool extends your AI agent's functionality by enabling it to interact with external APIs. With features like the built-in Test Playground, cURL import, and click-to-add response mapping, configuring API integrations is faster and more intuitive than ever.
Remember to:
- ✓Use cURL import to quickly configure from API documentation
- ✓Test with the built-in playground before deploying
- ✓Use $variables to capture and pass data dynamically
- ✓Click response keys in the test results to set up response mapping
- ✓Write clear agent instructions explaining when to use the tool
By mastering the Call API tool, you unlock a powerful mechanism to integrate your AI agent with the broader digital ecosystem, enhancing both your operations and customer interactions.
You can visit the Tool Usage guide for a brief overview of all the tools.