mirror of
https://github.com/dograh-hq/dograh.git
synced 2026-06-10 08:05:22 +02:00
134 lines
No EOL
4.9 KiB
Text
134 lines
No EOL
4.9 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={3}>
|
|
<Card title="Twilio" href="/integrations/telephony/twilio">
|
|
Industry-leading cloud communications platform with global reach
|
|
</Card>
|
|
<Card title="Vonage" href="/integrations/telephony/vonage">
|
|
High-quality voice with 16kHz audio and excellent international coverage
|
|
</Card>
|
|
<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(ABC):
|
|
async def initiate_call(to_number: str, webhook_url: str, workflow_run_id: Optional[int] = None, **kwargs)
|
|
async def get_call_status(call_id: str) -> Dict[str, Any]
|
|
async def get_available_phone_numbers() -> List[str]
|
|
def validate_config() -> bool
|
|
async def verify_webhook_signature(url: str, params: Dict, signature: str) -> bool
|
|
async def get_webhook_response(workflow_id: int, user_id: int, workflow_run_id: int) -> str
|
|
async def get_call_cost(call_id: str) -> Dict[str, Any]
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Dograh AI uses database configuration for all telephony providers. 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
|
|
|
|
## Code Usage
|
|
|
|
Here's how to use the telephony provider in your code:
|
|
|
|
```python
|
|
from api.services.telephony.factory import get_telephony_provider
|
|
|
|
# Get provider based on organization configuration
|
|
provider = await get_telephony_provider(organization_id)
|
|
|
|
# Initiate a call
|
|
result = await provider.initiate_call(
|
|
to_number="+1234567890",
|
|
webhook_url="https://your-domain.com/webhook",
|
|
workflow_run_id=123
|
|
)
|
|
|
|
# Check call status
|
|
status = await provider.get_call_status(result["call_id"])
|
|
|
|
# Get call cost after completion
|
|
cost_info = await provider.get_call_cost(result["call_id"])
|
|
```
|
|
|
|
## 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/webhook/{id}` | GET/POST | Handle initial webhook |
|
|
| `/api/v1/telephony/ws/{id}` | WebSocket | Real-time audio streaming |
|
|
|
|
## Implementation Status
|
|
|
|
- **Twilio**: ✅ Fully implemented and tested
|
|
- **Vonage**: ✅ Fully implemented with 16kHz audio support
|
|
- **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/webhook/{workflow_id}/{user_id}/{workflow_run_id}` - Initial call webhook
|
|
- `/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:
|
|
- Twilio: 8kHz μ-law (MULAW)
|
|
- Vonage: 16kHz Linear PCM
|
|
</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) |