diff --git a/docs/docs.json b/docs/docs.json index 198fa24..c4e3a2b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -85,9 +85,11 @@ "group": "Telephony", "pages": [ "integrations/telephony/overview", + "integrations/telephony/inbound", "integrations/telephony/twilio", "integrations/telephony/vonage", "integrations/telephony/cloudonix", + "integrations/telephony/vobiz", "integrations/telephony/webhooks", "integrations/telephony/custom" ] diff --git a/docs/images/cloudonix-inbound-config-1.png b/docs/images/cloudonix-inbound-config-1.png new file mode 100644 index 0000000..d7e8ee9 Binary files /dev/null and b/docs/images/cloudonix-inbound-config-1.png differ diff --git a/docs/images/cloudonix-inbound-config-2.png b/docs/images/cloudonix-inbound-config-2.png new file mode 100644 index 0000000..f0ee137 Binary files /dev/null and b/docs/images/cloudonix-inbound-config-2.png differ diff --git a/docs/images/twilio-inbound-config.png b/docs/images/twilio-inbound-config.png new file mode 100644 index 0000000..a0bb2c5 Binary files /dev/null and b/docs/images/twilio-inbound-config.png differ diff --git a/docs/images/vobiz-inbound-config-1.png b/docs/images/vobiz-inbound-config-1.png new file mode 100644 index 0000000..395fc14 Binary files /dev/null and b/docs/images/vobiz-inbound-config-1.png differ diff --git a/docs/images/vobiz-inbound-config-2.png b/docs/images/vobiz-inbound-config-2.png new file mode 100644 index 0000000..baf2fd0 Binary files /dev/null and b/docs/images/vobiz-inbound-config-2.png differ diff --git a/docs/images/vobiz-inbound-config-3.png b/docs/images/vobiz-inbound-config-3.png new file mode 100644 index 0000000..2b09bc2 Binary files /dev/null and b/docs/images/vobiz-inbound-config-3.png differ diff --git a/docs/integrations/telephony/cloudonix.mdx b/docs/integrations/telephony/cloudonix.mdx index a2ec9f2..612c628 100644 --- a/docs/integrations/telephony/cloudonix.mdx +++ b/docs/integrations/telephony/cloudonix.mdx @@ -54,22 +54,65 @@ Watch this step-by-step guide to set up Cloudonix with Dograh AI: 2. Click "Test Call" to verify connection 3. Check call logs for successful connection -## How It Works +## Inbound Calling Setup -### Outbound Calling -When you initiate a call through Dograh AI: -1. The system selects a phone number from your configured pool -2. Cloudonix places the call to your recipient, via a pre-configured Cloudonix outbound voice trunk -3. Once connected, audio streams through WebSocket for real-time voice interaction -4. Call status updates are tracked throughout the lifecycle +The Dograh AI configuration for inbound calling is **identical** to outbound calling - use the same credentials configured above. However, you need additional setup in your Cloudonix Console to route incoming calls to Dograh AI. +### Configure Inbound Trunk and Application -## Campaign Features +1. **Set Up Inbound Trunk**: + - Log in to your [Cloudonix Console](https://cockpit.cloudonix.io) + - Navigate to **Trunks** → **Create Inbound Trunk** + - Configure your inbound trunk with your voice service provider + - Ensure the trunk can receive calls to your desired phone numbers -When using Cloudonix with campaigns: -- **Rate Limiting**: Enforced per organization to prevent overwhelming -- **Automatic Retry**: Failed calls (busy/no-answer) are retried automatically -- **Concurrent Call Management**: System manages call slots to optimize throughput +2. **Create Application for Your Domain**: + - Select your domain in the Cloudonix Console + + Cloudonix console showing domain selection + Cloudonix console showing domain selection + + - Create a new application for your domain + - Set the webhook URL in the application: + ``` + https://api.dograh.com/api/v1/telephony/inbound/{workflow_id} + ``` + + + Replace `{workflow_id}` with your actual workflow ID. If using self-hosted Dograh, replace `api.dograh.com` with your domain. + + + Cloudonix application creation with webhook URL configuration + Cloudonix application creation with webhook URL configuration + +3. **Verify Configuration**: + - Ensure your Dograh AI instance is publicly accessible + - Test that webhook URL responds correctly + - Verify any firewalls allow Cloudonix's IP ranges + - Confirm your inbound trunk is active and receiving calls + +### Test Inbound Calling + +1. Call your configured phone number from another phone +2. Verify your Dograh AI voice agent answers and responds +3. Check call logs in both Dograh AI dashboard and Cloudonix Console +4. Confirm clear two-way audio communication ## Troubleshooting @@ -89,6 +132,20 @@ When using Cloudonix with campaigns: - Check firewall rules for WebSocket traffic - Ensure audio pipeline is configured correctly + + + - Verify inbound trunk is properly configured and active + - Check routing rules point to correct Dograh AI webhook endpoint + - Ensure webhook URLs are publicly accessible + - Confirm phone numbers are correctly routed to your trunk + + + + - Verify organization_id in webhook URLs matches your setup + - Check that voice agent workflow is properly configured + - Ensure SIP connection instructions are correctly returned + - Review webhook logs for error responses + ## Best Practices diff --git a/docs/integrations/telephony/inbound.mdx b/docs/integrations/telephony/inbound.mdx new file mode 100644 index 0000000..b087749 --- /dev/null +++ b/docs/integrations/telephony/inbound.mdx @@ -0,0 +1,168 @@ +--- +title: "Inbound Calling" +description: "Configure inbound calling for Twilio, Vonage, and Cloudonix providers in Dograh AI" +--- + +## Overview + +Dograh AI supports inbound calling across all supported telephony providers. When someone calls your configured phone number, your voice agent automatically answers and handles the interaction. The inbound calling configuration in Dograh AI uses the same telephony settings as outbound calling. + +## Supported Providers for Inbound Calls + + + + Industry-leading platform with robust inbound call handling + + + SIP-based inbound calling with flexible trunk configuration + + + Cloud-based telephony with global reach and competitive pricing + + + + +**Vonage**: Inbound calling support is coming soon. Currently supports outbound calling only. + + +## How Inbound Calling Works + +When someone calls your configured phone number: + +1. **Call Received**: The telephony provider receives the incoming call +2. **Webhook Triggered**: The provider sends a webhook to Dograh AI +3. **Agent Activated**: Dograh AI activates your configured voice agent workflow +4. **Audio Streaming**: Real-time audio streams between caller and agent via WebSocket +5. **Conversation Handled**: Your voice agent manages the entire conversation + +## Configuration in Dograh AI + +Setting up inbound calling requires three simple steps: + +### Step 1: Configure Telephony Provider + +The telephony configuration for inbound calling is **identical** to outbound calling. Follow the **Configuration** section in your provider's documentation page: + +- [Twilio Configuration](/integrations/telephony/twilio#configuration) +- [Cloudonix Configuration](/integrations/telephony/cloudonix#configuration) +- [Vobiz Configuration](/integrations/telephony/vobiz#configuration) + +### Step 2: Get Your Workflow Webhook URL + +1. **Find Your Workflow ID**: + - Navigate to your workflow page (e.g., `https://app.dograh.com/workflow/3`) + - Note the workflow ID from the URL (in this example: `3`) + +2. **Construct Webhook URL**: + ``` + https://api.dograh.com/api/v1/telephony/inbound/{workflow_id} + ``` + + For example, if your workflow ID is `3`: + ``` + https://api.dograh.com/api/v1/telephony/inbound/3 + ``` + + + If you're using a self-hosted Dograh instance, replace `api.dograh.com` with your own domain. + + +### Step 3: Configure Provider-Specific Inbound Settings + +Each telephony provider requires additional configuration to route incoming calls to your Dograh AI webhook. Follow the provider-specific inbound setup instructions: + +- [Twilio Inbound Setup](/integrations/telephony/twilio#inbound-calling-setup) +- [Vonage Inbound Setup](/integrations/telephony/vonage#inbound-calling-setup) +- [Cloudonix Inbound Setup](/integrations/telephony/cloudonix#inbound-calling-setup) +- [Vobiz Inbound Setup](/integrations/telephony/vobiz#inbound-calling-setup) + + +## Testing Inbound Calls + +After completing both the Dograh AI configuration and provider-specific setup: + +1. **Test Call**: Call your configured phone number from another phone +2. **Verify Connection**: Ensure your voice agent answers and responds appropriately +3. **Check Logs**: Monitor call logs in both Dograh AI and your provider's dashboard +4. **Audio Quality**: Verify clear two-way audio communication + +## Troubleshooting Common Issues + + + + - Verify webhook URLs are correctly configured at your provider + - Check that webhook endpoints are publicly accessible + - Ensure phone numbers are properly linked to your application + + + + - Confirm your voice agent workflow is properly configured + - Check webhook signature validation is working + - Verify WebSocket connections are established successfully + + + + - **Error**: "Configuration error: This phone number is configured for a different telephony provider" + - **Solution**: Check your dashboard settings and update your webhook URL configuration to match the correct provider + - Ensure the phone number is configured for the same provider in both Dograh AI and your telephony console + + + + - **Error**: "Workflow not found" + - **Solution**: Verify the workflow ID in your webhook URL is correct and the workflow exists in your dashboard + - Double-check the webhook URL format: `https://api.dograh.com/api/v1/telephony/inbound/{workflow_id}` + + + + - **Error**: "Authentication error: Account credentials do not match" + - **Solution**: Verify your account SID/credentials configuration in Dograh AI matches your telephony provider settings + - Re-enter your provider credentials in the telephony configuration page + + + + - **Error**: "Phone number not configured: This number is not set up for inbound calls" + - **Solution**: Add this phone number to your telephony configuration in Dograh AI + - Ensure the phone number is properly linked to your provider account + + + + - **Error**: "Security error: Webhook signature validation failed" + - **Solution**: Verify your auth token configuration in Dograh AI matches your provider settings + - Ensure webhook requests are coming from your telephony provider's verified IP ranges + - Check that your webhook URL is accessible and responding correctly + + + + - **Error**: "Service temporarily unavailable: Your account has exceeded usage limits" + - **Solution**: Contact your administrator or upgrade your plan to continue receiving calls + - Check your provider account billing and usage limits + + + + - **Error**: "Authentication failed" + - **Solution**: Check your webhook URL configuration and ensure your telephony provider settings match your dashboard configuration + - Verify all credentials are entered correctly and haven't expired + - Test the webhook URL is publicly accessible from your provider's servers + + + + - Check network bandwidth and latency from provider to Dograh AI + - Verify audio pipeline configuration matches provider requirements + - Review WebSocket connection stability + + + +## Best Practices + +- **Single Configuration**: Use the same telephony configuration for both inbound and outbound calls +- **Testing**: Always test inbound calling after configuration changes +- **Monitoring**: Monitor both Dograh AI logs and provider dashboards for call analytics +- **Backup Numbers**: Configure multiple phone numbers for redundancy +- **Security**: Ensure webhook signature verification is enabled for security + +## Next Steps + +1. Choose your telephony provider and complete the basic configuration +2. Follow the provider-specific setup instructions (to be detailed) +3. Test your inbound calling setup +4. Configure your voice agent workflow for optimal caller experience \ No newline at end of file diff --git a/docs/integrations/telephony/twilio.mdx b/docs/integrations/telephony/twilio.mdx index 6ca849b..4b7b74d 100644 --- a/docs/integrations/telephony/twilio.mdx +++ b/docs/integrations/telephony/twilio.mdx @@ -54,22 +54,47 @@ Watch this step-by-step guide to set up Twilio with Dograh AI: 2. Click "Test Call" to verify connection 3. Check call logs for successful connection -## How It Works +## Inbound Calling Setup -### Outbound Calling -When you initiate a call through Dograh AI: -1. The system selects a phone number from your configured pool -2. Twilio places the call to your recipient -3. Once connected, audio streams through WebSocket for real-time voice interaction -4. Call status updates are tracked throughout the lifecycle +To enable inbound calling with Twilio: +1. **Complete Telephony Configuration**: Use the same [Configuration](#configuration) steps above +2. **Get Your Workflow Webhook URL**: Find your workflow ID and construct the webhook URL as: `https://api.dograh.com/api/v1/telephony/inbound/{workflow_id}` -## Campaign Features +### Configure Webhook in Twilio Console -When using Twilio with campaigns: -- **Rate Limiting**: Enforced per organization to prevent overwhelming -- **Automatic Retry**: Failed calls (busy/no-answer) are retried automatically -- **Concurrent Call Management**: System manages call slots to optimize throughput +1. **Configure Phone Number Webhook**: + - Go to **Phone Numbers** → **Manage** → **Active Numbers** in Twilio Console + - Click on the phone number you want to use for inbound calls + - In the "Voice Configuration" section: + - Set **Webhook** to: `https://api.dograh.com/api/v1/telephony/inbound/{workflow_id}` + - Set **HTTP Method** to: `POST` + - Click **Save Configuration** + + + Replace `{workflow_id}` with your actual workflow ID. If using self-hosted Dograh, replace `api.dograh.com` with your domain. + + + Twilio phone number voice configuration showing webhook URL setup for inbound calls + Twilio phone number voice configuration showing webhook URL setup for inbound calls + +2. **Verify Setup**: + - Ensure your Dograh AI instance is publicly accessible + - Verify any firewalls allow Twilio's IP ranges + +### Test Inbound Calling + +1. Call your configured Twilio phone number from another phone +2. Verify your Dograh AI voice agent answers and responds +3. Check call logs in both Dograh AI dashboard and Twilio Console ## Troubleshooting @@ -95,6 +120,20 @@ When using Twilio with campaigns: - Check firewall rules for WebSocket traffic - Ensure audio pipeline is configured correctly + + + - Verify webhook URL is correctly configured in Twilio Console + - Ensure webhook URL is publicly accessible from internet + - Check that phone number is properly linked to webhook + - Verify Dograh AI instance is running and responding + + + + - Confirm voice agent workflow is properly configured + - Check webhook signature validation is working + - Verify WebSocket connection establishes successfully + - Review call logs for error messages + ## Best Practices diff --git a/docs/integrations/telephony/vobiz.mdx b/docs/integrations/telephony/vobiz.mdx new file mode 100644 index 0000000..9f96d7f --- /dev/null +++ b/docs/integrations/telephony/vobiz.mdx @@ -0,0 +1,170 @@ +--- +title: "Vobiz Integration" +description: "Configure Vobiz for voice communication in Dograh AI" +--- + +## Overview + +Vobiz is a cloud-based telephony service provider that offers global reach with competitive pricing. Dograh AI's Vobiz integration provides reliable voice connectivity for your conversational AI agents. + +## Prerequisites + +Before setting up Vobiz integration, you'll need: + +- A [Vobiz account](https://vobiz.com) +- Auth ID from your Vobiz dashboard +- Auth Token generated for your account +- At least one configured phone number in your Vobiz account +- Dograh AI instance running and accessible + +## Configuration + +### Step 1: Get Vobiz Credentials + +1. Sign up for a Vobiz account +2. Log in to your Vobiz dashboard +3. Navigate to your account settings to find your **Auth ID** +4. Generate an **Auth Token** for API access +5. Configure phone numbers in your Vobiz account for outbound calling + +### Step 2: Configure in Dograh AI + +1. Navigate to **Workflow** → **Phone Call** → **Configure Telephony** +2. Select **Vobiz** as your provider +3. Enter your credentials: + - Auth ID + - Auth Token + - From Phone Number (with country code, e.g., +1234567890) +4. Click **Save Configuration** + + +Vobiz provides cloud-based telephony services with global reach and competitive pricing. + + +### Step 3: Test Your Configuration + +1. Create a test workflow +2. Click "Test Call" to verify connection +3. Check call logs for successful connection + +## Inbound Calling Setup + +To enable inbound calling with Vobiz: + +1. **Complete Telephony Configuration**: Use the same [Configuration](#configuration) steps above +2. **Get Your Workflow Webhook URL**: Find your workflow ID and construct the webhook URL as: `https://api.dograh.com/api/v1/telephony/inbound/{workflow_id}` + +### Configure Application in Vobiz Console + +Vobiz requires creating an XML application to handle inbound calls. Follow these steps: + +1. **Navigate to Applications**: + - Log in to your Vobiz Console + - Navigate to the **Applications** section + + Vobiz console showing Applications section navigation + Vobiz console showing Applications section navigation + +2. **Create New Application**: + - Click **Create New Application** + - Configure the XML application with the following URLs: + - **Answer URL**: `https://api.dograh.com/api/v1/telephony/inbound/{workflow_id}` + - **Hangup URL**: `https://api.dograh.com/api/v1/telephony/vobiz/hangup-callback/workflow/{workflow_id}` + - **Fallback Answer URL**: `https://api.dograh.com/api/v1/telephony/inbound/fallback` + - Save the application + + + Replace `{workflow_id}` with your actual workflow ID. If using self-hosted Dograh, replace `api.dograh.com` with your domain. + + + Vobiz XML application configuration showing Answer URL, Hangup URL, and Fallback Answer URL + Vobiz XML application configuration showing Answer URL, Hangup URL, and Fallback Answer URL + +3. **Attach Phone Number**: + - After saving the application, edit it to attach a phone number + - Select the phone number you want to use for inbound calls + - Link it to your created application + + Vobiz application showing phone number attachment interface + Vobiz application showing phone number attachment interface + +2. **Verify Setup**: + - Ensure your Dograh AI instance is publicly accessible + - Verify any firewalls allow Vobiz's webhook requests + +### Test Inbound Calling + +1. Call your configured Vobiz phone number from another phone +2. Verify your Dograh AI voice agent answers and responds +3. Check call logs in both Dograh AI dashboard and Vobiz dashboard + +## Troubleshooting + + + + Ensure phone numbers include country code in E.164 format: `+1234567890` + + + + - Verify Auth ID and Auth Token are correct + - Check for extra spaces in credentials + - Ensure credentials haven't been regenerated in Vobiz dashboard + + + + - Confirm your Auth Token matches exactly + - Verify the webhook URL is accessible from Vobiz servers + - Check if you're behind a proxy that modifies requests + + + + - Verify WebSocket connection is established + - Check firewall rules for WebSocket traffic + - Ensure audio pipeline is configured correctly + + + + - Verify webhook URL is correctly configured in Vobiz dashboard + - Ensure webhook URL is publicly accessible from internet + - Check that phone number is properly linked to webhook + - Verify Dograh AI instance is running and responding + + + + - Confirm voice agent workflow is properly configured + - Check webhook processing is working correctly + - Verify WebSocket connection establishes successfully + - Review call logs for error messages + + + +## Best Practices + +- Store credentials securely in the database +- Test your configuration with a single call before running campaigns +- Monitor Vobiz dashboard for usage and billing +- Keep your Auth Token secure and rotate it periodically \ No newline at end of file diff --git a/docs/integrations/telephony/vonage.mdx b/docs/integrations/telephony/vonage.mdx index f973f35..11944cd 100644 --- a/docs/integrations/telephony/vonage.mdx +++ b/docs/integrations/telephony/vonage.mdx @@ -65,49 +65,20 @@ Watch this step-by-step guide to set up Vonage with Dograh AI: 2. Click "Test Call" to verify connection 3. Check call logs for successful connection -## How It Works +## Inbound Calling -### Technical Details + +**Coming Soon**: Inbound calling support for Vonage is currently under development and will be available in a future release. For now, Vonage integration supports outbound calling only. + -Vonage integration differs from other providers in key ways: +Vonage integration currently supports outbound calling. Inbound calling functionality is being developed and will include: -- **Audio Format**: Uses 16kHz Linear PCM (vs Twilio's 8kHz μ-law) -- **Protocol**: NCCO (Nexmo Call Control Objects) instead of TwiML -- **Authentication**: JWT-based authentication using private keys -- **WebSocket**: Binary audio frames instead of base64-encoded +- Webhook configuration for incoming calls +- NCCO response handling +- Event tracking for call lifecycle management +- WebSocket audio streaming for inbound calls -### Call Flow - -1. Dograh AI generates a JWT token using your private key -2. Call is initiated via Vonage Voice API -3. Vonage requests NCCO instructions at the webhook URL -4. Dograh returns WebSocket connection details -5. Audio streams as 16kHz PCM over WebSocket -6. Real-time voice interaction occurs with your agent - -### NCCO Response Example - -```json -[ - { - "action": "connect", - "endpoint": [{ - "type": "websocket", - "uri": "wss://your-domain/api/v1/telephony/ws/123/456/789", - "content-type": "audio/l16;rate=16000", - "headers": {} - }] - } -] -``` - -## Campaign Features - -When using Vonage with campaigns: -- **Global Reach**: Excellent international call quality and coverage -- **Number Pool Management**: Automatic rotation of configured numbers -- **Call Analytics**: Detailed metrics via Vonage Dashboard -- **Cost Tracking**: Per-call cost calculation for billing +For inbound calling needs, consider using [Twilio](/integrations/telephony/twilio), [Cloudonix](/integrations/telephony/cloudonix), or [Vobiz](/integrations/telephony/vobiz) which have full inbound support. ## Audio Quality Optimization @@ -151,6 +122,20 @@ Vonage uses higher quality audio (16kHz) which provides: - Monitor for audio pipeline errors - Review max call duration settings + + + - Verify Answer URL is correctly configured in Vonage application + - Ensure Answer URL is publicly accessible and returns valid NCCO + - Check that phone numbers are linked to the correct application + - Verify Event URL is configured for call tracking + + + + - Confirm NCCO response includes correct WebSocket endpoint + - Check that organization_id in Event URL matches your setup + - Verify voice agent workflow is properly configured + - Review webhook logs for error responses + ## Best Practices diff --git a/ui/src/app/telephony-configurations/page.tsx b/ui/src/app/telephony-configurations/page.tsx index bee5df5..1d1325a 100644 --- a/ui/src/app/telephony-configurations/page.tsx +++ b/ui/src/app/telephony-configurations/page.tsx @@ -663,7 +663,7 @@ export default function ConfigureTelephonyPage() { )} -
+
+
+

+ Configure inbound calling?{" "} + + View documentation + +

+