Telephony Integration

​

Overview

• Click-to-Call: Initiate calls directly from customer or ticket records
• Automatic Ticket Creation: Create tickets automatically from incoming calls
• Call Logging: Track call history and duration
• Ticket Linking: Associate calls with existing tickets
• Supported Providers: Twilio and Exotel integration

​

Supported Telephony Providers

• Twilio: Popular cloud communications platform
• Exotel: Cloud telephony solution for businesses

​

Prerequisites

bench get-app telephony
bench --site your-site.local install-app telephony

​

Telephony Store Integration

// From desk/src/stores/telephony.ts
interface TelephonyState {
  isLoading: boolean
  isCallingEnabled: boolean
  isTwilioEnabled: boolean
  isExotelEnabled: boolean
  defaultCallingMedium: string
  callMethod: (params: MakeCallParams) => void
  linkDoc: {
    doctype: string
    docname: string
  }
}

​

Call Integration Status

// Fetch integration status
await fetchCallIntegrationStatus()

// Check if calling is enabled
if (isCallingEnabled) {
  // Show call buttons
}

​

Making Calls

​

Click-to-Call from Tickets

​

Making Calls Programmatically

import { useTelephonyStore } from '@/stores/telephony'

const telephony = useTelephonyStore()

// Make a call to a number
telephony.makeCall({
  number: '+1234567890'
})

// Make a call linked to a ticket
telephony.makeCall({
  number: '+1234567890',
  doctype: 'HD Ticket',
  docname: 'TICKET-00001'
})

​

Call Method Configuration

// Set the call method
telephony.setMakeCall((params) => {
  // Your call implementation
  console.log('Making call to:', params.number)
})

// Set default calling medium
telephony.setDefaultCallingMedium('Twilio')

​

Linking Calls to Documents

​

Link to Ticket

// Set document to link
telephony.setLinkDoc({
  doctype: 'HD Ticket',
  docname: 'TICKET-00001'
})

// Make the call
telephony.makeCall({
  number: customerPhone
})

​

Link to Customer

telephony.setLinkDoc({
  doctype: 'HD Customer',
  docname: customer.name
})

​

Call Handling

​

Incoming Calls

1. Caller Identification: System looks up phone number
2. Customer Match: Finds existing customer record
3. Ticket Creation: Creates new ticket if configured
4. Agent Notification: Alerts available agents
5. Call Routing: Routes to appropriate agent

​

Call Recording

• Calls are automatically recorded
• Recordings are stored with the call log
• Playback available from ticket or customer record
• Compliance with local recording laws required

​

Call Notes

• During Call: Real-time note taking
• After Call: Wrap-up notes and disposition
• Ticket Update: Notes are added to ticket communication

​

Call Area Component

• Call Status: Active, ringing, completed
• Timer: Call duration tracking
• Controls: Mute, hold, transfer, hang up
• Notes: Quick note-taking interface

​

Configuration

​

Telephony Settings

1. Provider: Select Twilio or Exotel
2. Credentials: Enter API keys and tokens
3. Phone Numbers: Configure your telephony numbers
4. Call Recording: Enable/disable recording
5. IVR Settings: Set up interactive voice response

​

Helpdesk Integration

1. Enable Call Support: Activate telephony features
2. Default Calling Medium: Set preferred provider
3. Auto-Create Tickets: Configure automatic ticket creation
4. Call Disposition: Set up call outcome categories

​

Checking Integration Status

const telephony = useTelephonyStore()
console.log('Calling enabled:', telephony.isCallingEnabled)
console.log('Twilio enabled:', telephony.isTwilioEnabled)
console.log('Exotel enabled:', telephony.isExotelEnabled)

await telephony.fetchCallIntegrationStatus()

​

Best Practices

​

Call Handling

1. Train Agents: Ensure team knows how to use telephony features
2. Call Scripts: Provide templates for common scenarios
3. Quick Notes: Encourage note-taking during calls
4. Follow Up: Create follow-up tasks for complex calls
5. Customer Verification: Always verify caller identity

​

Integration

1. Test Thoroughly: Verify calls work before going live
2. Monitor Quality: Track call quality metrics
3. Recording Compliance: Ensure legal compliance for recordings
4. Backup Plan: Have fallback for telephony outages
5. Regular Testing: Periodically test integration

​

Performance

1. Network Quality: Ensure stable internet connection
2. Headset Quality: Use quality headsets for best experience
3. Browser Compatibility: Test on supported browsers
4. Load Testing: Verify system handles expected call volume

​

Troubleshooting

​

Calls Not Working

1. Verify Telephony app is installed
2. Check provider credentials are correct
3. Ensure phone numbers are configured
4. Check browser permissions for microphone
5. Verify firewall allows WebRTC traffic

​

Integration Not Detected

1. Check Telephony app is installed and enabled
2. Verify provider is configured
3. Call fetchCallIntegrationStatus() to refresh
4. Check API endpoint is accessible
5. Review server logs for errors

​

Call Quality Issues

1. Check internet connection speed and stability
2. Use wired connection instead of WiFi
3. Close bandwidth-heavy applications
4. Test with different browser
5. Contact provider for network diagnostics

​

Calls Not Linking to Tickets

1. Verify setLinkDoc() is called before makeCall()
2. Check doctype and docname are correct
3. Review call log creation
4. Check permissions for call log creation

​

Limitations

• Requires separate Frappe Telephony app installation
• Limited to Twilio and Exotel providers
• Browser must support WebRTC for browser-based calling
• Recording storage depends on provider limits

​

Related Resources

• Ticket Management
• Email Integration
• Frappe Telephony Documentation