mirror of
https://github.com/dograh-hq/dograh.git
synced 2026-06-10 08:05:22 +02:00
115 lines
No EOL
4.1 KiB
Text
115 lines
No EOL
4.1 KiB
Text
---
|
|
title: "Telephony Integration"
|
|
description: "Connect voice agents with telephony providers for inbound and outbound calls"
|
|
---
|
|
|
|
## Overview
|
|
|
|
Dograh AI's telephony integration system provides a unified interface for connecting with various telephony providers. This abstraction layer allows you to easily switch between providers without changing your application logic.
|
|
|
|
## Supported Providers
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Twilio" href="/integrations/telephony/twilio">
|
|
Industry-leading cloud communications platform with global reach
|
|
</Card>
|
|
{/* Additional providers can be added in the future by implementing the TelephonyProvider interface */}
|
|
<Card title="Custom Provider" href="/integrations/telephony/custom">
|
|
Build your own telephony provider integration
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
## Architecture
|
|
|
|
The telephony integration system uses a provider abstraction pattern that ensures consistency across different services:
|
|
|
|
```python
|
|
# All providers implement this interface
|
|
class TelephonyProvider:
|
|
async def initiate_call(to_number, webhook_url, ...)
|
|
async def get_call_status(call_id)
|
|
async def verify_webhook_signature(url, params, signature)
|
|
# ... more methods
|
|
```
|
|
|
|
## Configuration Methods
|
|
|
|
### OSS Deployment (Environment Variables)
|
|
|
|
For self-hosted deployments, configure your telephony provider using environment variables:
|
|
|
|
```bash
|
|
# .env file
|
|
TELEPHONY_PROVIDER=twilio # Required to specify which provider to use
|
|
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
|
TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
|
TWILIO_FROM_NUMBER=+1234567890
|
|
```
|
|
|
|
### SaaS Deployment (Database Configuration)
|
|
|
|
For cloud deployments, configure providers through the web interface:
|
|
|
|
1. Navigate to **Settings** → **Integrations** → **Telephony**
|
|
2. Select your provider
|
|
3. Enter credentials
|
|
4. Test connection
|
|
|
|
## Common Features
|
|
|
|
The telephony integration in Dograh AI supports:
|
|
|
|
- **Outbound Calls**: Initiate calls to any phone number
|
|
- **Call Status Tracking**: Monitor call lifecycle events (initiated, ringing, answered, completed, failed)
|
|
- **WebSocket Streaming**: Real-time audio streaming for voice agents
|
|
- **Webhook Authentication**: Secure webhook signature verification
|
|
|
|
## API Endpoints
|
|
|
|
The telephony system exposes these unified endpoints:
|
|
|
|
| Endpoint | Method | Description |
|
|
|----------|---------|-------------|
|
|
| `/api/v1/telephony/initiate-call` | POST | Start an outbound call |
|
|
| `/api/v1/telephony/status-callback/{id}` | POST | Receive call status updates |
|
|
| `/api/v1/telephony/twiml` | POST | Handle initial webhook |
|
|
| `/api/v1/telephony/ws/{id}` | WebSocket | Real-time audio streaming |
|
|
|
|
## Implementation Status
|
|
|
|
- **Twilio**: ✅ Fully implemented and tested
|
|
- **Custom Providers**: The abstraction layer supports adding new providers by implementing the `TelephonyProvider` interface
|
|
- **API Endpoints**: All telephony operations use the unified `/api/v1/telephony/*` endpoints:
|
|
- `/api/v1/telephony/initiate-call` - Start outbound calls
|
|
- `/api/v1/telephony/status-callback/{id}` - Receive call status updates
|
|
- `/api/v1/telephony/ws/{workflow_id}/{user_id}/{workflow_run_id}` - WebSocket for audio streaming
|
|
|
|
## Troubleshooting
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Calls not connecting">
|
|
- Verify credentials are correctly configured
|
|
- Check phone number format (must include country code)
|
|
- Ensure webhook URLs are publicly accessible
|
|
- Review provider-specific error logs
|
|
</Accordion>
|
|
|
|
<Accordion title="Audio quality issues">
|
|
- Check network bandwidth and latency
|
|
- Verify audio codec compatibility
|
|
- Review WebSocket connection stability
|
|
- Ensure proper audio format (MULAW for Twilio)
|
|
</Accordion>
|
|
|
|
<Accordion title="Webhook signature validation failing">
|
|
- Confirm auth tokens match between provider and configuration
|
|
- Verify webhook URL matches exactly (including parameters)
|
|
- Check for proxy or load balancer modifications
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
## Next Steps
|
|
|
|
- [Set up your first telephony provider](/integrations/telephony/twilio)
|
|
- [Build a custom provider integration](/integrations/telephony/custom)
|
|
- [Configure webhooks and callbacks](/integrations/telephony/webhooks) |