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
Twilio	Phone numbers and calls	Available
API Keys	External application access	Available
Webhooks	Real-time event notifications	Available
Google Calendar	Appointment scheduling	Available
Microsoft Outlook	Appointment scheduling	Available
Cal.com	Appointment scheduling	Available
CRM Systems	Customer data	Coming soon

Twilio Integration

Twilio provides the phone infrastructure for voice calls.

Setup Steps

Create Twilio Account (if needed)
- Go to twilio.com
- Sign up for an account
- Complete verification
Get Credentials
- Log into Twilio Console
- Copy Account SID
- Copy Auth Token
Connect to Hanc.AI
- Go to Integration → Twilio
- Enter Account SID
- Enter Auth Token
- Click Connect
Import Numbers
- After connecting, your Twilio numbers appear
- Click Import to add them to Hanc.AI
- Assign agents to numbers

Twilio Configuration

┌─────────────────────────────────────────────────────────────────┐
│                  TWILIO INTEGRATION                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Account SID:  AC________________________________               │
│                                                                 │
│  Auth Token:   ________________________________                 │
│                                                                 │
│  Status:       ● Connected                                      │
│                                                                 │
│  [Disconnect]  [Refresh Numbers]                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Troubleshooting Twilio

Issue	Solution
Connection fails	Verify credentials are correct
Numbers not appearing	Click "Refresh Numbers"
Calls not routing	Check number webhook in Twilio

API Keys

Generate API keys to integrate Hanc.AI with your own applications.

Creating an API Key

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/agents" \
  -H "Authorization: Bearer YOUR_API_KEY"

API Key Permissions

Permission	Access
Read	View agents, calls, analytics
Write	Create/modify agents, upload KB
Admin	All operations, delete, settings

Webhooks

Webhooks send real-time notifications when events occur.

Setting Up Webhooks

Go to Integration → Webhooks
Click "Add Webhook"
Enter your endpoint URL
Select events to trigger
Save and test

Available Events

Event	Trigger	Payload Includes
`call.started`	Call begins	Agent ID, caller number
`call.ended`	Call completes	Duration, transcript, sentiment
`call.transferred`	Transfer to human	Reason, destination
`appointment.created`	Booking made	Date, time, customer info
`appointment.cancelled`	Booking cancelled	Reason, customer info

Webhook Payload Example

{
  "event": "call.ended",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": {
    "call_id": "call_abc123",
    "agent_id": "agent_xyz789",
    "duration_seconds": 185,
    "caller_number": "+43664123456",
    "sentiment": "positive",
    "transcript": "...",
    "escalated": false
  }
}

Webhook Security

Validate webhook signatures:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === expected;
}

Calendar Integrations

Connect calendars for appointment booking.

Google Calendar

Go to Integration → Calendars
Click "Connect Google Calendar"
Sign in with Google
Authorize Hanc.AI access
Select calendars to sync

Permissions requested:

View calendar events
Create calendar events
Modify calendar events

Microsoft Outlook

Go to Integration → Calendars
Click "Connect Outlook"
Sign in with Microsoft
Authorize access
Select calendars

Cal.com

Go to Integration → Calendars
Click "Connect Cal.com"
Enter API key from Cal.com
Configure event types

Calendar Usage in Agents

Once connected, agents can:

Check availability for specific times
Book appointments automatically
Send calendar invitations
Handle rescheduling

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?"

CRM Integration (Coming Soon)

Connect customer relationship management systems:

Planned CRMs

HubSpot
Salesforce
Pipedrive
Zoho CRM

Planned Features

Automatic call logging
Customer data lookup
Lead creation
Activity tracking

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

Endpoints available:

Endpoint	Method	Purpose
`/agents`	GET	List all agents
`/agents/{id}`	GET	Get agent details
`/agents`	POST	Create agent
`/calls`	GET	List call logs
`/calls/{id}`	GET	Get call details
`/knowledge-bases`	GET	List knowledge bases
`/knowledge-bases`	POST	Create knowledge base

Example: Create Agent via API

curl -X POST "https://api.hanc.ai/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "first_message": "Hello, how can I help?",
    "prompt": "You are a helpful support agent...",
    "language": "en",
    "provider": "openai",
    "model": "gpt-4o"
  }'

Integration Best Practices

Security

✅ Use HTTPS for all webhooks ✅ Store credentials securely ✅ Rotate API keys regularly ✅ Limit permissions to minimum needed

Reliability

✅ Handle webhook failures gracefully ✅ Implement retry logic ✅ 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

Webhooks not receiving events

Verify URL is accessible publicly
Check URL returns 200 status
Review webhook logs in dashboard
Test with webhook.site for debugging

Calendar not syncing

Re-authorize calendar access
Check calendar permissions
Verify selected calendar is correct
Check for sync delays (up to 5 minutes)

Phone Numbers — Twilio number management
Voice Agents — Using integrations in agents
Analytics — Integration event tracking

Available Integrations​

Twilio Integration​

Setup Steps​

Twilio Configuration​

Troubleshooting Twilio​

API Keys​

Creating an API Key​

API Key Security​

Using API Keys​

API Key Permissions​

Webhooks​

Setting Up Webhooks​

Available Events​

Webhook Payload Example​

Webhook Security​

Calendar Integrations​

Google Calendar​

Microsoft Outlook​

Cal.com​

Calendar Usage in Agents​

CRM Integration (Coming Soon)​

Planned CRMs​

Planned Features​

Custom Integrations​

Using the API​

API Documentation​

Example: Create Agent via API​

Integration Best Practices​

Security​

Reliability​

Testing​

Troubleshooting​

Integration won't connect​

Webhooks not receiving events​

Calendar not syncing​

Related Topics​