Integrations
Integrations extend your voice agents by connecting to external services. This section covers all available integrations and how to configure them.
Available Integrations
| Integration | Purpose | Status | Plans |
|---|---|---|---|
| Phone Numbers | Phone numbers and calls | Available | All |
| SIP Trunk | Connect existing phone infrastructure | Available | All |
| Google Calendar | Appointment scheduling | Available | All |
| API Keys | External application access | Available | All |
| Webhooks | Real-time event notifications | Available | All |
All Plans
Calendar integrations, SIP, API access, and webhooks are available on all plans, including Free.
Phone Number Setup
Phone numbers allow your agents to receive and make real phone calls.
Setup Steps
- Go to Phone Numbers in the sidebar
- Click "Buy Number"
- Select country and number type
- Complete purchase
- Assign an agent to the number
Numbers are automatically configured and ready to use after purchase.
SIP Trunk Integration
Connect your existing SIP trunk provider to route calls through Hanc.AI voice agents. Available on all plans including Free.
Setup Steps
- Go to Phone Numbers in the sidebar
- Click "Connect SIP"
- Enter your SIP trunk credentials:
- SIP Server / Domain — your provider's SIP address
- Username — your SIP account username
- Password — your SIP account password
- Port — SIP port (default: 5060)
- Click Connect
- Assign an agent to handle calls from this trunk
When to Use SIP
| Scenario | Recommendation |
|---|---|
| New to phone service | Buy numbers through Hanc.AI (simpler setup) |
| Existing PBX system | Use SIP trunk to integrate |
| Enterprise telephony | SIP trunk for full control |
| Multiple providers | SIP for flexibility |
Google Calendar Integration
Connect Google Calendar to enable your voice agents to check availability and book appointments during calls.
Setup Steps
- Go to Integration → Calendars
- Click "Connect Google Calendar"
- Sign in with Google
- Authorize Hanc.AI access
Permissions requested:
- View calendar events (to check availability)
- Create calendar events (to book appointments)
Calendar Configuration
After connecting, configure the calendar tool on your agent:
| Setting | Description |
|---|---|
| calendar_id | Which Google Calendar to use for scheduling |
| timezone | Timezone for appointment scheduling (e.g., Europe/Vienna) |
| work_hours | Available hours for booking (e.g., Monday-Friday 9:00-18:00) |
| slot_duration | Default appointment length (e.g., 30 minutes) |
| buffer | Buffer time between appointments (e.g., 15 minutes) |
Calendar Usage in Agents
Once connected and configured, agents can:
- Check availability for specific dates and times
- Book appointments automatically
- Respect work hours and buffer times
- Handle rescheduling requests
Example conversation:
Customer: "Can I book an appointment for Tuesday at 3pm?"
Agent: [Checks calendar]
"Yes, Tuesday at 3pm is available.
May I have your name to complete the booking?"
API Keys
Generate API keys to integrate Hanc.AI with your own applications.
Creating an API Key
You can create up to 3 API keys per user.
- Go to Integration → API Keys
- Click "Create API Key"
- Enter a name (e.g., "CRM Integration")
- Set permissions (read, write, admin)
- Copy the key immediately (shown only once)
API Key Security
Important
- Store keys securely (environment variables, secrets manager)
- Never commit keys to version control
- Rotate keys periodically
- Delete unused keys
Using API Keys
Include in API requests:
curl -X GET "https://api.hanc.ai/v1/agent/list" \
-H "x-api-key: YOUR_API_KEY"
API Key Permissions
| Permission | Access |
|---|---|
| Read | View agents, calls, analytics |
| Write | Create/modify agents, upload KB |
| Admin | All operations, delete, settings |
Available API Endpoints
| Base URL | https://api.hanc.ai |
| Authentication | API Key via x-api-key header |
| Format | JSON |
Calls
| Action | Method | Endpoint |
|---|---|---|
| List calls | GET | /v1/call/list |
| Call details (transcript, sentiment, summary) | GET | /v1/call/:id |
| General analytics (metrics by date/agent) | GET | /v1/call/general-metrics |
| Daily analytics | GET | /v1/call/daily-metrics |
| Sentiment statistics | GET | /v1/call/sentiment-stats |
| Cost breakdown | GET | /v1/call/costs-breakdown |
| Export calls (CSV) | GET | /v1/call/list/export |
| Export costs (CSV) | GET | /v1/call/costs-breakdown/export |
| Make a phone call | POST | /v1/call/make-phone-call |
| Make a web call | POST | /v1/call/make-web-call |
Agents
| Action | Method | Endpoint |
|---|---|---|
| List agents | GET | /v1/agent/list |
| Agent details | GET | /v1/agent/:id |
| Create agent | POST | /v1/agent |
| Update agent | PATCH | /v1/agent/:id |
| Delete agent | DELETE | /v1/agent/:id |
| Agent call statistics | GET | /v1/agent/:id/call-stats |
| List agent templates | GET | /v1/agent/agent_template/list |
Agent Actions:
| Action | Method | Endpoint |
|---|---|---|
| List actions | GET | /v1/agent/:id/actions |
| Add action | POST | /v1/agent/:id/actions |
| Update action | PATCH | /v1/agent/:id/actions/:actionId |
| Delete action | DELETE | /v1/agent/:id/actions/:actionId |
Agent Tools:
| Action | Method | Endpoint |
|---|---|---|
| List tools | GET | /v1/agent/:id/tools |
| Add tool | POST | /v1/agent/:id/tools |
| Update tool | PATCH | /v1/agent/:id/tools/:toolId |
| Delete tool | DELETE | /v1/agent/:id/tools/:toolId |
Knowledge Base
| Action | Method | Endpoint |
|---|---|---|
| List knowledge bases | GET | /v1/knowledge-base/list |
| Create knowledge base | POST | /v1/knowledge-base |
| Upload file(s) | POST | /v1/knowledge-base/:id/file(s) |
| Delete file | DELETE | /v1/knowledge-base/:id/file |
| Assign agents | PUT | /v1/knowledge-base/:id/agents |
Phone Numbers
| Action | Method | Endpoint |
|---|---|---|
| List numbers | GET | /v1/phone-number/list |
| Available numbers (by country) | GET | /v1/phone-number/available |
| Buy a number | POST | /v1/phone-number/buy |
| Import number | POST | /v1/phone-number/import |
| Connect to SIP | PATCH | /v1/phone-number/connect-to-sip |
Voices
| Action | Method | Endpoint |
|---|---|---|
| List voices | GET | /v1/voice/list |
Filter by language: GET /v1/voice/list?language=de
Subscription
| Action | Method | Endpoint |
|---|---|---|
| Subscription details | GET | /v1/subscription |
| Configure auto top-up | PATCH | /v1/subscription/auto-top-up |
| Set top-up amount | PATCH | /v1/subscription/top-up-amount |
Customers
| Action | Method | Endpoint |
|---|---|---|
| List customers | GET | /v1/customer/list |
| Customer details | GET | /v1/customer/:id |
| Create customer | POST | /v1/customer |
| Update customer | PATCH | /v1/customer/:id |
| Delete customer | DELETE | /v1/customer/:id |
Workspaces
| Action | Method | Endpoint |
|---|---|---|
| Workspace operations | GET/POST/PATCH/DELETE | /v1/workspaces/* |
| Invite member | POST | /v1/workspaces/:id/invite-member |
| Remove member | DELETE | /v1/workspaces/:id/invite-member |
What's Not Available via API
Some operations are only available through the dashboard:
| Feature | Reason |
|---|---|
| API key management | Security — keys can't create other keys |
| Phone number setup | Requires interactive setup |
| Google Calendar integration | Requires interactive authorization |
| Billing & payments | Managed through the dashboard |
Webhooks
Configure webhooks to receive real-time notifications about events in your Hanc.AI account.
Setup
- Go to Integration → Webhooks
- Enter your webhook endpoint URL
- Select events to subscribe to
- Save configuration
Webhooks send HTTP POST requests to your endpoint with event data in JSON format.
Post-Call Actions
Post-call actions trigger automatically after a voice agent conversation ends. Configure these on individual agents.
Available Action Types
| Action | Description |
|---|---|
| Send an email summary of the call (to business owner, customer, or both) | |
| SMS | Send an SMS notification after the call |
| Send a WhatsApp message after the call | |
| API Call | Make an HTTP request to an external endpoint with call data |
Setup
- Go to Voice Agents → select your agent
- Open the Actions tab
- Click "Add Action"
- Select action type and configure:
- Trigger: When the action fires (e.g., after every call, only on specific outcomes)
- Recipients: Who receives the notification
- Content: Message template with call data variables
Custom Integrations
Using the API
Build custom integrations using the Hanc.AI API:
Base URL: https://api.hanc.ai/v1
Authentication: Bearer token (API key)
Format: JSON
API Documentation
See the API Reference for the full list of available endpoints.
Integration Best Practices
Security
- Store credentials securely
- Rotate API keys regularly
- Limit permissions to minimum needed
Reliability
- Log all integration events
- Monitor integration health
Testing
- Test integrations in staging first
- Verify data flow both directions
- Test error scenarios
- Document integration setup
Troubleshooting
Integration won't connect
- Verify credentials are correct
- Check for typos
- Ensure third-party account is active
- Try disconnecting and reconnecting
Calendar not syncing
- Re-authorize calendar access
- Check calendar permissions
- Verify selected calendar is correct
- Check for sync delays (up to 5 minutes)
Related Topics
- Phone Numbers — Phone number management
- Voice Agents — Using integrations in agents
- Analytics — Integration event tracking