Overview
API integration allows your voice agents to interact with external systems, fetch data, and perform actions beyond conversation. Hamsa’s tool system makes it easy to connect to any HTTP API, enabling powerful workflows like looking up customer data, creating tickets, sending notifications, and more.What You Can Do with API Integration:
- Look up customer information from your CRM
- Create and update tickets in your helpdesk
- Check inventory and availability
- Process orders and payments
- Send emails, SMS, and notifications
- Update databases and systems
- Verify account credentials
- Access any HTTP/REST API
Tool System Basics
What Are Tools?
Tools are reusable API configurations that your agents can call during conversations. Think of them as functions your agent can execute. Tool Components:- Name & Description - What the tool does
- HTTP Method - GET, POST, PUT, DELETE, PATCH
- URL - API endpoint (supports path parameters)
- Authentication - API keys, bearer tokens
- Headers - Custom HTTP headers
- Parameters - JSON schema defining inputs
- Messages - What agent says during execution
Creating Your First Tool
Let’s create a tool to look up customer information.Using Tools in Agents
In Flow Agents
Add tools to your conversation flow using Tool Nodes. Example: Customer Lookup FlowIn Single Prompt Agents
Add tools to configuration, agent decides when to call them.API Patterns
GET Requests - Retrieving Data
Fetch information from your systems. Example: Get Order StatusPOST Requests - Creating Data
Create new records in your systems. Example: Create Support TicketPUT/PATCH Requests - Updating Data
Modify existing records. Example: Update Customer PreferencesDELETE Requests - Removing Data
Delete records (use with caution). Example: Cancel AppointmentAdvanced Patterns
Chained API Calls
Call multiple APIs in sequence. Example: Order Fulfillment ChainConditional Tool Execution
Execute tools based on conditions.Error Handling & Retries
Handle API failures gracefully.Async Tool Execution
For long-running operations.Authentication Methods
Bearer Token (JWT)
Most common for modern APIs.API Key in Header
Common for older APIs.No Authentication
For public APIs.Custom Authentication
Use headers for custom schemes.Parameter Schemas
Basic Types
String Parameter:Complex Types
Object Parameter:Using Variables in Parameters
Map conversation variables to API parameters.Path Parameters
Use dynamic URL segments. URL Template:Response Handling
Using API Responses
Tool responses become available as variables. API Response:Response Validation
Check API responses before using.Complete Integration Examples
Example 1: CRM Customer Lookup & Update
Example 2: E-commerce Order Management
Example 3: Appointment Scheduling System
Best Practices
Clear Descriptions
Write detailed tool descriptions so LLM knows when to use them
Set Appropriate Timeouts
Fast APIs: 5-10s, Slow APIs: 15-30s, Use async for 30s+
Handle Errors Gracefully
Plan for API failures, timeouts, and unexpected responses
Validate Inputs
Use parameter schemas to ensure correct data types
Secure Credentials
Never hardcode API keys, use environment variables
Use Path Parameters
For RESTful URLs like /customers/:id/orders/:orderId
Test Thoroughly
Test with real API calls, not just mock data
Monitor Usage
Track API call success rates and latencies
Troubleshooting
Tool Not Being Called
Tool Not Being Called
Check:
- Tool description is clear about when to use it
- Tool is added to agent configuration
- Agent prompt mentions the tool
- Conversation provides context for tool use
- Improve tool description
- Add explicit examples to prompt
- Mention tool capabilities in greeting
API Call Failing
API Call Failing
Check:
- URL is correct and accessible
- Authentication credentials are valid
- Required parameters are provided
- Headers are correctly formatted
- Firewall/network allows requests
- Test API with curl or Postman
- Check API response in call logs
- Verify parameter values in logs
- Check for CORS issues
Wrong Parameters Passed
Wrong Parameters Passed
Check:
- Variable names match exactly
- Variables are populated before tool call
- Parameter schema is correct
- Data types match expectations
- Verify variable extraction works
- Check variable values in call logs
- Add validation before tool call
- Use correct variable syntax:
Timeout Issues
Timeout Issues
Check:
- API response time
- Timeout setting in tool config
- Network latency
- Increase timeout value
- Optimize API performance
- Use async mode for slow operations
- Add retry logic
Security Best Practices
Secure Integration Checklist:- Use HTTPS for all API endpoints
- Store credentials in secure vault
- Use API keys with minimal required permissions
- Implement rate limiting
- Validate all inputs
- Sanitize outputs before speaking
- Log API calls for auditing
- Monitor for unusual patterns
- Set up alerts for failures