Integrating Web Forms with VICIdial: A NON-AGENT API Use Case

Capturing leads through web forms is a cornerstone of modern marketing and sales strategies. However, manually transferring these leads into your call center software can be time-consuming and error-prone. By integrating your web forms directly with VICIdial using its NON-AGENT API, you can automate lead ingestion, ensure real-time follow-ups, and streamline your sales pipeline.

In this guide, we’ll walk through how to connect web forms to VICIdial using the NON-AGENT API, complete with code examples, best practices, and troubleshooting tips. Whether you’re a developer, marketer, or call center manager, this tutorial will help you bridge the gap between lead generation and outbound outreach.

Table of Contents

1. Why Integrate Web Forms with VICIdial?
2. Understanding the NON-AGENT API for Lead Ingestion
3. Prerequisites for Integration
4. Step-by-Step Integration Guide
   • Step 1: Design Your Web Form
   • Step 2: Set Up Server-Side Logic
   • Step 3: Send Data to VICIdial via API
   • Step 4: Handle API Responses and Errors
5. Advanced Features
   • Real-Time Lead Validation
   • Custom Field Mapping
   • Automating Follow-Up Actions
6. Best Practices for Secure and Scalable Integration
7. Common Pitfalls and Troubleshooting
8. Real-World Use Cases
9. Conclusion

1. Why Integrate Web Forms with VICIdial?

Manual data entry is inefficient and prone to errors. Automating lead transfer from web forms to VICIdial offers:

• Instant Lead Processing: Leads enter your dialing queue immediately after form submission.
• Reduced Human Error: Eliminate typos or missed entries.
• Faster Response Times: Enable agents to contact leads while their interest is fresh.
• Scalability: Handle high volumes of leads without additional effort.

For example, a mortgage company could automatically add leads from a “Get a Quote” form to a high-priority VICIdial campaign, ensuring agents call prospects within minutes.

2. Understanding the NON-AGENT API for Lead Ingestion

The NON-AGENT API provides the add_lead endpoint, which allows you to inject leads into VICIdial programmatically. Key parameters include:

• phone_number: The lead’s contact number (required).
• first_name, last_name: Basic lead details.
• list_id: The VICIdial list where the lead will be added (required).
• Custom fields (e.g., email, company, custom_1).

Example API Request:

https://your-vicidial-server.com/non_agent_api.php?
source=webform&
user=api_user&
pass=api_pass&
function=add_lead&
phone_number=5551234567&
first_name=John&
last_name=Doe&
email=john.doe@example.com&
list_id=1001

3. Prerequisites for Integration

Before starting, ensure you have:

• VICIdial Access: A server with the NON-AGENT API enabled.
• API Credentials: A username and password with permissions to add leads.
• Web Form: A form on your website (e.g., WordPress, React, or HTML).
• Server-Side Scripting: Access to backend code (e.g., PHP, Python, Node.js) to process form submissions.
• List ID: The ID of the VICIdial list where leads will be stored (found in the VICIdial admin interface).

4. Step-by-Step Integration Guide

Step 1: Design Your Web Form

Create a web form to capture lead data. Include fields like:

• Phone number
• First and last name
• Email address
• Custom fields (e.g., “Interest Level,” “Product Type”).

Example HTML Form:

<form id="leadForm" action="/submit_lead" method="POST">
  <input type="text" name="first_name" placeholder="First Name" required>
  <input type="text" name="last_name" placeholder="Last Name" required>
  <input type="tel" name="phone" placeholder="Phone Number" required>
  <input type="email" name="email" placeholder="Email" required>
  <select name="interest_level">
    <option value="High">High Interest</option>
    <option value="Medium">Medium Interest</option>
  </select>
  <button type="submit">Submit</button>
</form>

Step 2: Set Up Server-Side Logic

Create a script to process form submissions. Below is a Python example using Flask:

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

@app.route('/submit_lead', methods=['POST'])
def submit_lead():
    # Extract form data
    data = request.form
    
    # Prepare API parameters
    api_params = {
        "source": "webform",
        "user": "api_user",
        "pass": "api_pass",
        "function": "add_lead",
        "list_id": "1001",
        "phone_number": data.get("phone"),
        "first_name": data.get("first_name"),
        "last_name": data.get("last_name"),
        "email": data.get("email"),
        "custom_1": data.get("interest_level")  # Map to a VICIdial custom field
    }
    
    # Send request to VICIdial API
    response = requests.get(
        "https://your-vicidial-server.com/non_agent_api.php",
        params=api_params
    )
    
    # Handle response
    if response.json().get("status") == "SUCCESS":
        return jsonify({"message": "Lead added successfully!"}), 200
    else:
        return jsonify({"error": "Failed to add lead"}), 500

Step 3: Send Data to VICIdial via API

The server-side script sends the form data to VICIdial’s add_lead endpoint. Ensure all required fields (e.g., phone_number, list_id) are included.

Step 4: Handle API Responses and Errors

• Success: Log the lead ID and notify the user (e.g., display a confirmation message).
• Failure: Retry failed requests or alert administrators.
  Example Error Handling:

try:
    response = requests.get(api_url, params=api_params, timeout=10)
    response.raise_for_status()  # Raise HTTP errors
except requests.exceptions.RequestException as e:
    log_error(f"API request failed: {e}")
    return jsonify({"error": "Server error"}), 500

5. Advanced Features

Real-Time Lead Validation

Use VICIdial’s API to check for duplicates or invalid numbers before adding leads.
Example: Call the get_lead_info endpoint to verify if the phone number already exists.

Custom Field Mapping

Map web form fields to VICIdial’s custom fields (e.g., custom_1, custom_2) to store additional data like “Interest Level” or “Source.”

Automating Follow-Up Actions

Trigger immediate outbound calls or SMS alerts when a high-priority lead submits the form.
Example: Use the campaign_activate endpoint to start a dialing campaign for urgent leads.

6. Best Practices for Secure and Scalable Integration

• Validate Inputs: Sanitize phone numbers and email addresses to prevent invalid data.
• Use HTTPS: Encrypt API requests to protect sensitive data.
• Rate Limiting: Add delays between API calls to avoid hitting VICIdial’s rate limits.
• Logging: Track form submissions and API responses for auditing.
• Backup Storage: Temporarily store leads in a database if the API fails.

7. Common Pitfalls and Troubleshooting

• Invalid list_id: Double-check the list ID in the VICIdial admin interface.
• Missing Fields: Ensure required parameters like phone_number are included.
• API Timeouts: Increase timeout thresholds or optimize server performance.
• Duplicate Leads: Implement deduplication checks using get_lead_info.

8. Real-World Use Cases

1. E-Commerce: A retail company uses a “Callback Request” form to add leads to a VIP campaign, ensuring calls within 5 minutes.
2. Healthcare: A clinic’s “Appointment Inquiry” form triggers SMS reminders and agent follow-ups via VICIdial.
3. Education: A university’s “Program Interest” form assigns leads to regional sales teams based on custom field values.

9. Conclusion

Integrating web forms with VICIdial using the NON-AGENT API eliminates manual workflows, accelerates lead response times, and ensures no prospect falls through the cracks. By following this guide, you can set up a robust automation pipeline that connects your marketing efforts directly to your call center operations.

Whether you’re running a small business or a large enterprise, this integration empowers your team to focus on what matters most: closing deals and delighting customers. Start automating today and watch your conversion rates soar!

For further details, refer to the VICIdial NON-AGENT API documentation.