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

All Plans

Calendar integrations (Google Calendar, Microsoft Outlook, Cal.com), SIP, and outbound calling are available on all plans, including Free.

---

Twilio Integration

Twilio provides the phone infrastructure for voice calls.

Setup Steps

1. Create Twilio Account (if needed)

   • Go to twilio.com
   • Sign up for an account
   • Complete verification

2. Get Credentials

   • Log into Twilio Console
   • Copy Account SID
   • Copy Auth Token

3. Connect to Hanc.AI

   • Go to Integration → Twilio
   • Enter Account SID
   • Enter Auth Token
   • Click Connect

4. Import Numbers

   • After connecting, your Twilio numbers appear
   • Click Import to add them to Hanc.AI
   • Assign agents to numbers

Twilio Configuration

Field	Value
Account SID	AC________________________________
Auth Token	________________________________
Status	🟢 Connected

Actions: [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

---

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

1. Go to Phone Numbers in the sidebar
2. Click "Connect SIP"
3. 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)
4. Click Connect
5. Assign an agent to handle calls from this trunk

When to Use SIP

Scenario	Recommendation
New to phone service	Use Twilio (simpler setup)
Existing PBX system	Use SIP trunk to integrate
Enterprise telephony	SIP trunk for full control
Multiple providers	SIP for flexibility

---

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.

1. Go to Integration → API Keys
2. Click "Create API Key"
3. Enter a name (e.g., "CRM Integration")
4. Set permissions (read, write, admin)
5. 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

1. Go to Integration → Webhooks
2. Click "Add Webhook"
3. Enter your endpoint URL
4. Select events to trigger
5. Save and test

Available Events

Webhook 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

Widget events (for JavaScript integration on your website):

Event	Trigger
call-start	Web widget call begins
call-end	Web widget call ends

Widget Events

The web widget emits only two events: call-start and call-end. Use these for custom UI behavior on your website. See Widgets for integration details.

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

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

Permissions requested:

• View calendar events
• Create calendar events
• Modify calendar events

Microsoft Outlook

1. Go to Integration → Calendars
2. Click "Connect Outlook"
3. Sign in with Microsoft
4. Authorize access
5. Select calendars

Cal.com

1. Go to Integration → Calendars
2. Click "Connect Cal.com"
3. Enter API key from Cal.com
4. 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"
  }'

---

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

1. Verify credentials are correct
2. Check for typos
3. Ensure third-party account is active
4. Try disconnecting and reconnecting

Webhooks not receiving events

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

Calendar not syncing

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

---

Related Topics

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