mirror of
https://github.com/dograh-hq/dograh.git
synced 2026-06-07 07:55:16 +02:00
117 lines
No EOL
3.1 KiB
Text
117 lines
No EOL
3.1 KiB
Text
---
|
|
title: "Webhooks and Callbacks"
|
|
description: "How Dograh AI handles telephony webhooks and audio streaming"
|
|
---
|
|
|
|
## Overview
|
|
|
|
Dograh AI uses webhooks to communicate with telephony providers for call events and audio streaming. Webhooks are automatically configured when you initiate calls.
|
|
|
|
## Webhook Types
|
|
|
|
### 1. Initial Call Webhook
|
|
|
|
When a call is initiated, the telephony provider requests instructions.
|
|
|
|
**Endpoint**: `/api/v1/telephony/webhook/{workflow_id}/{user_id}/{workflow_run_id}`
|
|
|
|
**Purpose**: Returns provider-specific instructions
|
|
|
|
<Tabs>
|
|
<Tab title="Twilio (TwiML)">
|
|
```xml
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<Response>
|
|
<Connect>
|
|
<Stream url="wss://your-domain/api/v1/telephony/ws/123/456/789" />
|
|
</Connect>
|
|
</Response>
|
|
```
|
|
</Tab>
|
|
<Tab title="Vonage (NCCO)">
|
|
```json
|
|
[
|
|
{
|
|
"action": "connect",
|
|
"endpoint": [{
|
|
"type": "websocket",
|
|
"uri": "wss://your-domain/api/v1/telephony/ws/123/456/789",
|
|
"content-type": "audio/l16;rate=16000"
|
|
}]
|
|
}
|
|
]
|
|
```
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
### 2. Status Callback
|
|
|
|
Receives call lifecycle events.
|
|
|
|
**Endpoint**: `/api/v1/telephony/status-callback/{workflow_run_id}`
|
|
|
|
**Events Tracked**:
|
|
- `initiated` - Call request received
|
|
- `ringing` - Call is ringing
|
|
- `answered` - Call was answered
|
|
- `completed` - Call ended normally
|
|
- `busy` - Line was busy
|
|
- `no-answer` - Call not answered
|
|
- `failed` - Call failed
|
|
|
|
### 3. WebSocket Audio Stream
|
|
|
|
Real-time audio streaming for voice interaction.
|
|
|
|
**Endpoint**: `/api/v1/telephony/ws/{workflow_id}/{user_id}/{workflow_run_id}`
|
|
|
|
**Audio Formats**:
|
|
- **Twilio**: 8kHz μ-law (MULAW), Base64-encoded in JSON messages
|
|
- **Vonage**: 16kHz Linear PCM, Binary frames
|
|
|
|
## How It Works
|
|
|
|
Dograh AI automatically:
|
|
1. Constructs webhook URLs based on your deployment
|
|
2. Passes them to the telephony provider when initiating calls
|
|
3. Verifies webhook signatures for security:
|
|
- **Twilio**: HMAC-SHA1 signature validation
|
|
- **Vonage**: JWT token verification
|
|
4. Processes status updates to track call lifecycle
|
|
5. Manages WebSocket connections for audio streaming
|
|
6. Handles provider-specific audio formats and protocols
|
|
|
|
## Local Development
|
|
|
|
For local development, use the built-in Cloudflare tunnel:
|
|
|
|
```yaml
|
|
# docker-compose.yml includes:
|
|
cloudflared:
|
|
image: cloudflare/cloudflared:latest
|
|
command: tunnel --no-autoupdate --url http://api:8000
|
|
```
|
|
|
|
The tunnel URL is automatically detected and used for webhooks.
|
|
|
|
## Troubleshooting
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Webhook URL not accessible">
|
|
- Verify your domain/tunnel URL is publicly accessible
|
|
- Check firewall rules allow incoming HTTPS traffic
|
|
- Test with `curl` from external network
|
|
</Accordion>
|
|
|
|
<Accordion title="WebSocket connection dropping">
|
|
- Check WebSocket upgrade headers are preserved
|
|
- Verify no timeout on load balancer/proxy
|
|
- Monitor for memory/CPU constraints
|
|
</Accordion>
|
|
|
|
<Accordion title="Status callbacks not received">
|
|
- Verify workflow_run_id is included in URL
|
|
- Check provider console for webhook errors
|
|
- Review webhook retry logs
|
|
</Accordion>
|
|
</AccordionGroup> |