How to Trigger Outbound Calls with Neural Voice: Complete API Guide

What are Outbound Calls with Neural Voice?

Outbound calls are AI-initiated phone calls where your Neural Voice assistant proactively contacts customers, prospects, or users. This powerful feature enables businesses to automate follow-ups, conduct surveys, deliver notifications, or handle sales outreach at scale.

Unlike inbound calls where customers contact you, outbound calls put your AI assistant in the driver's seat, making it perfect for proactive customer engagement and business automation.

Why Use Automated Outbound Calls?

Automated outbound calling with AI voice assistants transforms how businesses communicate:

Prerequisites: What You Need to Get Started

Before triggering outbound calls with Neural Voice, ensure you have:

• Neural Voice Account: Active subscription with outbound calling enabled
• Assistant ID: UUID of your configured AI assistant (provided by Neural Voice)
• API Key: Your authorisation token (provided by Neural Voice)
• Development Environment: Ability to make HTTP POST requests
• Phone Numbers: Valid UK phone numbers in the correct format

Step-by-Step Guide: Triggering an Outbound Call

Step 1: Prepare Your Request URL

Neural Voice outbound calls are triggered via an API endpoint. You'll make a POST request to the Neural Voice API with your call parameters.

POST https://b-prd.neural-voice.ai/webhook/outbound-call

Step 2: Format Your Phone Numbers Correctly

Phone numbers must follow this exact format:

• Start with +44 (UK country code)
• Include the full number without spaces
• Example: +447123456789 (not +44 7123 456 789)

Step 3: Structure Your Request Body

Your API request body should contain these essential fields:

• assistant_id: The UUID of your Neural Voice assistant
• target_phone_number: The phone number to call (in +44xxxxxxxxxx format)
• external_id (optional): Your internal ID to link the call to your CRM
• call_variables (optional): Custom variables to personalise the call

Using Variables for Personalised Calls

One of Neural Voice's most powerful features is the ability to pass custom variables that provide context to your AI assistant during the call. These variables can include customer names, order details, preferences, or any other relevant information.

Variables are included in your request using the call_variables field and referenced in your assistant's prompt using double curly braces: {{ variable_name }}

For example, if you want your AI to know the caller's name and recent purchase:

• In your API request: "caller_name": "Sarah"
• In your assistant's prompt: "Hello {{ caller_name }}, I'm calling about your recent order"

This makes every call feel personal and contextual, dramatically improving customer experience and engagement rates.

Step 4: Set Required Headers

Include these mandatory headers in your request:

• Referer: Set to https://app.neural-voice.ai
• Authorisation: Your Neural Voice API key
• Content-Type: application/json

Code Examples: Making Your First Outbound Call

JavaScript/Node.js Example

Here's how to trigger an outbound call using JavaScript:

const axios = require('axios');

const triggerOutboundCall = async () => {
  try {
    const response = await axios.post('https://b-prd.neural-voice.ai/webhook/outbound-call', {
      assistant_id: 'your-assistant-uuid-here',
      target_phone_number: '+447123456789',
      external_id: 'customer-12345', // Optional
      call_variables: {
        caller_name: 'Sarah',
        order_id: 'ORD-12345',
        product_name: 'Premium Subscription',
        account_status: 'VIP'
      }
    }, {
      headers: {
        'Referer': 'https://app.neural-voice.ai',
        'Authorisation': 'your-api-key-here',
        'Content-Type': 'application/json'
      }
    });
    
    console.log('Call triggered successfully:', response.status);
  } catch (error) {
    console.error('Error triggering call:', error.response.data);
  }
};

"You are calling {{ caller_name }} who is a {{ account_status }} customer. 
They recently purchased {{ product_name }} (Order: {{ order_id }}). 
Be friendly and professional. Start the call with: 
'Hi {{ caller_name }}, this is calling from Neural Voice about your recent order {{ order_id }}. How has your day been?'"

Python Example

Using Python with the requests library:

import requests

def trigger_outbound_call():
    url = 'https://b-prd.neural-voice.ai/webhook/outbound-call'
    headers = {
        'Referer': 'https://app.neural-voice.ai',
        'Authorisation': 'your-api-key-here',
        'Content-Type': 'application/json'
    }
    data = {
        'assistant_id': 'your-assistant-uuid-here',
        'target_phone_number': '+447123456789',
        'external_id': 'customer-12345',  # Optional
        'call_variables': {
            'caller_name': 'Sarah',
            'order_id': 'ORD-12345',
            'product_name': 'Premium Subscription',
            'account_status': 'VIP',
            'last_contact': '2025-05-15'
        }
    }
    
    try:
        response = requests.post(url, json=data, headers=headers)
        if response.status_code == 200:
            print('Call triggered successfully')
        else:
            print(f'Error: {response.status_code} - {response.text}')
    except requests.exceptions.RequestException as e:
        print(f'Request failed: {e}')

cURL Example

For direct command-line testing or shell script integration:

curl -X POST \
  'https://b-prd.neural-voice.ai/webhook/outbound-call' \
  -H 'Content-Type: application/json' \
  -H 'Referer: https://app.neural-voice.ai' \
  -H 'Authorisation: your-api-key-here' \
  -d '{'
    "assistant_id": "your-assistant-uuid-here",'
    "target_phone_number": "+447123456789",'
    "external_id": "customer-12345",'
    "call_variables": {'
      "caller_name": "Sarah",'
      "order_id": "ORD-12345",'
      "product_name": "Premium Subscription",'
      "account_status": "VIP"
    '}'
  '}'

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "message": "Call queued successfully"
}

Understanding API Responses

Neural Voice returns different HTTP status codes to indicate the result of your request:

Best Practices for Outbound Calling

1. Respect Calling Hours

Schedule calls during appropriate business hours (typically 9 AM - 6 PM) to improve answer rates and maintain professionalism.

2. Use External IDs for CRM Integration

Always include an external_id to link call transcripts with your customer records. This enables better tracking and follow-up workflows.

3. Handle Rate Limits

Implement retry logic with exponential backoff to handle temporary API limits gracefully.

4. Monitor Your Usage

Track your calling minutes to avoid hitting plan limits. Consider upgrading your plan if you're regularly approaching limits.

5. Test with Development Numbers

Always test your integration with internal phone numbers before deploying to production.

6. Optimise Your Variables

Use descriptive variable names and provide meaningful context. Instead of generic variables like "data1", use specific names like "last_purchase_date" or "customer_tier".

7. Keep Variables Relevant

Only pass variables that are relevant to the call's purpose. Too much information can overwhelm the AI and make conversations feel unnatural.

Accessing Call Transcripts and Analytics

After your AI assistant completes an outbound call:

• Transcripts appear in your Neural Voice dashboard within 3 minutes
• Use the external_id to match transcripts with your CRM records
• Access detailed analytics including call duration, success rates, and conversation insights
• Export transcript data for further analysis or reporting

Creative Ways to Use Call Variables

Customer Service Calls

Pass ticket details, customer history, and previous interactions to make support calls more efficient:

• Variables: ticket_id, issue_type, customer_tier, previous_contacts
• Prompt: "You're calling {{ caller_name }} about ticket {{ ticket_id }}. They are a {{ customer_tier }} customer with a {{ issue_type }} issue. This is their {{ previous_contacts }} contact about this matter."

Sales Follow-Up Calls

Include prospect information, interests, and interaction history for more targeted conversations:

• Variables: prospect_name, company_name, industry, demo_date, interest_level
• Prompt: "Hi {{ prospect_name }}, I'm following up on the demo we showed {{ company_name }} on {{ demo_date }}. You seemed particularly interested in our {{ interest_level }} features."

Appointment Confirmations

Send personalised appointment reminders with specific details:

• Variables: appointment_date, appointment_time, service_type, location
• Prompt: "Hello {{ caller_name }}, I'm calling to confirm your {{ service_type }} appointment on {{ appointment_date }} at {{ appointment_time }} at our {{ location }} location."

Common Integration Scenarios

Lead Follow-Up Automation

Automatically call new leads within minutes of form submission using API triggers from your website or CRM.

Appointment Reminders

Schedule reminder calls for upcoming appointments, reducing no-shows and improving customer experience.

Survey and Feedback Collection

Conduct post-purchase surveys or satisfaction calls to gather valuable customer feedback at scale.

Payment Reminders

Automate friendly payment reminder calls for overdue accounts, improving collection rates while maintaining customer relationships.

Troubleshooting Common Issues

Phone Number Format Errors

Ensure phone numbers start with +44 and contain no spaces or special characters except the + symbol.

Authentication Problems

Verify your API key is correct and that the Referer header is set to https://app.neural-voice.ai exactly.

Assistant Not Found

Double-check your assistant_id UUID with your Neural Voice account manager.

Getting Started with Neural Voice Outbound Calls

Ready to implement automated outbound calling for your business? Neural Voice makes it simple to integrate AI-powered calling into your existing workflows.

Our outbound calling API enables businesses to scale their communication efforts while maintaining the personal touch customers expect. From lead follow-up to customer service, the possibilities are endless.

Discover how Neural Voice can transform your outbound communication strategy. Book a demo to see our outbound calling capabilities in action, or view our plans to find the perfect solution for your calling volume needs.