mirror of
https://github.com/dograh-hq/dograh.git
synced 2026-06-10 08:05:22 +02:00
93 lines
No EOL
2.5 KiB
Text
93 lines
No EOL
2.5 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/twiml`
|
|
|
|
**Purpose**: Returns provider-specific instructions (TwiML for Twilio)
|
|
|
|
**Example Response**:
|
|
```xml
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<Response>
|
|
<Connect>
|
|
<Stream url="wss://your-domain/api/v1/telephony/ws/123/456/789" />
|
|
</Connect>
|
|
</Response>
|
|
```
|
|
|
|
### 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}`
|
|
|
|
## 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
|
|
4. Processes status updates to track call lifecycle
|
|
5. Manages WebSocket connections for audio streaming
|
|
|
|
## 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> |