Skip to main content

Voice Call

Makes an automated voice call using the Twilio API. This node can deliver voice messages using text-to-speech or execute custom TwiML scripts for advanced call flows.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If ContinueOnError property is true, no error is caught when the project is executed even if Catch node is used.

Input​

  • Connection Id - The Twilio connection identifier from the Connect node. This is optional if you provide credentials directly in the Options.
  • From Number - The Twilio phone number to call from. Must be in E.164 format (e.g., +14155552671). This must be a phone number you own in your Twilio account.
  • To Number - The phone number to call. Must be in E.164 format (e.g., +14155552672).
  • XML Url - URL to TwiML instructions for the call. If provided along with Message, the XML Url takes precedence and Message is ignored.
  • Message - Text message to be spoken using text-to-speech. Maximum 4,000 characters. If both XML Url and Message are provided, the Message is ignored.
info

You must provide either Message (for simple text-to-speech) or XML Url (for advanced call flows). If both are provided, XML Url takes precedence.

Output​

  • Response - The Twilio API response containing call details including:
    • sid - Unique call identifier
    • status - Call status (queued, ringing, in-progress, completed, busy, no-answer, failed, canceled)
    • to - Recipient phone number
    • from - Caller phone number
    • date_created - Timestamp when call was created
    • duration - Call duration in seconds (available after call completes)
    • price - Cost of the call
    • direction - Call direction (outbound-api)
    • answered_by - Who answered (human, machine, fax, unknown)

Options​

  • Voice For TwiML - Voice type for text-to-speech when using Message input. Default: woman.
    • Available voices: man, woman, alice (more natural)
  • Language For TwiML - Language code for text-to-speech. Default: en-gb.
    • Examples: en-US (US English), en-GB (British English), es-ES (Spanish), fr-FR (French), de-DE (German)
    • See Twilio's TTS documentation for all supported languages
  • Record - Enable call recording. Default: false. When enabled, the call will be recorded and accessible in your Twilio Console.
  • Account SID - Your Twilio Account SID. This is optional if you're using a Connection Id from the Connect node.
  • Auth Token - Your Twilio Auth Token. This is optional if you're using a Connection Id from the Connect node.
tip

Use the alice voice for more natural-sounding text-to-speech. It provides better pronunciation and inflection than the standard man and woman voices.

Examples​

Example 1: Simple Voice Notification​

Make a basic voice call with a text-to-speech message:

Inputs:

  • Connection Id: connection_id (from Connect node)
  • From Number: +14155552671
  • To Number: +14155552672
  • Message: Hello! This is a reminder about your appointment tomorrow at 2 PM. Please call us if you need to reschedule.

Options:

  • Voice For TwiML: woman
  • Language For TwiML: en-US
  • Record: false

Output:

{
  "sid": "CA1234567890abcdef1234567890abcdef",
  "status": "queued",
  "to": "+14155552672",
  "from": "+14155552671",
  "date_created": "2024-01-15T10:30:00Z",
  "direction": "outbound-api"
}

Example 2: Appointment Reminder Campaign​

Send voice reminders to multiple patients from a database:

Flow Structure:

  1. Schedule Trigger - Run daily at 9 AM
  2. Database Query - Get appointments for tomorrow
  3. For Each - Loop through appointments
  4. Voice Call - Call each patient

Call Configuration:

  • From Number: +14155552671
  • To Number: {{item.patient_phone}}
  • Message: Hello {{item.patient_name}}. This is a reminder about your appointment on {{item.appointment_date}} at {{item.appointment_time}} with Dr. {{item.doctor_name}}. Please call us at +1-415-555-2671 if you need to cancel or reschedule.
  • Voice: woman
  • Language: en-US
  • Record: true (for compliance)

Example 3: Emergency Alert System​

Broadcast urgent alerts to a list of contacts:

Flow Structure:

  1. Trigger - Manual or event-based trigger
  2. Excel - Read Range - Read emergency contacts
  3. For Each - Call each contact
  4. Delay - Wait 1 second between calls

Message:

This is an emergency alert. {{alert_message}}. Please follow emergency procedures immediately. I repeat: {{alert_message}}.

Options:

  • Voice: alice (clearest voice)
  • Language: en-US
  • Record: true

Example 4: Multi-Language Notifications​

Send notifications in recipient's preferred language:

Flow Structure:

  1. Database Query - Get users with language preference
  2. For Each - Loop through users
  3. Switch - Based on language preference
  4. Voice Call - Call with appropriate language

English Call:

  • Message: Your package has been delivered. Thank you for your order.
  • Language: en-US

Spanish Call:

  • Message: Su paquete ha sido entregado. Gracias por su pedido.
  • Language: es-ES

French Call:

  • Message: Votre colis a été livré. Merci pour votre commande.
  • Language: fr-FR

Example 5: Advanced TwiML Call Flow​

Use custom TwiML for interactive call experience:

TwiML Script (hosted at https://example.com/call-flow.xml):

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say voice="alice" language="en-US">
        Welcome to Acme Services. Please listen to the following options.
    </Say>
    <Gather numDigits="1" action="https://example.com/handle-choice">
        <Say>Press 1 for sales. Press 2 for support. Press 3 for billing.</Say>
    </Gather>
    <Say>We didn't receive your input. Goodbye.</Say>
</Response>

Call Configuration:

  • XML Url: https://example.com/call-flow.xml
  • Message: (leave empty, XML Url takes precedence)
  • Record: true

Example 6: Delivery Status Calls with Recording​

Call customers about delivery status and record for quality:

Flow Structure:

  1. Database Query - Get delivered orders from today
  2. For Each - Loop through orders
  3. Voice Call - Notify customer
  4. Database Update - Mark as notified

Call Configuration:

  • From Number: +14155552671
  • To Number: {{item.customer_phone}}
  • Message: Hello, this is a notification that your order number {{item.order_id}} has been successfully delivered. If you did not receive this order, please call our customer service at +1-415-555-2671. Thank you for your business.
  • Voice: woman
  • Language: en-US
  • Record: true (for customer service quality)

Tips​

  • Phone Number Format - Always use E.164 format: +[country code][number]. Example: +14155552671.
  • Message Length - Keep messages concise (under 1 minute of speech). Longer messages may cause recipients to hang up.
  • Voice Selection - alice provides the most natural-sounding voice. Test different voices to find what works best.
  • Language Codes - Use proper language codes for best pronunciation. en-GB sounds different from en-US.
  • Recording Compliance - If recording calls, ensure compliance with local laws. Some regions require consent.
  • Call Timing - Avoid calling outside business hours (9 AM - 8 PM local time) to comply with regulations.
  • TwiML vs Message - Use Message for simple notifications. Use TwiML for interactive calls, menus, or complex flows.
  • TwiML Testing - Test your TwiML XML files using Twilio's TwiML Bins before using in production.
  • Cost Management - Voice calls cost more than SMS. Monitor call durations and costs in Twilio Console.
  • Answering Machines - Check answered_by in Response to detect if a machine answered. Consider using Twilio's AMD (Answering Machine Detection).
  • Retry Logic - Implement retry logic for failed calls (busy, no-answer). Add delays between retries.
  • Status Tracking - Check call status in Response: queued, ringing, in-progress, completed, busy, no-answer, failed.

Common Errors​

Empty From/To Number​

Error: "ErrInvalidArg: From Number cannot be empty" or "To Number cannot be empty"

Solution:

  • Ensure both From Number and To Number fields are populated
  • Check that your data source contains valid phone numbers
  • Verify the variable names match your flow data

Empty Message and XML Url​

Error: "ErrInvalidVoice: Message and XML Url cannot be empty at the same time"

Solution:

  • Provide either a Message (text-to-speech) or XML Url (TwiML script)
  • If both are provided, XML Url takes precedence
  • Ensure at least one is populated with valid content

Invalid Phone Number Format​

Error: "ErrRuntime: Error making voice call: Invalid 'To' Phone Number"

Solution:

  • Use E.164 format: +[country code][number]
  • Remove spaces, dashes, or parentheses from phone numbers
  • Ensure country code is included (e.g., +1 for US/Canada)
  • Example: +14155552671 (correct), 415-555-2671 (incorrect)

Invalid From Number​

Error: "The From number is not a valid phone number"

Solution:

  • Ensure the From Number is a phone number you own in your Twilio account
  • Purchase a phone number from Twilio Console if needed
  • Verify the phone number is configured for voice calls
  • Check that the number is in E.164 format

TwiML Fetch Failed​

Error: "Unable to fetch TwiML from URL"

Solution:

  • Verify the XML Url is publicly accessible
  • Ensure the URL returns valid TwiML XML
  • Check the server is responding with Content-Type: application/xml or text/xml
  • Test the URL in a browser to verify it loads
  • Ensure the server has a valid SSL certificate if using HTTPS

Invalid TwiML​

Error: "Invalid TwiML" or TwiML parsing error

Solution:

  • Validate your TwiML XML syntax
  • Use Twilio's TwiML validator or TwiML Bins for testing
  • Ensure all XML tags are properly closed
  • Check for invalid TwiML verbs or attributes
  • Review Twilio's TwiML documentation

Call Blocked or Failed​

Error: Call status shows "failed" or "busy"

Solution:

  • Verify the recipient's phone number is correct and active
  • Check if the number has blocked your Twilio number
  • Ensure the recipient's phone is turned on and has service
  • Try calling at a different time (might be temporarily busy)
  • Check Twilio Console logs for detailed failure reason

Unverified Number (Trial Account)​

Error: "The number is unverified. Trial accounts cannot call unverified numbers"

Solution:

  • Add the recipient number to verified phone numbers in Twilio Console
  • Upgrade your Twilio account from trial to paid
  • Use verified phone numbers for testing with trial accounts

Message Too Long​

Error: TwiML message exceeds maximum length

Solution:

  • Keep messages under 4,000 characters
  • Split long messages into multiple calls if necessary
  • Consider using TwiML with multiple <Say> elements for better pacing
  • Summarize information to keep calls concise

Recording Failed​

Error: Recording not available or failed

Solution:

  • Verify recording is enabled (Record option set to true)
  • Ensure your Twilio account has recording features enabled
  • Check Twilio Console for recording status and errors
  • Note: Recordings are only available after call completes
  • Verify you're not exceeding recording storage limits