ai calling Logo / Documentation
Back to app

Twilio / VAPI Working Flow

This documentation explains how calls are placed and received through Twilio or Vonage Voice API (VAPI) within the platform. Understanding the call flow helps you configure providers correctly, troubleshoot issues, and optimize call handling. The platform integrates with these telephony providers to enable voice calling capabilities.

Understanding the Call Flow

The platform uses Twilio or VAPI as telephony providers to handle voice calls. Calls flow through the provider's infrastructure, with the platform managing call logic, AI assistant interactions, and call recording.

Outbound Calls

Calls initiated from the platform (campaigns, manual calls) are routed through the provider to destination numbers. The provider handles dialing and connection.

Inbound Calls

Calls received on your purchased numbers are forwarded to the platform via webhooks. The platform processes the call and routes it to configured AI assistants.

Prerequisites

Before using telephony features, ensure you have the necessary configuration in place.

Required Configuration

  • Provider Credentials: Valid Twilio Account SID and Auth Token, or VAPI Token configured in Settings → API Settings
  • Phone Number: At least one purchased phone number with voice capabilities. Numbers can be purchased through the platform or directly from the provider
  • Webhook Configuration: Webhook URLs configured in the provider dashboard to forward call events to the platform
  • Wallet Balance: Sufficient wallet balance or subscription minutes to cover call costs
Twilio API Docs VAPI API Docs

Outbound Call Flow

Outbound calls are initiated from the platform and routed through the telephony provider to destination numbers.

Step-by-Step Process

  1. User Initiates Call: A user triggers an outbound call via Campaigns (automated) or Calls (manual). The platform prepares call details including destination number, caller ID, and AI assistant configuration.
  2. Platform Authentication: The platform authenticates with Twilio/VAPI using stored credentials (Account SID/Token for Twilio, Token for VAPI) from Settings.
  3. Provider API Call: The platform makes an API call to the provider to initiate the call. This includes destination number, caller ID (your purchased number), and webhook URLs for call events.
  4. Provider Dials: The provider dials the destination number using your purchased number as the caller ID. The provider handles the actual phone network connection.
  5. Call Events: As the call progresses, the provider sends events (ringing, answered, completed, failed) to the platform via webhooks.
  6. AI Assistant Interaction: When the call is answered, the platform routes the call to the configured AI assistant. The assistant handles the conversation using its prompts and configuration.
  7. Call Recording: If recording is enabled, the provider records the call and provides a recording URL after completion.
  8. Call Logging: The platform records call details (status, duration, recording URL, summary) in the Calls log for review and analysis.

Caller ID: Outbound calls use your purchased phone number as the caller ID. This is the number that appears on the recipient's phone when you call them.

Inbound Call Flow

Inbound calls are received on your purchased numbers and forwarded to the platform for processing.

Step-by-Step Process

  1. Caller Dials Number: A caller dials your purchased phone number. The call is received by the telephony provider (Twilio/VAPI).
  2. Provider Receives Call: The provider receives the incoming call and identifies which number was dialed.
  3. Webhook Forwarding: The provider forwards the call request to the platform's webhook URL (configured in the provider dashboard). The webhook includes call details like caller number, called number, and call status.
  4. Platform Processing: The platform receives the webhook and processes the incoming call. It identifies the number that was called and checks for configured AI assistants or call handling rules.
  5. AI Assistant Routing: If an AI assistant is configured for the number, the platform routes the call to that assistant. The assistant handles the conversation using its prompts and configuration.
  6. Call Handling: The AI assistant greets the caller, processes their responses, and handles the conversation according to its configuration. This may include appointment scheduling, information gathering, or call routing.
  7. Call Recording: If recording is enabled, the provider records the call and provides a recording URL after completion.
  8. Call Logging: The platform records call details (status, duration, recording URL, summary) in the Calls log for review and analysis.

Webhook Configuration: Inbound calls require webhook URLs to be configured in the provider dashboard. These URLs tell the provider where to send call events. Ensure webhooks are properly configured and accessible from the internet.

Webhooks & Call Events

Webhooks are HTTP callbacks that allow the provider to notify the platform about call events in real-time.

Webhook Configuration

Webhooks must be configured in the provider dashboard:

Configuration Steps

  • Get Webhook URL: The platform provides webhook URLs for call events. These are typically displayed in Settings or provided during number purchase.
  • Configure in Provider Dashboard: Log into your Twilio or VAPI dashboard and configure webhook URLs for your phone numbers. Set URLs for both voice call handling and status callbacks.
  • Verify Accessibility: Ensure webhook URLs are publicly accessible from the internet. Providers cannot reach internal or localhost URLs.
  • Test Webhooks: Test webhook delivery by making a test call. Verify that the platform receives and processes webhook events correctly.

Call Events

The provider sends various events during call lifecycle:

Ringing

Call is ringing at the destination. The recipient's phone is alerting but not yet answered.

Answered

Call was answered by the recipient. The call is now active and conversation can begin.

Completed

Call ended normally. Both parties hung up. Recording and summary are available.

Failed

Call failed to connect. Reasons include busy, no answer, invalid number, or network issues.

Common Issues & Solutions

Understanding common issues helps you troubleshoot call problems effectively.

Insufficient wallet balance or plan minutes

Solutions:

  • Check wallet balance: Verify your wallet balance in Billing & Plans → Wallet. Ensure you have sufficient funds to cover call costs.
  • Check subscription: If you have a subscription, verify you haven't exceeded your minute allowance. Check usage in My Subscriptions.
  • Refill wallet: If balance is low, refill your wallet. Go to Billing & Plans → Wallet and add funds.
  • Upgrade plan: If you consistently exceed subscription limits, consider upgrading your plan to get more included minutes.
  • Review call costs: Check call costs in the Calls log. Verify that charges match expected rates.
Invalid or missing credentials

Checklist:

  • Verify credentials: Check that Twilio Account SID/Token or VAPI Token are correctly entered in Settings → API Settings. Ensure there are no extra spaces or typos.
  • Test credentials: Test credentials by making a test call or checking provider dashboard. Invalid credentials will cause authentication failures.
  • Check expiration: Some tokens may expire. Verify that credentials are still valid in the provider dashboard.
  • Regenerate if needed: If credentials are compromised or expired, regenerate them in the provider dashboard and update Settings.
  • Provider account status: Verify that your provider account is active and in good standing. Suspended accounts cannot make calls.
Number lacks required capabilities

Solutions:

  • Check number capabilities: Verify that your purchased number has voice capabilities enabled. Some numbers may only support SMS.
  • Enable capabilities: In the provider dashboard, ensure voice capabilities are enabled for your number. Some providers require explicit capability activation.
  • Purchase correct number: When purchasing numbers, ensure you select numbers with voice capabilities. Check number details before purchasing.
  • Contact provider: If capabilities cannot be enabled, contact your provider's support for assistance.
Webhook URL misconfigured or blocked

Checklist:

  • Verify webhook URL: Check that webhook URLs are correctly configured in the provider dashboard. URLs must be publicly accessible.
  • Test accessibility: Test webhook URLs from external networks to ensure they're accessible. Providers cannot reach internal URLs.
  • Check firewall: Ensure firewalls are not blocking incoming webhook requests. Webhooks require inbound HTTP/HTTPS access.
  • Verify SSL: If using HTTPS, ensure SSL certificates are valid. Invalid certificates will cause webhook failures.
  • Check provider logs: Review provider dashboard logs for webhook delivery failures. This helps identify connectivity issues.
  • Test webhook: Use provider's webhook testing tools to verify webhook delivery. Some providers offer webhook testing utilities.

Best Practices

Provider Configuration

  • Secure Credentials: Store provider credentials securely in Settings. Never share credentials or commit them to version control.
  • Test Credentials: After configuring credentials, test them with a small call to verify they work correctly.
  • Monitor Provider Account: Regularly check your provider account status and balance. Ensure account remains in good standing.
  • Backup Configuration: Document webhook URLs and configuration settings for disaster recovery purposes.

Webhook Management

  • Use HTTPS: Always use HTTPS for webhook URLs to ensure secure communication. Never use HTTP for production webhooks.
  • Verify Webhooks: Test webhook delivery after configuration changes. Verify that the platform receives and processes events correctly.
  • Monitor Webhook Logs: Regularly review webhook delivery logs to identify failures or issues early.
  • Handle Failures: Implement retry logic for webhook failures. Some providers retry failed webhooks automatically.

Call Optimization

  • Monitor Call Quality: Review call recordings and summaries to identify quality issues. Optimize AI assistant prompts to improve conversations.
  • Track Costs: Monitor call costs and usage patterns. Optimize call durations and volumes to reduce expenses.
  • Test Before Scaling: Test call flows with small volumes before scaling to large campaigns. Verify everything works correctly.
  • Review Call Logs: Regularly review call logs to identify patterns, issues, or optimization opportunities.

Phone Numbers

Learn how to purchase and manage phone numbers for calling.

Settings

Configure provider credentials and API settings.

Calls

Review call logs and understand call statuses.

Integrations

Learn about Twilio and VAPI integration details.