# ๐งช Automated Agent Testing
Source: https://docs.vodex.ai/agents/automated-testing
Learn how to automatically test your AI agents with custom customer profiles to ensure quality and reliability
**What you'll learn:** How to create customer profiles, run automated tests on your AI agents, and interpret test results to improve performance.
## What Is Automated Agent Testing?
Automated agent testing allows you to **simulate real customer interactions** without making actual phone calls. Think of it as a rehearsal where your AI agent practices with different types of customers before going live.
Instead of manually calling test numbers, you create **Customer Profiles** that act like different customers, and the system automatically tests how well your agent handles each scenario.
## Why Use Automated Testing? ๐ฏ
### **The Problems It Solves:**
* **Time-consuming manual testing** - No need to manually test every scenario
* **Inconsistent test coverage** - Ensures all scenarios are tested systematically
* **Costly errors in production** - Catch issues before real customers are affected
* **Difficult to reproduce edge cases** - Create specific scenarios that are hard to test manually
### **The Benefits:**
* **Fast iteration** - Test multiple scenarios simultaneously
* **Cost-effective** - Only \$0.02 per customer profile test
* **Consistent results** - Same scenarios tested the same way every time
* **Comprehensive coverage** - Test edge cases that rarely happen in real life
## How Automated Testing Works ๐ง
The testing flow is simple:
```mermaid theme={null}
flowchart TD
A[Create Customer Profiles] --> B[Define Customer Behaviors]
B --> C[Set User Fields & Scenarios]
C --> D[Select Agent to Test]
D --> E[Choose Customer Profiles]
E --> F[Select AI Model for Customer]
F --> G[Start Testing]
G --> H[Monitor Test Progress]
H --> I{Test Complete?}
I -->|Success| J[Review Conversation]
I -->|Failed| K[Review Failure Status]
J --> L[Improve Agent Prompt]
K --> L
L --> M[Run Tests Again]
style A fill:#e1f5fe
style J fill:#c8e6c9
style K fill:#ffcdd2
```
## Step 1: Create Customer Profiles
Customer Profiles are **simulated customers** that interact with your AI agent. Each profile represents a different type of customer with unique behaviors, responses, and scenarios.
### **Accessing the Customer Profile Page**
1. Navigate to: [https://app.vodex.ai/account/test-customer](https://app.vodex.ai/account/test-customer)
2. Click the **"Add New Customer"** button
3. You'll see a form with several fields to configure
### **Customer Profile Fields**
Here's what each field means and how to fill it out:
### Customer Name
**What it is:** A unique identifier for this customer profile.
**Purpose:** Helps you quickly identify which customer scenario you're testing.
**Examples:**
* "Sarah - Interested Buyer"
* "John - Difficult Customer"
* "Maria - Payment Ready"
* "David - Needs More Info"
Use descriptive names that instantly tell you what type of customer this profile represents.
### Short Description
**What it is:** A brief summary of the customer's behavior and scenario.
**Purpose:** Quick reference to understand what this profile tests.
**Examples:**
* "Loan clear today, agree RPC"
* "Customer wants to reschedule appointment"
* "Payment declined, needs alternative method"
* "Interested but has budget concerns"
Keep it under 100 characters for easy scanning in your test dashboard.
### Customer Scenario
**What it is:** A detailed description of who the customer is, their situation, and how they should behave.
**Purpose:** Teaches the AI model how to impersonate this customer realistically.
**What to include:**
* Customer's background and situation
* Their goals or concerns
* How they should respond to agent questions
* Their personality traits (friendly, skeptical, busy, etc.)
* Any specific objections they should raise
**Example 1 - Payment Collection:**
```
You are Michael Thompson, a 35-year-old business owner who has an overdue
invoice of $500 from 30 days ago. You've been busy with your business and
forgot about the payment. When the AI agent calls, you should:
- Be apologetic about the missed payment
- Confirm you received the invoice
- Express willingness to pay immediately
- Ask if you can pay by credit card
- If asked about amount, confirm it's $500
- Thank the agent for the reminder
```
**Example 2 - Difficult Customer:**
```
You are Lisa Chen, a 42-year-old professional who is very busy and
skeptical of sales calls. You have a loan but you're frustrated because:
- You believe you already made a payment
- You're in a meeting and don't have time for a long call
- You want written confirmation before discussing anything
- You should be polite but firm
- If the agent is respectful and brief, you'll engage
- If the agent is pushy, you'll end the call
```
**Example 3 - Appointment Booking:**
```
You are Robert James, a 28-year-old who's interested in a consultation
but has specific scheduling needs. When the AI agent calls, you should:
- Express interest in the service
- Say you're only available on Thursdays after 3 PM
- Ask how long the appointment will take
- Request a reminder text message
- Confirm your phone number and email
- Thank the agent and express excitement
```
### User Fields
**What it is:** Key-value pairs that provide specific data about the customer.
**Purpose:** Allows your agent to access customer-specific information during the call.
**Common Fields:**
| Field Name | Example Value | When to Use |
| ----------------- | ------------------ | --------------------------------- |
| `Amount` | `500.00` | Payment collection calls |
| `Merchant` | `ABC Store` | Purchase-related conversations |
| `DueDate` | `2025-11-30` | Payment reminders |
| `AppointmentDate` | `2025-12-01` | Appointment confirmations |
| `LoanID` | `LN-12345` | Loan-related calls |
| `CustomerID` | `CUST-789` | General customer identification |
| `today` | `NA` | When using time-sensitive prompts |
| `time_zone` | `America/New_York` | For time zone calculations |
**Example Configuration:**
```json theme={null}
{
"Amount": "1250.00",
"Merchant": "Tech Solutions Inc",
"DueDate": "2025-11-20",
"CustomerID": "CUST-4567",
"today": "NA",
"time_zone": "America/Los_Angeles"
}
```
**Special Fields to Note:**
* If your prompt contains **"today"** or references to the current date, you MUST add a `today` field with value `"NA"`
* For **"time\_zone"**, use standard timezone names like `"America/New_York"`, `"Europe/London"`, etc.
### **Complete Customer Profile Example**
Here's a fully filled out customer profile for reference:
**Customer Name:** Sarah - Ready to Pay
**Short Description:** Customer acknowledges debt and wants to clear it today
**Customer Scenario:**
```
You are Sarah Martinez, a 31-year-old teacher who has an outstanding balance
of $850 with LoanCo. You received several reminder emails but have been dealing
with family issues and forgot to pay.
When the AI agent calls:
- Apologize for the delay and explain you've been dealing with personal matters
- Confirm you remember the loan
- Express that you want to clear it today
- Ask if you can pay by credit card over the phone
- Confirm the amount is $850
- Ask for a confirmation email after payment
- Thank the agent for being understanding
- Be friendly and cooperative throughout
If asked about your availability: You're available now and want to complete
the payment immediately.
If asked about payment method: Prefer credit card, but can do bank transfer
if needed.
```
**User Fields:**
```json theme={null}
{
"Amount": "850.00",
"LoanID": "LN-98765",
"DueDate": "2025-11-15",
"CustomerID": "CUST-2345",
"CustomerName": "Sarah Martinez",
"today": "NA",
"time_zone": "America/Chicago"
}
```
### **Creating Multiple Customer Profiles**
For comprehensive testing, create profiles that cover:
**Essential Test Scenarios:**
* โ
**Happy Path** - Cooperative customer who completes the objective
* โ
**Objection Handler** - Customer with concerns or questions
* โ
**Difficult Customer** - Skeptical or resistant customer
* โ
**Busy Customer** - Person who has limited time
* โ
**Confused Customer** - Doesn't understand or needs clarification
* โ
**Edge Case** - Unusual situations or unexpected responses
## Step 2: Test Your AI Agent
Once you've created customer profiles, it's time to test your AI agent against them.
### **Starting a Test**
1. **Navigate to Your Agent:**
* Go to the **Agents** section in your dashboard
* Find the AI agent you want to test
2. **Access Test Options:**
* Click the **three dots (โฎ)** next to your agent's name
* Select **"Test Agent"** from the dropdown menu
3. **Configure the Test:**
You'll see a test configuration screen with these options:
### Choose Customer Profiles
**What to do:** Select one or more customer profiles you created in Step 1.
**Options:**
* **Single profile** - Test one specific scenario
* **Multiple profiles** - Test several scenarios in batch
**Best Practice:**
```
Start with 3-5 profiles that cover:
1. Your ideal customer (happy path)
2. A common objection scenario
3. A difficult customer scenario
```
You can run multiple profiles simultaneously to speed up testing.
### Choose the Customer Model
**What it is:** The AI model that will impersonate your test customers.
**Purpose:** Different models have different conversation styles and capabilities.
**View All Available Models:** Check out our [Call Settings Overview](/call-settings/overview#ai-model-selection) for a complete list of available AI models, their capabilities, and recommendations for different use cases.
**Quick Recommendations:**
* **Complex scenarios**: Use advanced models like GPT-4 or Claude Sonnet
* **Simple scenarios**: Use efficient models like GPT-3.5 or Claude Haiku
* **Natural conversations**: Claude models excel at human-like dialogue
Most users should start with **GPT-4** or **Claude Sonnet** for comprehensive testing.
4. **Start Testing:**
* After selecting profiles and model, click **"Start Testing"**
* The system will begin running automated conversations
* Each profile will interact with your agent independently
### **What Happens During Testing?**
```mermaid theme={null}
sequenceDiagram
participant System
participant Customer AI
participant Your Agent
System->>Your Agent: Initiates test call
Your Agent->>Customer AI: Greeting message
Customer AI->>Your Agent: Responds based on profile
Your Agent->>Customer AI: Continues conversation
Customer AI->>Your Agent: Follows scenario instructions
Note over Your Agent,Customer AI: Conversation continues
up to 25 turns
Your Agent->>Customer AI: Completes objective or ends call
System->>System: Logs results (Success/Failed)
```
**Test Duration:** Each test conversation runs automatically and completes within 1-3 minutes depending on complexity. Each test costs \$0.02 per customer profile.
## Step 3: View Test Results
After testing completes, you can review the results and identify areas for improvement.
### **Accessing Test Results**
1. **Return to Your Agent:**
* Go back to the **Agents** section
* Find the same AI agent you tested
2. **Open Test Progress:**
* Click the **three dots (โฎ)** next to the agent
* Select **"Test Agent Progress"**
3. **Review Results Dashboard:**
* You'll see a list of all test runs with their status
### **Understanding Test Status**
### Success Status
**What it means:** The conversation completed gracefully without errors.
**Success indicators:**
* Agent followed the prompt correctly
* All custom fields were accessible
* Conversation reached a natural conclusion
* No system errors occurred
**What to check:**
* Read the conversation transcript
* Verify the agent achieved its objective
* Check if the tone and responses were appropriate
* Confirm all tags (like `(disconnect)`) worked correctly
**Even if marked "Success", you should review:**
* Did the agent sound natural?
* Was the conversation efficient?
* Could anything be improved?
A "Success" status means technical success - still review for quality!
### Failed Status
**What it means:** Something went wrong during the conversation.
**Common reasons for failure:**
1. **Custom Field Issues**
* Missing required custom fields
* Incorrect field names (case-sensitive)
* Invalid field values
2. **System Errors**
* Connection timeout
* API rate limits exceeded
* Model unavailable
3. **Configuration Problems**
* Incomplete prompt setup
* Missing agent configuration
* Invalid tags in prompt
**How to troubleshoot:**
```
Step 1: Check the error message in the test results
Step 2: Verify all custom fields are correctly configured
Step 3: Review your agent prompt for syntax errors
Step 4: Ensure all required fields have values
Step 5: Re-run the test after fixes
```
**Most common cause:** Missing or incorrectly named custom fields in your prompt vs. customer profile.
### 25-Turn Conversation Limit
**What it is:** Every test conversation is limited to 25 turns (back-and-forth exchanges).
**Why it exists:** Prevents infinite loops and ensures efficient conversations.
**What counts as a turn:**
* 1 turn = Agent speaks, then customer responds
* 25 turns = approximately 10-15 minutes of conversation
**If you hit the limit:**
| Situation | What It Means | What To Do |
| ----------------------------------------------- | ------------- | --------------------------------- |
| **Agent accomplishes goal before 25 turns** | โ
Perfect | No action needed |
| **Conversation naturally ends before 25 turns** | โ
Good | Consider if it could be shorter |
| **Hits 25 turns without completing** | โ ๏ธ Issue | Simplify your prompt or objective |
| **Repetitive conversation** | โ Problem | Fix conversation loop in prompt |
**Red Flag:** If you consistently hit the 25-turn limit, your prompt may be too complex or contain logic loops.
### **Analyzing Conversation Transcripts**
When reviewing test results, look for these key elements:
#### โ
**Natural Flow**
* [ ] Agent sounds conversational, not robotic
* [ ] Smooth transitions between topics
* [ ] Appropriate pauses and acknowledgments
* [ ] Natural response to customer questions
#### โ
**Objective Achievement**
* [ ] Agent stayed focused on the goal
* [ ] Successfully completed the intended action
* [ ] Didn't get sidetracked by irrelevant topics
* [ ] Used appropriate closing statements
#### โ
**Objection Handling**
* [ ] Acknowledged customer concerns
* [ ] Provided helpful responses
* [ ] Didn't sound defensive or pushy
* [ ] Offered alternatives when appropriate
#### โ
**Technical Correctness**
* [ ] All custom fields displayed correctly
* [ ] Tags triggered appropriate actions
* [ ] No error messages in conversation
* [ ] Transfers and disconnects worked properly
#### โ
**Professional Tone**
* [ ] Maintained consistent personality
* [ ] Used appropriate language
* [ ] Showed empathy when needed
* [ ] Ended conversation gracefully
## Testing Costs and Billing ๐ฐ
Automated testing is extremely cost-effective:
**Pricing Structure:**
* **Cost per test:** \$0.02 per customer profile test
* **Pay as you go:** Only pay for the tests you run
* **Billing cycle:** All charges accumulate throughout the day and are deducted at the end of the day
* **No subscription fees:** No daily or monthly charges - only pay when you test
### **Cost Examples**
| Testing Activity | Number of Tests | Cost |
| ------------------------------ | --------------- | ------ |
| Run 5 customer profile tests | 5 | \$0.10 |
| Run 10 customer profile tests | 10 | \$0.20 |
| Run 50 customer profile tests | 50 | \$1.00 |
| Run 100 customer profile tests | 100 | \$2.00 |
| No testing | 0 | \$0.00 |
**Example Billing Cycle:**
```
Monday:
- 9:00 AM: Test Agent with 3 profiles = $0.06
- 2:00 PM: Test Agent with 5 profiles = $0.10
- 5:00 PM: Test Agent with 2 profiles = $0.04
Total deducted at end of Monday: $0.20
```
**Value Proposition:** At just 2 cents per test, you can thoroughly validate your agents before deploying them to real customers, ensuring quality and reducing costly mistakes.
## Best Practices for Automated Testing
### **1. Create a Comprehensive Test Suite**
Build a library of customer profiles that cover all scenarios:
```
Essential Profiles to Create:
โโโ Happy Path
โ โโโ Eager customer
โ โโโ Cooperative customer
โโโ Common Objections
โ โโโ Price concerns
โ โโโ Timing issues
โ โโโ Need more information
โโโ Difficult Scenarios
โ โโโ Angry customer
โ โโโ Skeptical customer
โ โโโ Very busy customer
โโโ Edge Cases
โโโ Language barriers
โโโ Hearing difficulties
โโโ Unexpected situations
```
### **2. Test Before Every Major Change**
Run your test suite whenever you:
* โ
Update your agent prompt
* โ
Add new custom fields
* โ
Change call flow logic
* โ
Modify greeting or voicemail messages
* โ
Update objection handling strategies
### **3. Iterate Based on Results**
Use this continuous improvement cycle:
```mermaid theme={null}
graph LR
A[Run Tests] --> B[Review Results]
B --> C[Identify Issues]
C --> D[Update Prompt]
D --> E[Run Tests Again]
E --> F{All Tests Pass?}
F -->|No| B
F -->|Yes| G[Deploy to Production]
G --> H[Monitor Real Calls]
H --> I[Create New Test Profiles]
I --> A
```
### **4. Document Your Test Scenarios**
Keep a record of:
* What each customer profile tests
* Expected outcomes for each profile
* Changes made based on test results
* Performance improvements over time
### **5. Test with Realistic Data**
**Important:** Use realistic but not actual customer data in your test profiles. Create fictional but plausible scenarios that mirror real situations.
## Troubleshooting Common Issues
### **Issue 1: Test Shows Success but Conversation Quality is Poor**
**Problem:** Test passes technically but the conversation doesn't sound good.
**Solution:**
1. Read the full transcript carefully
2. Identify specific lines that sound unnatural
3. Update your prompt with better instructions
4. Add more example responses to guide the agent
5. Test again with the same profile
***
### **Issue 2: Tests Keep Failing with Custom Field Errors**
**Problem:** Agent can't access custom fields in the conversation.
**Solution:**
1. Check field names are **exactly the same** in:
* Your agent prompt
* Your customer profile
2. Field names are **case-sensitive** (`Amount` โ `amount`)
3. Ensure all fields referenced in your prompt exist in the customer profile
4. Verify field values are in the correct format
**Example Fix:**
โ **In Prompt:** `The amount due is {total_amount}`\
โ **In Profile:** `"Amount": "500"`\
โ
**Fixed:** Both use `"total_amount"` or both use `"Amount"`
***
### **Issue 3: Hitting the 25-Turn Limit Regularly**
**Problem:** Conversations are too long and hit the maximum turn limit.
**Solution:**
1. Simplify your agent's objectives
2. Remove unnecessary questions from the prompt
3. Add clearer exit criteria to end calls sooner
4. Check for conversation loops (agent repeating same questions)
5. Use tags like `(disconnect)` more strategically
***
### **Issue 4: Customer AI Doesn't Follow the Scenario**
**Problem:** The AI impersonating the customer doesn't behave as described in the profile.
**Solution:**
1. Make the customer scenario more specific and detailed
2. Use clear imperative language ("You should...", "Always...", "Never...")
3. Provide example responses in the scenario
4. Test with a more advanced AI model (GPT-4 or Claude)
5. Break complex scenarios into simpler ones
***
### **Issue 5: Tests Pass But Real Calls Fail**
**Problem:** Automated tests work but real customer calls have issues.
**Solution:**
1. Create more realistic customer profiles
2. Add profiles for unexpected customer behaviors
3. Include interruptions and side questions in scenarios
4. Test with more varied customer personalities
5. Review real call recordings and create profiles that match
## Advanced Testing Strategies
### **Regression Testing**
Create a **baseline test suite** that you run before every deployment:
```
Baseline Test Suite:
1. Happy path customer (should always pass)
2. Common objection (tests objection handling)
3. Difficult customer (tests resilience)
4. Quick call (tests efficiency)
5. Complex scenario (tests advanced logic)
```
### **A/B Testing Your Prompts**
Test different versions of your agent:
1. Create Agent Version A with one prompt approach
2. Create Agent Version B with a different prompt approach
3. Run the same customer profiles against both
4. Compare results to see which performs better
5. Deploy the winning version
### **Stress Testing**
Test extreme scenarios:
* Very long customer responses
* Customer who constantly interrupts
* Customer who goes completely off-topic
* Customer who is extremely emotional
* Multiple objections in one call
### **Progressive Testing**
Start simple and increase complexity:
```
Week 1: Test basic scenarios (happy path)
Week 2: Add common objections
Week 3: Add difficult customers
Week 4: Add edge cases
Week 5: Add stress tests
```
## Success Metrics
Track these metrics to measure testing effectiveness:
| Metric | How to Calculate | Target |
| --------------------- | -------------------------------------- | ------------------ |
| **Test Pass Rate** | (Successful tests / Total tests) ร 100 | >90% |
| **Average Turns** | Total turns / Number of tests | \<15 turns |
| **Scenario Coverage** | Number of scenarios tested | All critical paths |
| **Issues Found** | Problems identified before production | Track trend |
| **Time to Fix** | Time from issue found to resolved | \<1 day |
## Next Steps
Now that you understand automated testing:
1. **Start small** - Create 3-5 customer profiles for your most common scenarios
2. **Run your first test** - Test your agent with these profiles
3. **Review results** - Carefully read the transcripts and identify improvements
4. **Iterate** - Update your prompt based on findings
5. **Expand coverage** - Gradually add more profiles for edge cases
6. **Make it routine** - Run tests before every significant change
**Ready to start testing?** Head to [https://app.vodex.ai/account/test-customer](https://app.vodex.ai/account/test-customer) and create your first customer profile today!
***
## Related Resources
**Want to improve your agent's responses?** Check out our [Prompt Guide](/agents/prompt) to learn how to write more effective instructions.
**Need to add automated actions?** Visit our [Tags Guide](/agents/tags) to learn about special commands like `(disconnect)` and `(transfer)`.
**Just getting started?** Read our [Agents Overview](/agents/overview) to understand the basics of AI agent creation.
# ๐ค Agents Overview
Source: https://docs.vodex.ai/agents/overview
Learn how to create and configure AI agents for your phone calls - a complete step-by-step guide
**What you'll learn:** How to create AI agents that can make phone calls, what information you need to provide, and how to set them up step by step.
## What Are AI Agents?
Think of an AI agent as a **virtual employee** that can make phone calls for you. Just like a real person, it needs:
* A name to identify itself
* Instructions on what to say
* Rules to follow during conversations
* The ability to handle different situations
## How to Create Your First AI Agent
Creating an AI agent is like filling out a form - you provide information, and the system builds your virtual caller. Here's how it works:
## Visual Guide: Agent Creation Process
Here's a simple flowchart showing the complete agent creation process:
```mermaid theme={null}
flowchart TD
A[Go to Agents Section] --> B[Click + Add New Agent]
B --> C[Step 1: Basic Information]
C --> D[Enter Agent Name]
C --> E[Enter Organization Name]
D --> F[Step 2: Call Messages]
E --> F
F --> G[Set Greeting Message]
F --> H[Set Voicemail Message]
G --> I[Step 3: Call Context]
H --> I
I --> J[Configure AI Agent Prompt]
J --> K[Connect to Prompt Settings]
K --> L[Step 4: Add Rules]
L --> M[Set Behavior Boundaries]
M --> N[Configure Safety Guidelines]
N --> O[Step 5: Save Agent]
O --> P[Agent Created Successfully!]
P --> Q[Agent Ready to Use]
Q --> R[Can Edit Anytime]
Q --> S[Can Test with Sample Call]
Q --> T[Ready for Campaigns]
style A fill:#e1f5fe
style P fill:#c8e6c9
style Q fill:#fff3e0
```
### **Step 1: Start Creating Your Agent**
1. Go to the **Agents section** in your dashboard
2. Click the **"Add New Agent"** button
3. You'll see a form with several sections to fill out
### **Step 2: Basic Agent Information**
This is where you give your agent its identity:
| Field | What to Enter | Example |
| --------------------- | -------------------------------- | ----------------------------- |
| **Agent Name** | What you want to call your agent | "Sarah from Customer Service" |
| **Organization Name** | Your company or business name | "ABC Corporation" |
**Important:** Choose a clear, professional name for your agent. This is what callers will hear when they answer the phone.
### **Step 3: Call Messages**
These are the messages your agent will say in different situations:
#### **Greeting Message**
* **What it is:** The first thing your agent says when someone answers the phone
* **When it's used:** Every time someone picks up the call
* **Example:** "Hello, this is Sarah from ABC Corporation. I'm calling about your recent order."
#### **Voicemail Message**
* **What it is:** What your agent says when the call goes to voicemail
* **When it's used:** When no one answers and the call goes to voicemail
* **Example:** "Hi, this is Sarah from ABC Corporation. Please call me back at 555-123-4567 when you have a moment."
**Pro Tip:** Keep your messages clear, friendly, and professional. People are more likely to respond positively to a well-crafted message.
### **Step 4: Call Context (The Brain)**
This is where you give your agent its **intelligence** - what it knows and how it should behave:
1. **Click "Next"** after filling out the basic information
2. **You'll see the Call Context section**
3. **This connects to your [Prompt](/agents/prompt) settings** - click on "prompt" to go to that page
4. **The prompt contains all the instructions** your agent needs to have natural conversations
Think of the prompt as a **script and rulebook** that tells your agent:
* How to introduce itself
* What questions to ask
* How to handle different responses
* When to transfer calls
* How to end conversations
**Key Point:** The prompt is the most important part of your agent. It determines how smart and effective your agent will be in conversations.
### **Step 5: Add Rules (The Boundaries)**
After setting up the call context, you'll move to the **Rules section**:
1. **Click "Next"** to proceed from Call Context
2. **You'll see the Add Rules section**
3. **Rules help control your agent's behavior** and set limits
Rules are like **safety guidelines** that prevent your agent from:
* Going off-topic
* Making inappropriate statements
* Spending too long on calls
* Violating company policies
## What Happens After You Create an Agent?
Once you've completed all the steps:
1. **Click Save** then it is ready to use
2. **You can test it** with a sample call
3. **You can edit it** anytime to make improvements
4. **You can use it** in campaigns or individual calls
## Common Questions About Agents
### **How Many Agents Can I Create?**
* You can create as many agents as you need
* Each agent can have different personalities and purposes
* You might have one for sales, another for customer service, etc.
### **Can I Change My Agent Later?**
* **Yes!** You can edit your agent anytime
* Change the name, messages, or rules
* Update the prompt to improve performance
* Test different versions to see what works best
### **What Makes a Good Agent?**
* **Clear purpose** - Knows exactly what it's calling about
* **Professional tone** - Sounds trustworthy and helpful
* **Good instructions** - Has a well-written prompt
* **Appropriate rules** - Stays within boundaries
* **Natural conversation** - Doesn't sound robotic
## Best Practices for Creating Agents
### **1. Start Simple**
* Begin with basic information
* Add complexity gradually
* Test before adding advanced features
### **2. Be Specific**
* Give your agent a clear role
* Write specific, actionable instructions
* Set realistic expectations
### **3. Test and Improve**
* Always test your agent before using it
* Listen to call recordings
* Make adjustments based on results
* Ask for feedback from your team
### **4. Keep It Professional**
* Use appropriate language
* Avoid slang or jargon
* Maintain a consistent tone
* Follow your company's voice
## Next Steps
Now that you understand how to create agents:
1. **Go to the Agents section** and click "Add New Agent"
2. **Fill out the basic information** (name, organization, messages)
3. **Set up the call context** by configuring your [prompt](/agents/prompt)
4. **Add appropriate rules** to keep your agent on track
5. **Test your agent** to make sure it works correctly
**Ready to create your first AI agent?** Follow these steps to build a professional, effective virtual caller that represents your business perfectly.
***
**Need help with prompts?** Check out our [Prompt Guide](/agents/prompt) to learn how to write effective instructions for your AI agents.
**Want to learn about tags?** Visit our [Tags Guide](/agents/tags) to understand how to add special commands to your prompts.
# โ๏ธ Creating Effective AI Call Prompts
Source: https://docs.vodex.ai/agents/prompt
Learn how to design clear, structured AI call prompts that sound natural and achieve your goals
**What you'll learn:** How to design AI call prompts that sound natural, handle objections gracefully, and achieve your business objectives.
## Overview
Creating an effective AI call prompt is like writing a detailed instruction manual for your AI agent. The goal is to design a clear, structured set of instructions that teach the bot how to sound natural, handle different scenarios, and achieve the purpose of the call.
## Key Components of a Great Prompt
### 1. **Define Your Objective** ๐ฏ
Before writing anything, clearly identify what you want the AI to accomplish:
* **Lead Qualification** - Determine if prospects meet your criteria
* **Appointment Booking** - Schedule meetings or consultations
* **Payment Collection** - Process payments or collect outstanding balances
* **Customer Updates** - Provide status updates or information
* **Survey Collection** - Gather feedback or data
**Pro tip:** Every part of your prompt should align with your primary objective. Don't mix multiple goals in a single prompt.
### 2. **Set the AI Personality** ๐ค
Define how your AI should behave during conversations:
| Personality Type | Tone | Best For | Example Use Case |
| -------------------------- | --------------------- | ---------------------------- | -------------------------------------- |
| **Warm & Persuasive** | Friendly, encouraging | Sales calls, lead generation | Converting prospects to customers |
| **Professional & Neutral** | Formal, informative | B2B communications | Technical support, corporate updates |
| **Empathetic & Helpful** | Caring, supportive | Customer service | Resolving issues, providing assistance |
**What to Include:**
* Tone and style guidelines
* Language preferences (formal vs. casual)
* What to avoid (robotic responses, overly casual language)
**Example Personality Setting:**
```markdown theme={null}
The AI should sound warm and professional, like a helpful customer service representative.
Use a friendly tone but maintain professionalism. Avoid sounding robotic or overly casual.
Always be empathetic to the customer's needs and concerns.
```
### 3. **Design the Conversation Flow** ๐
Unlike static scripts, AI prompts should be dynamic and teach the bot how to respond naturally:
#### Basic Flow Structure
```mermaid theme={null}
graph TD
A[Start Call] --> B[Greet & Identify]
B --> C[Explain Purpose]
C --> D[User Response]
D --> E{Positive?}
E -->|Yes| F[Proceed with Objective]
E -->|No| G[Handle Objection]
G --> H{Re-engage?}
H -->|Yes| I[Present Benefits]
H -->|No| J[Thank & End]
F --> K[Complete Objective]
K --> L[End Call Successfully]
```
#### Step-by-Step Instructions
Write instructions in the third person as if guiding someone step by step:
```markdown theme={null}
1. After confirming the user's identity, greet them warmly using their name
2. Explain the purpose of the call clearly and concisely
3. Ask if they are open to continuing the conversation
4. If they respond positively, proceed with qualifying questions
5. If they respond negatively, acknowledge their time and ask if there's a better time
6. If they still decline, thank them politely and end the call
```
### 4. **Handle Objections Gracefully** ๐ก๏ธ
Prepare structured responses for common pushbacks:
#### "I'm not interested right now"
**Response Strategy:**
* Acknowledge their time and current situation
* Offer to call back at a better time
* Provide a soft benefit or alternative
**Example Response:**
```
"I completely understand you're busy right now. Would it be better if I called you back
tomorrow afternoon? Or perhaps you'd prefer to receive our information via email instead?"
```
#### "I need to think about it"
**Response Strategy:**
* Respect their decision-making process
* Offer additional information or resources
* Set a follow-up timeline
**Example Response:**
```
"Of course, this is an important decision. I'd be happy to send you some additional
information to help with your decision. When would be a good time to follow up with you?"
```
#### "I'm not the right person"
**Response Strategy:**
* Thank them for their time
* Ask for the correct contact person
* Request permission to transfer the call
**Example Response:**
```
"Thank you for letting me know. Could you please direct me to the person who handles
[relevant topic]? Or would you prefer to take a message and have them call me back?"
```
### 5. **Plan for Every Outcome** ๐
Anticipate all possible responses and ensure the AI knows how to handle them:
**Complete Coverage:** A well-structured prompt should cover positive, negative, and neutral responses with clear next steps for each.
#### Response Categories
| Response Type | AI Action | Example |
| ------------- | ---------------------------------- | ------------------------------------------- |
| **Positive** | Proceed with objective | "Great! Let me ask you a few questions..." |
| **Negative** | Handle objection or end gracefully | "I understand. Thank you for your time." |
| **Neutral** | Gather more information | "Could you tell me more about that?" |
| **Confused** | Clarify and simplify | "Let me explain this in a different way..." |
## Best Practices
### โ
**Do's**
* **Keep it simple** - Use clear, straightforward language
* **Test thoroughly** - Run multiple scenarios to catch edge cases
* **Update regularly** - Refine based on real-world performance
* **Include examples** - Provide sample responses for common situations
* **Set clear boundaries** - Define what the AI should and shouldn't do
### โ **Don'ts**
* **Overcomplicate** - Don't create overly complex branching logic
* **Forget edge cases** - Always plan for unexpected responses
* **Ignore tone** - Don't let the AI sound robotic or unprofessional
* **Mix objectives** - Don't try to accomplish multiple goals in one prompt
* **Skip testing** - Always validate your prompt before deployment
## Template Structure
Here's a complete template you can use as a starting point:
```markdown theme={null}
# AI Call Prompt Template
## Objective
[Clearly state what the AI should accomplish]
## Personality
[Define tone, style, and behavior guidelines]
## Conversation Flow
1. [Step-by-step instructions]
2. [Include branching logic]
3. [Handle different responses]
## Objection Handling
- [Common objection 1]: [Response strategy]
- [Common objection 2]: [Response strategy]
## Success Criteria
[Define what constitutes a successful call]
## End Call Instructions
[How to properly conclude the conversation]
```
## Testing Your Prompt
Before deploying, test your prompt with these scenarios:
### **Happy Path Testing**
* User is interested and engaged
* User has all necessary information
* Call proceeds smoothly to completion
### **Objection Testing**
* User raises common objections
* User seems hesitant or unsure
* User is in a hurry or distracted
### **Edge Case Testing**
* User speaks a different language
* User has hearing difficulties
* User is in a noisy environment
* User needs to put you on hold
### **End-of-Call Testing**
* User agrees to next steps
* User declines further contact
* User requests follow-up information
## Common Mistakes to Avoid
**Watch out for these common pitfalls that can make your AI sound robotic or ineffective.**
1. **Too Many Rules** - Overly complex prompts confuse the AI
2. **Missing Context** - AI doesn't understand the business context
3. **Poor Objection Handling** - AI gets stuck when users push back
4. **Inconsistent Tone** - AI switches between different personalities
5. **No Fallback Plans** - AI doesn't know what to do in unexpected situations
## Success Metrics
Track these metrics to measure your prompt's effectiveness:
| Metric | What It Measures | Target |
| ---------------------- | ------------------------------------------------ | ----------------------- |
| **Completion Rate** | Percentage of calls that achieve their objective | >80% |
| **Objection Handling** | Success rate of overcoming common objections | >70% |
| **User Satisfaction** | Customer feedback on call quality | >4.5/5 |
| **Call Duration** | Average length of successful calls | Optimize for efficiency |
## Next Steps
Now that you understand the fundamentals of creating effective AI call prompts:
1. **Start with a simple objective** - Don't try to do everything at once
2. **Use the template** - Follow the structure provided above
3. **Test thoroughly** - Run multiple scenarios before deployment
4. **Iterate and improve** - Refine based on real-world performance
5. **Document your learnings** - Keep track of what works and what doesn't
**Ready to create your first prompt?** Start with the template above and customize it for your specific use case. Remember, the key is to be clear, comprehensive, and always think about the user's perspective.
***
**Need help?** Check out our [Tags documentation](/agents/tags) to learn how to organize and categorize your prompts effectively.
# ๐ท๏ธ Understanding AI Prompt Tags
Source: https://docs.vodex.ai/agents/tags
Learn how to use special tags in your AI prompts to trigger automated actions and backend processes
**What you'll learn:** How to use special tags in your AI prompts to automatically trigger actions like ending calls, sending SMS messages, and transferring to live agents.
## What Are AI Prompt Tags?
Think of tags as **special instructions** that you hide inside your AI prompt. While the main prompt teaches the AI what to say and how to handle conversations, tags handle what happens **after** the AI finishes speaking.
Tags are like secret commands that tell the backend system: "Hey, do this specific action right now!"
## Why Are Tags Important? ๐ฏ
Tags solve a big problem: **seamless automation**. Instead of writing complicated instructions for every possible scenario, you use simple tags as shortcuts to trigger actions instantly.
### **The Problem Without Tags:**
* AI says goodbye but doesn't know how to end the call
* User needs help but AI doesn't know how to transfer to a human
* Follow-up information needs to be sent but AI doesn't know how
### **The Solution With Tags:**
* AI says goodbye and automatically ends the call
* AI transfers difficult calls to human agents instantly
* AI sends follow-up SMS messages automatically
## How Tags Work ๐ง
Tags work like this:
1. **AI delivers its message** (what it says to the user)
2. **Tag triggers an action** (what happens behind the scenes)
3. **User gets the result** (call ends, SMS sent, transfer happens)
It's like having a smart assistant who not only talks to people but also knows exactly what to do next without being told twice.
## Common Tags and Their Purposes
### **1. (disconnect) - End the Call**
**What it does:** Immediately ends the call after the AI finishes speaking.
**When to use:** When the conversation is complete and you want to end the call politely.
**Example:**
```
"Thank you for your time today. Have a wonderful day!" (disconnect)
```
**What happens:** AI says goodbye, then the call automatically ends.
***
### **2. (transfer) - Connect to Human Agent**
**What it does:** Moves the call directly to a live human agent.
**When to use:** When the user needs help that only a human can provide, or when the situation is too complex for the AI.
**Example:**
```
"I understand this is complicated. Let me transfer you to a specialist who can better assist you." (transfer)
```
**What happens:** AI explains the transfer, then the call automatically moves to a human agent.
***
### **3. (sms) - Send Follow-up Message**
**What it does:** Sends an automated text message to the user after the call.
**When to use:** When you need to send links, instructions, or confirmation details that the user can reference later.
**Example:**
```
"I've just sent you the application link by text message. You'll receive it in a moment." (sms)
```
**What happens:** AI tells the user about the SMS, then the system automatically sends the text message.
***
### **4. (sms+transfer) - Send SMS and Transfer**
**What it does:** Combines two actions: sends an SMS and then transfers the call to a human agent.
**When to use:** When you want to provide information AND get the user immediate human assistance.
**Example:**
```
"I've sent you the details by text and will now connect you to our specialist who can answer your questions." (sms+transfer)
```
**What happens:** AI sends the SMS, then automatically transfers the call to a human agent.
***
### **5. (sms+disconnect) - Send SMS and End Call**
**What it does:** Sends an SMS message and then politely ends the call.
**When to use:** When you need to provide follow-up information but the conversation is complete.
**Example:**
```
"I've sent the payment link to your phone. Please check it when you have a moment. Thank you for calling!" (sms+disconnect)
```
**What happens:** AI sends the SMS, then automatically ends the call.
## Where to Place Tags in Your Prompts
### **Golden Rule: Place tags AFTER the AI's final spoken words**
Tags should always come at the very end of what you want the AI to say. Think of it like this:
**โ Wrong Placement:**
```
(disconnect) "Thank you for calling. Have a great day!"
```
**โ
Correct Placement:**
```
"Thank you for calling. Have a great day!" (disconnect)
```
### **Why This Matters:**
1. **AI speaks first** - User hears the complete message
2. **Tag triggers action** - Backend system performs the action
3. **Seamless transition** - No awkward pauses or confusion
## Real-World Examples
### **Example 1: Simple Call Ending**
**Scenario:** Lead qualification call where the prospect isn't interested.
**Prompt:**
```
"Thank you for your time today. I understand this isn't the right fit for you right now.
We'll keep your information on file, and if anything changes, feel free to reach out.
Have a wonderful day!" (disconnect)
```
**What happens:** AI politely ends the conversation, then the call automatically disconnects.
***
### **Example 2: Transfer with Information**
**Scenario:** Customer needs technical support that requires human assistance.
**Prompt:**
```
"I understand you're experiencing a technical issue. I've sent you a troubleshooting guide
by text message, and now I'll connect you to our technical support team who can help
you resolve this immediately." (sms+transfer)
```
**What happens:** AI sends troubleshooting guide via SMS, then transfers the call to technical support.
***
### **Example 3: Follow-up with Call Ending**
**Scenario:** Appointment reminder call where the user confirms they'll attend.
**Prompt:**
```
"Perfect! I've sent you a confirmation email and calendar reminder by text message.
Your appointment is confirmed for tomorrow at 2 PM. We look forward to seeing you!" (sms+disconnect)
```
**What happens:** AI sends confirmation details via SMS, then ends the call.
## Best Practices for Using Tags
### **โ
Do's**
* **Keep it simple** - Use one tag per action unless combining makes sense
* **Be clear** - Make sure the AI's message explains what's about to happen
* **Test thoroughly** - Verify that tags trigger the correct actions
* **Use consistently** - Apply the same tag patterns across similar scenarios
### **โ Don'ts**
* **Don't overcomplicate** - Avoid using multiple tags unless necessary
* **Don't hide tags** - Make sure the AI's message explains the action
* **Don't forget context** - Ensure the tag matches the user's needs
* **Don't skip testing** - Always verify tags work as expected
## Common Mistakes to Avoid
### **Mistake 1: Tag in Wrong Location**
**Problem:** Tag appears before the AI's message.
**Solution:** Always place tags at the end of what you want the AI to say.
***
### **Mistake 2: Unclear User Communication**
**Problem:** AI doesn't explain what action is about to happen.
**Solution:** Make sure the AI clearly tells the user what to expect.
***
### **Mistake 3: Inappropriate Tag Usage**
**Problem:** Using (transfer) for simple questions that AI can handle.
**Solution:** Only use (transfer) when human assistance is truly needed.
## Advanced Tag Strategies
### **Combining Tags Effectively**
Some tags work well together, but don't overdo it:
**Good Combinations:**
* `(sms+transfer)` - Provides information AND human help
* `(sms+disconnect)` - Provides information AND ends call
**Avoid:**
* `(disconnect+transfer)` - These contradict each other
* `(sms+sms)` - Redundant and confusing
### **Context-Aware Tagging**
Choose tags based on the conversation outcome:
| Conversation Result | Recommended Tag | Why |
| --------------------------------- | ---------------- | -------------------- |
| **User satisfied, call complete** | `(disconnect)` | Clean ending |
| **User needs human help** | `(transfer)` | Immediate assistance |
| **User needs follow-up info** | `(sms)` | Information delivery |
| **User needs both info and help** | `(sms+transfer)` | Complete solution |
## Testing Your Tags
### **Before Deployment:**
1. **Test each tag individually** - Make sure each one works correctly
2. **Test tag combinations** - Verify that combined tags work as expected
3. **Test user experience** - Ensure the AI's message flows naturally into the action
4. **Test backend integration** - Confirm that actions actually happen
### **Test Scenarios:**
* **Disconnect test:** Does the call end smoothly?
* **Transfer test:** Does the call move to the right agent?
* **SMS test:** Does the message get sent to the correct number?
* **Combination test:** Do multiple actions happen in the right order?
## Troubleshooting Common Issues
### **Problem: Tag Not Working**
**Possible Causes:**
* Tag placed in wrong location
* Tag syntax is incorrect
* Backend system not configured properly
**Solution:** Check tag placement and syntax, then verify backend configuration.
***
### **Problem: Wrong Action Triggered**
**Possible Causes:**
* Tag syntax error
* Backend system confusion
* Multiple conflicting tags
**Solution:** Review tag syntax and ensure only one action is intended.
***
### **Problem: User Confusion**
**Possible Causes:**
* AI doesn't explain what's happening
* Action happens too quickly
* Unexpected behavior
**Solution:** Make sure AI clearly explains the action and timing.
## Implementation Checklist
Use this checklist to implement tags effectively:
* [ ] **Understand your needs** - Identify which actions you want to automate
* [ ] **Choose appropriate tags** - Select tags that match your use cases
* [ ] **Write clear AI messages** - Ensure the AI explains what's about to happen
* [ ] **Place tags correctly** - Put tags at the end of AI messages
* [ ] **Test thoroughly** - Verify all tags work as expected
* [ ] **Train your team** - Make sure everyone understands how tags work
* [ ] **Monitor performance** - Track how tags improve user experience
## Next Steps
Now that you understand how AI prompt tags work:
1. **Review your current prompts** - Identify where tags could improve efficiency
2. **Start with simple tags** - Begin with `(disconnect)` and `(transfer)`
3. **Add SMS functionality** - Implement `(sms)` for follow-up information
4. **Combine when beneficial** - Use combinations like `(sms+transfer)` for complex scenarios
5. **Test and refine** - Continuously improve your tag implementation
**Ready to automate your AI calls?** Start implementing tags in your prompts today. Remember, tags are the bridge between AI conversation and automated action - they make your system smarter and more efficient.
***
**Need help with prompts?** Check out our [Prompt documentation](/agents/prompt) to learn how to create effective AI call prompts that work perfectly with tags.
# Get Call Transcript
Source: https://docs.vodex.ai/api-reference/analyze/gets-ths-transcript-of-a-call-uuid
get /analyze/transcript/{call_uuid}
Retrieve the complete transcript of a call using the call UUID
# Trigger Call
Source: https://docs.vodex.ai/api-reference/call-trigger/trigger-call
post /api/v1/trigger-call
Trigger automated calls with various configurations: basic calls, dynamic fields, campaign organization, or insights collection. The API supports multiple request formats based on your needs.
**๐จ Privacy & Consent Required:** We value the privacy and preferences of customers. Phone calls can only be made to individuals who have explicitly provided their consent. Failing to comply with this policy may result in account suspension.
**โ ๏ธ Terms Confirmation:** By using this API, you confirm that you have obtained the necessary consent from the provided phone numbers to be contacted. Please ensure you have reviewed and agree to our terms and conditions.
## API Overview
The Trigger Call API supports multiple call configurations through a single endpoint. You can trigger:
Simple calls with firstName, lastName, and phone number
Calls with custom fields for personalized conversations
Calls organized under campaign names for tracking
Calls with AI-powered data collection and analysis
## Important Consent Requirements
Before using this API, you **must** ensure:
* โ
**Explicit Consent:** All phone numbers have explicitly consented to receive calls
* โ
**Documentation:** You have documented proof of consent for each contact
* โ
**Compliance:** You comply with local privacy laws (GDPR, CCPA, etc.)
* โ
**Opt-out Options:** You provide clear opt-out mechanisms for contacts
The `consentForCalls` parameter must be set to `true` in your API request to confirm you have obtained proper consent from all contacts.
## Call Configuration Types
### 1. Basic Calls
Use the `basicTriggerCall` schema for simple calls with minimal information:
* `firstName`, `lastName`, `phone`
* `projectId` and `consentForCalls`
### 2. Dynamic Fields Calls
Use the `dynamicFieldsTriggerCall` schema for personalized calls:
* All basic fields plus custom fields (address, email, company, etc.)
* Perfect for agent prompts that use `{customField}` variables
* **Additional Privacy:** Ensure consent for personal data usage
### 3. Campaign Calls
Use the `campaignTriggerCall` schema for organized campaigns:
* All basic fields plus `campaignName`
* Better tracking and analytics
* **Marketing Compliance:** Ensure consent for campaign communications
### 4. Insights Collection
Use the `insightsTriggerCall` schema for data collection:
* All basic fields plus `insights` array with questions
* AI-powered response analysis
* **Survey Consent:** Ensure consent for data collection and AI processing
## Privacy Considerations by Type
* Explicit consent for calling
* Clear opt-out mechanisms
* Compliance with local laws
* Consent for personal data usage
* Data processing transparency
* Custom field privacy protection
* Marketing communication consent
* Campaign tracking disclosure
* Unsubscribe mechanisms
* Survey participation consent
* AI processing disclosure
* Data retention policies
* Response recording notification
## Example Request Bodies
```json Basic Call theme={null}
{
"callList": [
{
"firstName": "John",
"lastName": "Doe",
"phone": "+1234567890"
}
],
"projectId": "your-project-id",
"consentForCalls": true
}
```
```json Dynamic Fields theme={null}
{
"callList": [
{
"firstName": "Jane",
"lastName": "Smith",
"phone": "+1987654321",
"company": "Acme Corp",
"email": "jane@acme.com"
}
],
"projectId": "your-project-id",
"consentForCalls": true
}
```
```json Campaign Call theme={null}
{
"callList": [
{
"firstName": "Bob",
"lastName": "Johnson",
"phone": "+1555123456"
}
],
"projectId": "your-project-id",
"campaignName": "Summer_Sale_2024",
"consentForCalls": true
}
```
```json Insights Collection theme={null}
{
"callList": [
{
"firstName": "Alice",
"lastName": "Brown",
"phone": "+1555987654"
}
],
"projectId": "your-project-id",
"insights": [
{
"question": "How satisfied are you with our service?",
"type": "boolean",
"name": "satisfied"
},
{
"question": "What improvements would you suggest?",
"type": "string",
"name": "suggestion"
}
],
"consentForCalls": true
}
```
The API automatically detects which type of call to trigger based on the fields present in your request body. No need to specify the call type explicitly.
# API Reference Introduction
Source: https://docs.vodex.ai/api-reference/introduction
Get started with the Vodex.ai API for programmatic access to AI-powered voice calling capabilities
Welcome to the Vodex.ai API documentation. This comprehensive API reference provides programmatic access to Vodex.ai's AI-powered voice calling capabilities, allowing you to integrate intelligent voice automation into your applications and workflows.
**What you'll learn:** How to authenticate with the Vodex.ai API, make your first API calls, and integrate voice calling capabilities into your applications.
***
## Base URL
All API requests should be made to the following base URL:
```
https://api.vodex.ai
```
**HTTPS Required:** All API requests must use HTTPS. HTTP requests will be rejected for security reasons.
***
## Authentication
The Vodex.ai API uses API key authentication. You'll need two pieces of information to authenticate your requests:
### Required Headers
**API Key Authentication**
Include your API key in the `Authorization` header of all requests:
```bash theme={null}
Authorization: YOUR_API_KEY
```
**Keep Your API Key Secure:** Never expose your API key in client-side code or public repositories. Store it securely and use environment variables.
**Account Identification**
Include your unique account URL in the `dburl` header:
```bash theme={null}
dburl: YOUR_ACCOUNT_URL
```
**Account URL Format:** Your account URL is provided when you receive your API credentials and identifies your specific Vodex.ai account.
### Complete Authentication Example
```bash cURL Example theme={null}
curl -X GET "https://api.vodex.ai/v1/projects" \
-H "Authorization: YOUR_API_KEY" \
-H "dburl: YOUR_ACCOUNT_URL" \
-H "Content-Type: application/json"
```
```javascript JavaScript/Node.js theme={null}
const headers = {
'Authorization': 'YOUR_API_KEY',
'dburl': 'YOUR_ACCOUNT_URL',
'Content-Type': 'application/json'
};
fetch('https://api.vodex.ai/v1/projects', {
method: 'GET',
headers: headers
})
.then(response => response.json())
.then(data => console.log(data));
```
```python Python theme={null}
import requests
headers = {
'Authorization': 'YOUR_API_KEY',
'dburl': 'YOUR_ACCOUNT_URL',
'Content-Type': 'application/json'
}
response = requests.get('https://api.vodex.ai/v1/projects', headers=headers)
data = response.json()
```
***
## Getting Your API Key
To access the Vodex.ai API, you'll need to request API credentials:
**Request API Access:** Send an email to [support@vodex.ai](mailto:support@vodex.ai) with the subject "Request API Key". Include your company name, use case, expected API usage volume, and technical contact information.
**Email Support**
* Use the exact subject line: "Request API Key"
* Provide detailed information about your use case
* Include your technical requirements
**Get Your API Access**
* Support team will review your request
* You'll receive your API key and account URL
* Documentation and usage guidelines will be provided
**Verify Setup**
* Test authentication with a simple API call
* Verify your headers are correctly configured
* Start with basic endpoints before complex integrations
***
## API Structure
The Vodex.ai API is organized around REST principles and uses standard HTTP response codes. The API accepts and returns JSON-encoded data.
### Core Resources
**Campaign Management**
* Create and manage different bot projects
* Configure project-specific settings
* Organize campaigns by use case or client
**Key Endpoints:**
* `GET /v1/projects` - List all projects
* `POST /v1/projects` - Create new project
* `DELETE /v1/projects/{id}` - Delete project
**Contact Management**
* Upload and manage target audience data
* Segment contacts for different campaigns
* Update contact information and custom fields
**Key Endpoints:**
* `POST /v1/audience` - Create audience list
* `GET /v1/audience` - Retrieve audience data
* `PUT /v1/audience/{id}` - Update audience list
**Campaign Operations**
* Create and configure calling campaigns
* Monitor campaign performance
* Manage campaign lifecycle
**Key Endpoints:**
* `POST /v1/campaign` - Create campaign
* `GET /v1/campaign` - List campaigns
* `DELETE /v1/campaign/{id}` - Delete campaign
**AI Configuration**
* Configure AI agent behavior and responses
* Set up prompts and conversation flows
* Manage agent personalities and voices
**Key Endpoints:**
* `POST /v1/agent-setting` - Create agent configuration
* `GET /v1/agent-setting` - Retrieve agent settings
* `PUT /v1/agent-setting/{id}` - Update agent settings
**Call Execution**
* Initiate automated calls programmatically
* Trigger individual or batch calls
* Monitor call status and outcomes
**Key Endpoints:**
* `POST /v1/call-trigger/run-campaign` - Start campaign calls
***
## Quick Start: Trigger Your First Call
Get started quickly with the most commonly used endpoint - triggering calls:
**Start Making Calls Immediately**
Use the Call Trigger API to programmatically initiate AI-powered calls for your campaigns.
**Quick Access:** `/v1/call-trigger/run-campaign`
### Basic Call Trigger Example
```bash cURL - Trigger Campaign theme={null}
curl -X POST "https://api.vodex.ai/v1/call-trigger/run-campaign" \
-H "Authorization: YOUR_API_KEY" \
-H "dburl: YOUR_ACCOUNT_URL" \
-H "Content-Type: application/json" \
-d '{
"campaignId": "your_campaign_id",
"audienceId": "your_audience_id"
}'
```
```javascript JavaScript - Trigger Campaign theme={null}
const triggerCall = async () => {
const response = await fetch('https://api.vodex.ai/v1/call-trigger/run-campaign', {
method: 'POST',
headers: {
'Authorization': 'YOUR_API_KEY',
'dburl': 'YOUR_ACCOUNT_URL',
'Content-Type': 'application/json'
},
body: JSON.stringify({
campaignId: 'your_campaign_id',
audienceId: 'your_audience_id'
})
});
const result = await response.json();
console.log('Campaign triggered:', result);
};
```
***
## Response Format
All API responses follow a consistent JSON format:
### Success Response
```json theme={null}
{
"success": true,
"data": {
// Response data here
},
"message": "Operation completed successfully"
}
```
### Error Response
```json theme={null}
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error description"
}
}
```
### HTTP Status Codes
| Status Code | Meaning | Description |
| ----------- | --------------------- | ----------------------------- |
| **200** | OK | Request successful |
| **201** | Created | Resource created successfully |
| **400** | Bad Request | Invalid request parameters |
| **401** | Unauthorized | Invalid or missing API key |
| **403** | Forbidden | Insufficient permissions |
| **404** | Not Found | Resource not found |
| **429** | Too Many Requests | Rate limit exceeded |
| **500** | Internal Server Error | Server error occurred |
***
## Rate Limits
The Vodex.ai API implements rate limiting to ensure fair usage and system stability:
**Rate Limits Apply:** API requests are limited based on your account tier. Contact support if you need higher limits for your use case.
### Rate Limit Headers
All API responses include rate limit information in the headers:
```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
```
### Best Practices
**Optimize Your Requests:** Batch operations when possible and implement exponential backoff for retry logic to handle rate limits gracefully.
***
## Common Integration Patterns
### Webhook Integration
Many Vodex.ai API operations support webhooks for real-time notifications:
```json theme={null}
{
"webhookUrl": "https://your-domain.com/webhook",
"events": ["call_completed", "campaign_finished"]
}
```
### Batch Operations
For high-volume operations, use batch endpoints when available:
```json theme={null}
{
"batch": true,
"items": [
{"phone": "+1234567890", "name": "John Doe"},
{"phone": "+1234567891", "name": "Jane Smith"}
]
}
```
***
## SDK and Libraries
While we don't currently provide official SDKs, the API is designed to work seamlessly with standard HTTP libraries in any programming language.
### Recommended Libraries
**HTTP Clients**
* `fetch` (built-in)
* `axios`
* `node-fetch`
**HTTP Clients**
* `requests`
* `httpx`
* `aiohttp`
**HTTP Clients**
* `cURL`
* `Guzzle`
* `file_get_contents`
**HTTP Clients**
* `HttpURLConnection`
* `OkHttp`
* `Apache HttpClient`
***
## Next Steps
Now that you understand the basics:
1. **Request your API key** from [support@vodex.ai](mailto:support@vodex.ai)
2. **Test authentication** with a simple API call
3. **Explore the [Call Trigger API](/api-reference/call-trigger/run-campaign)** to start making calls
4. **Review other endpoints** for complete integration
5. **Set up webhooks** for real-time notifications
**Ready to integrate?** The Vodex.ai API provides powerful programmatic access to AI-powered voice calling capabilities. Start with the Call Trigger API and expand your integration as needed.
***
## Support and Resources
### Getting Help
* **Email Support:** [support@vodex.ai](mailto:support@vodex.ai)
* **API Questions:** Include "API Support" in your subject line
* **Response Time:** Within 24 hours during business days
### Additional Resources
Start making AI-powered calls programmatically with the most popular endpoint.
Access campaign analytics and performance data via API.
Programmatically manage your contact lists and audience data.
Configure AI agents and conversation flows via API.
# ๐ฅ Audience Guide
Source: https://docs.vodex.ai/audience/guide
Learn how to add and manage your audience list for AI calling campaigns - complete step-by-step instructions
**What you'll learn:** How to add people to your calling list (audience) so your AI agents know who to call. This guide covers both manual entry and file upload methods.
## What Is an Audience?
Think of an **audience** as your **calling list** - the people you want your AI agents to call. Just like you need a phone book to make calls, your AI agents need an audience list to know who to contact.
## Why Do You Need an Audience?
* **Your AI agents need targets** - They can't call people if they don't know who to call
* **Organize your contacts** - Group people by different campaigns or purposes
* **Track your calling progress** - Know who has been called and who hasn't
* **Manage your calling strategy** - Focus on specific groups of people
## How to Add Your First Audience
### **Step 1: Start Adding an Audience**
1. Go to the **Audience section** in your dashboard
2. Click the **"+ Add New Audience"** button
3. You'll see a form where you can add audience details
### **Step 2: Give Your Audience a Name**
First, you need to identify your audience:
| Field | What to Enter | Example |
| ----------------- | ----------------------------- | ------------------------- |
| **Audience Name** | A name to identify this group | "Customer Follow-up List" |
**Important:** Choose a clear, descriptive name for your audience. This helps you organize different calling campaigns and find the right list later.
### **Step 3: Choose How to Add People**
You have **two options** for adding people to your audience:
#### **Option A: Upload a File (Recommended for Large Lists)**
If you have many people to add (like 50+ contacts):
1. **Click "Choose File"** button
2. **Select your Excel file** (.xlsx or .xls format)
3. **Upload the file** to the system
4. **Click "Save"** to create your audience
**File Requirements:** Only Excel files (.xlsx or .xls) are accepted. Make sure your file has columns for FirstName, LastName, and PhoneNum.
**๐ Need help with file formatting?** Check out our [Upload Sheet Format Guide](/audience/upload-sheet) to learn the critical formatting requirements that ensure successful uploads.
#### **Option B: Add People Manually (Good for Small Lists)**
If you have just a few people to add:
1. **Click "Create Manually"** button
2. **Fill in the person's details:**
* **First Name** - The person's first name
* **Last Name** - The person's last name
* **Phone Number** - Their contact number
3. **Click "Save"** to add this person
4. **To add more people manually:**
* Click **"+ Add"** button for each additional person
* Fill in their details
* Click **"Save"** when finished
## Visual Guide: Adding an Audience
Here's a simple flowchart showing the process:
```mermaid theme={null}
flowchart TD
A[Click + Add New Audience] --> B[Enter Audience Name]
B --> C{Choose Method}
C -->|Many People| D[Upload Excel File]
C -->|Few People| E[Create Manually]
D --> F[Click Choose File]
F --> G[Select .xlsx or .xls file]
G --> H[Upload File]
H --> I[Click Save]
E --> J[Click Create Manually]
J --> K[Fill First Name, Last Name, Phone]
K --> L[Click Save]
L --> M{Add More People?}
M -->|Yes| N[Click + Add]
M -->|No| O[Finished!]
N --> K
I --> P[Audience Created Successfully!]
O --> P
```
## File Upload Method (Step by Step)
### **Before You Start: Prepare Your Excel File**
**Critical:** File formatting is essential for successful uploads. Even small mistakes in column headers or data format will cause your upload to fail completely.
Make sure your Excel file has these columns:
| Column A | Column B | Column C |
| ------------- | ------------ | ------------ |
| **FirstName** | **LastName** | **PhoneNum** |
| John | Smith | 555-123-4567 |
| Jane | Doe | 555-987-6543 |
| Mike | Johnson | 555-456-7890 |
### **Upload Process:**
1. **Click "+ Add New Audience"**
2. **Enter your audience name** (e.g., "Customer List March 2024")
3. **Click "Choose File"**
4. **Find and select your Excel file**
5. **Click "Upload"**
6. **Click "Save"**
**Success!** Your audience is now created and ready to use with your AI calling campaigns.
**๐ Pro Tip:** For the most reliable uploads, follow our detailed [Upload Sheet Format Guide](/audience/upload-sheet) which covers exact column header requirements, date formatting, and common mistakes to avoid.
## Manual Entry Method (Step by Step)
### **Adding Your First Person:**
1. **Click "+ Add New Audience"**
2. **Enter your audience name** (e.g., "VIP Customers")
3. **Click "Create Manually"**
4. **Fill in the person's details:**
* **First Name:** John
* **Last Name:** Smith
* **Phone Number:** 555-123-4567
5. **Click "Save"**
### **Adding More People:**
1. **Click "+ Add"** button
2. **Fill in the next person's details:**
* **First Name:** Jane
* **Last Name:** Doe
* **Phone Number:** 555-987-6543
3. **Click "Save"**
4. **Repeat for each additional person**
5. **When finished, your audience is complete**
## Important Tips for Success
### **File Upload Tips:**
* **Use Excel format** - Only .xlsx and .xls files work
* **Check your columns** - Make sure First Name, Last Name, and Phone Number are in separate columns
* **Verify phone numbers** - Ensure they're in the correct format (e.g., 555-123-4567)
* **Remove empty rows** - Clean up your Excel file before uploading
**๐จ Most Important Tip:** Column headers must match your custom fields exactly. Check our [Upload Sheet Format Guide](/audience/upload-sheet) for the critical formatting requirements that prevent upload failures.
### **Manual Entry Tips:**
* **Double-check phone numbers** - One wrong digit means the call won't go through
* **Use consistent formatting** - Keep names and phone numbers in the same format
* **Save frequently** - Don't lose your work if something goes wrong
* **Review before finishing** - Make sure all information is correct
## Common Questions About Audiences
### **How Many People Can I Add?**
* **File upload:** Up to thousands of contacts
* **Manual entry:** Best for 50 or fewer contacts
* **No limit** on total audience size
### **Can I Edit My Audience Later?**
* **Yes!** You can edit audience details anytime
* **Add new people** to existing audiences
* **Remove people** who shouldn't be called
* **Update information** if details change
### **What Happens If I Upload the Wrong File?**
* **Don't worry!** You can always delete and recreate
* **Check the preview** before saving
* **Verify your data** matches what you expect
* **Test with a small file** first if you're unsure
### **Can I Use the Same Audience for Different Campaigns?**
* **Yes!** One audience can be used multiple times
* **Track results** for each campaign separately
* **Reuse successful audiences** for similar campaigns
* **Organize by purpose** (e.g., "New Customers" vs "Follow-up")
## Best Practices for Managing Audiences
### **1. Use Clear Naming**
* **Be specific:** "Q1 Sales Prospects" instead of "List 1"
* **Include dates:** "Customer Follow-up March 2024"
* **Add purpose:** "VIP Customer Retention"
### **2. Keep Data Clean**
* **Verify phone numbers** before adding
* **Remove duplicates** from your Excel files
* **Update outdated information** regularly
* **Format consistently** across all entries
### **3. Organize by Purpose**
* **Group similar contacts** together
* **Separate different campaigns** into different audiences
* **Use tags or categories** if your system supports them
* **Archive old audiences** when no longer needed
### **4. Test Before Going Live**
* **Start with small audiences** to test your setup
* **Verify AI agent performance** with a few test calls
* **Check call quality** and adjust as needed
* **Scale up gradually** once everything works perfectly
## What Happens After You Create an Audience?
Once your audience is created:
1. **It's saved in your system** and ready to use
2. **You can assign it to AI agents** for calling campaigns
3. **Track calling progress** and results
4. **Edit or update** the audience anytime
5. **Use it for multiple campaigns** if needed
## Next Steps
Now that you understand how to create audiences:
1. **Go to the Audience section** and click "+ Add New Audience"
2. **Choose your method** (file upload or manual entry)
3. **Create your first audience** with a clear, descriptive name
4. **Add your contacts** using your preferred method
5. **Save and start using** your audience with AI calling campaigns
**๐ Ready to upload a file?** Before you start, make sure to review our [Upload Sheet Format Guide](/audience/upload-sheet) to avoid common formatting mistakes that cause upload failures.
**Ready to build your calling list?** Follow these steps to create professional, organized audiences that will help your AI agents reach the right people at the right time.
***
**๐ Need help with file formatting?** Check out our [Upload Sheet Format Guide](/audience/upload-sheet) to learn the critical requirements for successful audience uploads.
**Need help with AI agents?** Check out our [Agents Overview](/agents/overview) to learn how to create the AI callers that will use your audience lists.
**Want to learn about custom fields?** Visit our [Custom Fields Guide](/custom-fields/introduction) to understand how to personalize your calls with specific information about each contact.
# ๐ Upload Sheet Format Guide
Source: https://docs.vodex.ai/audience/upload-sheet
Learn the critical formatting requirements for uploading audience sheets - avoid upload failures with proper column headers and data formatting
**Critical Information:** The format of your upload sheet is the most important factor for successful audience uploads. Even small mistakes will cause your upload to fail completely.
## Why File Format Matters So Much
Think of your upload sheet like a **key that must fit perfectly** into a lock. If the key is even slightly wrong - wrong shape, wrong size, wrong teeth - the lock won't open. The same is true for your audience upload sheet.
**Small formatting mistakes = Complete upload failure**
## Important: File Size Limits
### **Maximum Capacity: 20,000 Customers Per File**
Your upload sheet can contain a **maximum of 20,000 customers** in a single file. This is a system limitation to ensure optimal performance and reliable campaign execution.
### **What Happens If You Have More Than 20k Customers?**
If your audience list contains more than 20,000 contacts, you'll need to:
1. **Split your data into multiple files** - Each file with maximum 20k customers
2. **Upload each file as a separate audience list** - Create multiple audience lists
3. **Run campaigns on each audience list** - Manage them separately or combine them
### **Example: 35,000 Customer Scenario**
| File Number | Customer Range | File Size | Action |
| ----------- | ----------------------- | --------- | --------------------------- |
| **File 1** | Customers 1-20,000 | 20,000 | Upload as "Audience List A" |
| **File 2** | Customers 20,001-35,000 | 15,000 | Upload as "Audience List B" |
**Result:** You'll have 2 audience lists that you can use for separate campaigns or combine for larger reach.
## The Golden Rule: Column Headers Must Match Custom Fields Exactly
### **What This Means:**
If your custom field is `{duedate}`, your column header must be exactly `duedate` - not `due date`, not `DueDate`, not `duedate ` (with extra spaces).
### **Why This Happens:**
The system looks for **exact matches** between your custom field names and your column headers. It's like a computer looking for a file named "report.txt" - it won't find "Report.txt" or "report .txt".
## Required Columns (Always Present)
These columns **must** be in your sheet for any upload to work:
| Column Header | Must Be Exactly | What It Contains | Example |
| ------------- | --------------- | -------------------- | ----------- |
| `FirstName` | `FirstName` | Person's first name | John |
| `LastName` | `LastName` | Person's last name | Smith |
| `PhoneNum` | `PhoneNum` | Contact phone number | 12185262990 |
**Important:** These three columns are the foundation of every audience upload. Without them, your upload will fail immediately.
## Custom Field Columns (Based on Your Prompt)
### **How to Know What to Include:**
1. **Look at your AI agent's prompt** - Find all the custom fields in curly braces like `{FirstName}`, `{AmountDue}`, `{DueDate}`
2. **Add a column for each custom field** - The column header must match exactly
3. **Remove the curly braces** - `{DueDate}` becomes `DueDate` in your sheet
### **Example Custom Field Mapping:**
| Custom Field in Prompt | Column Header in Sheet | What to Enter |
| ---------------------- | ---------------------- | ------------- |
| `{FirstName}` | `FirstName` | John |
| `{AmountDue}` | `AmountDue` | \$500.00 |
| `{DueDate}` | `DueDate` | 2024-03-30 |
| `{AccountNumber}` | `AccountNumber` | ACC12345 |
## Common Formatting Mistakes That Cause Failures
### **โ WRONG - These Will Fail:**
| What You Have | What It Should Be | Why It Fails |
| ------------- | ----------------- | ------------------------- |
| `First Name` | `FirstName` | Spaces are not allowed |
| `firstname` | `firstname` | Wrong capitalization |
| `FirstName ` | `FirstName` | Extra spaces at the end |
| `first_name` | `firstname` | Underscores are different |
| `Due Date` | `DueDate` | Spaces break the match |
| `duedate` | `DueDate` | Wrong capitalization |
### **โ
CORRECT - These Will Work:**
| Column Header | Status | Why It Works |
| --------------- | --------- | --------------------------------- |
| `FirstName` | โ
Correct | Matches `{FirstName}` exactly |
| `AmountDue` | โ
Correct | Matches `{AmountDue}` exactly |
| `DueDate` | โ
Correct | Matches `{DueDate}` exactly |
| `AccountNumber` | โ
Correct | Matches `{AccountNumber}` exactly |
## Phone Number Formatting (Critical!)
### **Why Phone Number Formatting is So Important:**
Phone numbers must include the **country code without the + sign** and have **no dashes, spaces, or special characters**. The system needs the complete international format to ensure successful SMS delivery.
### **โ
Correct Phone Number Formats:**
**Required Format:** Country code + phone number (no + sign, no dashes, no spaces)
| Country | Example Format | What to Enter |
| ------------- | ----------------- | -------------- |
| **US/Canada** | +1 (218) 526-2990 | `12185262990` |
| **India** | +91 99639 05554 | `919963905554` |
| **UK** | +44 20 7946 0958 | `442079460958` |
| **Australia** | +61 2 9374 4000 | `61293744000` |
### **โ Wrong Phone Number Formats:**
| What You Have | Why It Fails |
| ---------------- | ----------------------------------------------- |
| `+12185262990` | Contains + sign |
| `218-526-2990` | Missing country code and has dashes |
| `1 218 526 2990` | Contains spaces |
| `(218) 526-2990` | Missing country code and has special characters |
**Important:** Always include the country code and remove all formatting characters (+, -, spaces, parentheses) from phone numbers.
## Date Column Formatting (Critical!)
### **Why Date Formatting is So Important:**
Date columns are **extra sensitive** to formatting errors. The system needs to understand exactly what date you're providing.
### **โ
Correct Date Formats:**
**Allowed**
* `March 25, 2025` (Recommended)
* `25-03-2025` in `DD-MM-YYYY` format
* `03-05-2025` in `DD-MM-YYYY` format
**Not allowed**
* Just writing `10-03-2025` - it is confusing if it is `MM-DD` or `DD-MM`
## Complete Example Sheet
Here's what a properly formatted upload sheet should look like:
| FirstName | LastName | PhoneNum | AmountDue | DueDate | AccountNumber |
| --------- | -------- | ------------ | --------- | ---------- | ------------- |
| John | Smith | 12185262990 | \$500.00 | 2024-03-30 | ACC12345 |
| Jane | Doe | 919963905554 | \$750.00 | 2024-04-15 | ACC12346 |
| Mike | Johnson | 14155552368 | \$300.00 | 2024-03-25 | ACC12347 |
### **Key Points About This Example:**
1. **Required columns** are : `FirstName`, `LastName`, `PhoneNum`
2. **Custom field columns** match prompt customfields: `FirstName`, `AmountDue`, `DueDate`, `AccountNumber`
3. **Dates are in stringify date format**: `March 25, 2025`
4. **No extra spaces** anywhere in column headers
5. **Consistent formatting** throughout
## Step-by-Step Upload Sheet Preparation
### **Step 1: Download the Sample Excel Template**
1. **Select your desired AI agent** in the platform
2. **Navigate to the Audience tab**
3. **Click "Add New Audience"** to open the dialog box
4. **Click the "Download Sample Excel File" button**
5. **Save the sample file** to your computer
**Perfect Template:** This sample file contains all the exact column headers you need - both system fields (FirstName, LastName, PhoneNum) and all custom fields specific to your selected agent.
### **Step 2: Use the Sample File as Your Template**
1. **Open the downloaded sample Excel file**
2. **Review all column headers** - These are exactly what you need
3. **Keep the file structure intact** - Don't modify any column headers
4. **Save a copy** as your working template for future uploads
### **Step 3: Format Your Data**
1. **Names:** Use proper capitalization (John, not john)
2. **Phone numbers:** Use country code + phone number format (12185262990, 919963905554)
3. **Dates:** Use stringify date format (`March 25, 2025`)
4. **Numbers:** Use consistent decimal places ($500.00, not $500)
### **Step 4: Check for Common Errors**
1. **Don't modify column headers** - Use exactly what's in the sample file
2. **No extra spaces** - Don't add spaces to any headers or data
3. **Consistent formatting** - Keep the same format throughout all rows
4. **Proper date format** - Use stringify date format (`March 25, 2025`)
## Testing Your Sheet Before Upload
### **Before You Upload:**
1. **Double-check column headers** - Compare with your custom fields exactly
2. **Verify date formats** - All dates should be stringify date format `March 25, 2025`
3. **Check for extra spaces** - Look at the beginning and end of each header
4. **Test with a small file** - Upload 2-3 contacts first to verify
## Best Practices for Reliable Uploads
### **1. Use Excel Templates**
* **Create a template** with correct column headers
* **Save it as .xlsx** format
* **Reuse the template** for future uploads
* **Never copy-paste** column headers (can add hidden characters)
### **2. Validate Your Data**
* **Check phone numbers** - Make sure they include country code without + sign (e.g., 12185262990, 919963905554)
* **Verify dates** - Ensure they're in the future if needed
* **Review names** - Check for obvious typos
* **Test calculations** - If using formulas, verify results
### **3. Keep It Simple**
* **Start with basic fields** - Add complexity gradually
* **Use consistent formats** - Same style throughout
* **Avoid special characters** - Stick to letters, numbers, and basic punctuation
* **Test small batches** - Verify before uploading large lists
### **4. Respect File Size Limits**
* **Maximum 20,000 customers per file** - Don't exceed this limit
* **Split large lists** - Break them into multiple files if needed
* **Plan your uploads** - Consider how many audience lists you'll need
* **Monitor file sizes** - Check customer count before uploading
## Troubleshooting Upload Failures
### **If Your Upload Fails:**
1. **Check the error message** - It usually tells you what's wrong
2. **Verify column headers** - Compare with custom fields exactly
3. **Check date formats** - Convert all dates to stringify date format
4. **Look for extra spaces** - Remove any trailing or leading spaces
5. **Verify file format** - Make sure it's .xlsx or .xls
### **Common Fixes:**
| Problem | Solution |
| ------------------------ | ---------------------------------------------------- |
| Column header has spaces | Remove spaces: `First Name` โ `FirstName` |
| Wrong capitalization | Fix case: `firstname` โ `FirstName` |
| Extra spaces | Trim whitespace: `FirstName ` โ `FirstName` |
| Wrong date format | Convert to stringify date format : `March 25, 2025` |
| Missing required column | Add the missing column with correct spelling |
## Next Steps
Now that you understand proper sheet formatting:
1. **Review your AI agent's prompt** - Identify all custom fields
2. **Check your audience size** - Ensure you're within the 20,000 customer limit
3. **Create a properly formatted sheet** - Use correct column headers
4. **Format your data correctly** - Especially dates and phone numbers
5. **Test with a small upload** - Verify everything works
6. **Upload your complete audience** - Enjoy successful, error-free uploads
**Remember:** If you have more than 20,000 customers, split them into multiple files before uploading. Each file should contain a maximum of 20,000 contacts.
**Ready to create perfect upload sheets?** Remember: exact column headers + proper date formatting = successful uploads every time!
***
**Need help with audiences?** Check out our [Audience Guide](/audience/guide) to learn the complete process of creating and managing your contact lists.
**Want to learn about custom fields?** Visit our [Custom Fields Guide](/custom-fields/introduction) to understand how to use dynamic placeholders in your prompts.
# ๐ง Advanced Settings
Source: https://docs.vodex.ai/call-settings/advanced-settings
Configure advanced call settings including language codes, ASR providers, webhooks, transfer options, and system parameters
# Advanced Settings
**What you'll learn:** Advanced configuration options for language processing, speech recognition, post-call webhooks, transfer settings, and system parameters to optimize your AI calling campaigns.
## Language Configuration
### Language Selection
Choose the language for your AI conversations from the available options to ensure optimal speech recognition and response generation.
**Critical:** Incorrect language and ASR combinations will cause call triggering to fail with the error: "Please choose proper language code"
#### **Available Languages**
Select from these supported languages in your campaign settings:
| Language | Variants Available | Best ASR Match | Use Cases |
| ----------- | ------------------------ | ---------------------- | --------------------------------- |
| **English** | US, UK, India, Australia | Alpha Echo, Google ASR | Global business, customer service |
| **Hindi** | India | Alpha Echo, Nova Echo | Indian market campaigns |
| **German** | Standard | All ASR providers | German-speaking markets |
| **Spanish** | Standard | All ASR providers | Spanish-speaking regions |
| **Italian** | Standard | All ASR providers | Italian market campaigns |
#### **Language Selection Guidelines**
**Choose the Right English Variant:**
* **English (US)** - American pronunciation, terminology
* **English (UK)** - British pronunciation, terminology
* **English (India)** - Indian accent optimization
* **English (Australia)** - Australian accent optimization
**Best for:** Matching your target audience's accent and terminology preferences
**Specialized Language Support:**
* **Hindi** - Optimized for Indian market campaigns
* **German** - European German standard
* **Spanish** - International Spanish
* **Italian** - Standard Italian
**Best for:** Native language campaigns in specific regions
**Selection Tip:** Choose the language variant that best matches your target audience's location and accent for optimal recognition accuracy.
***
## ASR (Automatic Speech Recognition) Providers
Choose the speech recognition system that best fits your language and accuracy requirements.
### Available ASR Options
**Vodex Custom Trained Deepgram Model**
**Features:**
* Custom trained on conversation data
* Supports all Deepgram languages
* Enhanced accuracy for calling scenarios
* Optimized for real-time processing
**Advantages:**
* **Better accuracy** than standard models
* **Conversation-optimized** training
* **Low latency** for real-time calls
* **Multi-language support**
**Best for:** Most calling scenarios, customer service, sales calls
**Google Cloud Speech-to-Text**
**Features:**
* Enterprise-grade reliability
* Extensive language support
* Real-time streaming recognition
* Automatic punctuation and formatting
**Advantages:**
* **High accuracy** across languages
* **Robust performance** in noisy environments
* **Global language coverage**
* **Enterprise reliability**
**Best for:** Multi-language campaigns, enterprise applications
**OpenAI Whisper ASR**
**Features:**
* State-of-the-art accuracy
* Multilingual capabilities
* Robust to accents and noise
* Open-source foundation
**Advantages:**
* **Exceptional accuracy**
* **Accent tolerance**
* **Noise resistance**
* **Multilingual support**
**Best for:** High-accuracy requirements, diverse accents, challenging audio
**ElevenLabs Speech Recognition**
**Features:**
* Optimized for voice synthesis integration
* High-quality transcription
* Real-time processing
* Voice-optimized accuracy
**Advantages:**
* **Voice integration** with ElevenLabs TTS
* **Optimized pipeline** for voice applications
* **High quality** transcription
**Best for:** ElevenLabs voice integration, voice-focused applications
**Microsoft Azure Speech Services**
**Features:**
* Enterprise-grade security
* Global deployment options
* Custom model training
* Integration with Microsoft ecosystem
**Advantages:**
* **Enterprise security**
* **Custom models** available
* **Global infrastructure**
* **Microsoft integration**
**Best for:** Enterprise deployments, Microsoft ecosystem integration
**Vodex Fine-tuned Whisper**
**Features:**
* On-premises deployable
* Fine-tuned for specific use cases
* Enhanced privacy and security
* Custom optimization available
**Advantages:**
* **On-premises deployment**
* **Enhanced privacy**
* **Custom fine-tuning**
* **Specialized optimization**
**Best for:** Privacy-sensitive applications, on-premises requirements
**Arabic-Specialized Model**
**Features:**
* Fine-tuned specifically for Arabic
* Optimized for Gulf countries
* Regional dialect support
* Cultural context awareness
**Advantages:**
* **Arabic specialization**
* **Gulf region optimization**
* **Dialect recognition**
* **Cultural accuracy**
**Best for:** Arabic-speaking markets, Gulf countries, regional campaigns
***
## System Parameters
### Temperature Setting
Control the creativity and randomness of AI responses.
| Temperature | Behavior | Best For | Example Use Cases |
| ------------- | ---------------------------- | --------------------------- | ---------------------------------------- |
| **0.0 - 0.3** | Very consistent, predictable | Formal business, compliance | Legal notices, appointment confirmations |
| **0.4 - 0.6** | Balanced, professional | Customer service, support | Help desk, technical support |
| **0.7 - 0.9** | Creative, conversational | Sales, engagement | Sales calls, relationship building |
| **1.0+** | Highly creative, varied | Creative applications | Marketing, entertainment |
**Recommended Setting:** Use 0.5-0.7 for most business applications to balance consistency with natural conversation flow.
***
## Transfer Configuration
### Transfer Gateway
Specify which gateway to use when transferring calls to human agents or other numbers.
**Standard Transfer Routing**
* Uses your primary configured gateway
* Consistent with inbound call routing
* Simplified configuration
* Standard reliability and quality
**Specialized Transfer Routing**
* Dedicated gateway for transfers
* Optimized for specific transfer scenarios
* Enhanced routing options
* Custom quality parameters
**Multiple Gateway Support**
* Distribute transfers across gateways
* Improved reliability and capacity
* Geographic routing optimization
* Failover capabilities
### Transfer Call ID Options
Configure the caller ID displayed when transferring calls:
| Option | Caller ID Displayed | Use Case |
| --------------------- | ---------------------------- | -------------------------------- |
| **default** | Your outbound caller ID | Standard business transfers |
| **lead** | The original caller's number | Warm transfers, continuity |
| **Any Number or DID** | Specified phone number | Specialized routing, departments |
***
## Transfer Types
Choose the appropriate transfer method based on your technical requirements and cost considerations.
```mermaid theme={null}
graph TD
A[Incoming Call] --> B{Transfer Needed?}
B -->|No| C[Continue AI Conversation]
B -->|Yes| D{Transfer Type}
D --> E[Transfer Call]
D --> F[Bridge Call]
E --> G[SIP REFER to Gateway]
E --> H[Bot Disconnects]
E --> I[Charged Until Transfer]
F --> J[Conference Lead + Transfer]
F --> K[Bot Goes Silent]
F --> L[Full Lead Call + 7ยข/min Transfer]
G --> M[Gateway Handles Transfer]
J --> N[Both Parties Connected]
style E fill:#e1f5fe
style F fill:#fff3e0
style I fill:#c8e6c9
style L fill:#ffcdd2
```
### Transfer Call (Recommended)
**How it works:**
* Sends a SIP REFER command to the gateway/trunk
* Bot disconnects after successful transfer
* Gateway handles the actual call connection
**Billing:**
* Charged only until the transfer completes
* No additional charges for transferred portion
* Most cost-effective option
**Requirements:**
* Gateway/trunk must support SIP REFER
* Proper SIP configuration required
**Advantages:**
* โ
**Cost-effective** - No charges after transfer
* โ
**Clean handoff** - Bot completely disconnects
* โ
**Gateway managed** - Reliable transfer handling
* โ
**Scalable** - Minimal resource usage
**Best for:** Standard business transfers, cost-conscious deployments
### Bridge Call
**How it works:**
* Creates a conference between lead and transfer destination
* Bot remains connected but goes silent
* All parties on the same call
**Billing:**
* Full charges for the original lead call
* Additional 7ยข/minute for the transferred call
* Charges continue for entire call duration
**Requirements:**
* No special gateway requirements
* Works with any SIP provider
**Advantages:**
* โ
**Universal compatibility** - Works with any gateway
* โ
**Reliable connection** - No dependency on SIP REFER
* โ
**Monitoring capability** - Bot can monitor the transfer
* โ
**Fallback option** - When SIP REFER isn't supported
**Best for:** Gateways without SIP REFER support, monitoring requirements
### Choosing the Right Transfer Type
**Recommended Scenarios:**
* Your gateway supports SIP REFER
* Cost optimization is important
* Clean call handoffs are required
* High-volume transfer scenarios
* Standard business operations
**Necessary Scenarios:**
* Gateway doesn't support SIP REFER
* Need to monitor transferred calls
* Require guaranteed connectivity
* Complex transfer scenarios
* Fallback option needed
***
## Call Transfer Webhook
Configure real-time conversation data delivery when calls are transferred to human agents, enabling seamless handoffs with full context.
### Transfer Webhook Configuration
Provide your webhook URL to receive conversation history and call data immediately when a call is transferred to a human agent.
**Enterprise Feature:** Call Transfer Webhook enables human agents to receive complete conversation context, improving transfer quality and customer experience.
```text Transfer Webhook URL Setup theme={null}
https://your-domain.com/api/call-transfer
```
```json Example Transfer Webhook Payload theme={null}
{
"conversation": [
{
"role": "assistant",
"content": "Hello, thank you for calling Vodex. I'm Sarah, how can I help you today?",
"type": "response"
},
{
"role": "user",
"content": "Hi, I need help with my account billing issue",
"type": "input"
},
{
"role": "assistant",
"content": "I understand you have a billing concern. Let me transfer you to our billing specialist who can better assist you.",
"type": "response"
}
],
"call_uuid": "68adc5c4-2709-40e4-9f10-ea01d0731d",
"tenent_id": "Vodex",
"phone_number": "+1234567890",
"user_data": {
"firstName": "John",
"lastName": "Smith",
"accountId": "ACC-12345",
"customerTier": "Premium"
}
}
```
**Conversation Format:** The conversation array supports multiple formats depending on the AI model used:
* Standard: `{"role": "user|assistant", "content": "message", "type": "input|response"}`
* Alternative: `{"author": "agent_name", "content": "message"}`
**Important:** The conversation array may have inconsistent keys across different objects, as various AI models generate different data structures. Always validate object keys before processing.
### Transfer Webhook Data Fields
**Real-time Context:**
* `conversation` - Complete conversation transcript up to transfer point
* `role` - Speaker identification (user/assistant)
* `content` - Message content
* `type` - Message type (input/response)
**Transfer Context:**
* `call_uuid` - Unique call identifier
* `tenent_id` - Organization identifier
* `phone_number` - Customer phone number
* `user_data` - Custom customer data and context
### Transfer Webhook Benefits
**Informed Handoffs:**
* Complete conversation history
* Customer context and data
* Issue identification
* Previous interaction summary
**Result:** Agents start transfers with full context, eliminating customer frustration from repeating information.
**Seamless Transitions:**
* No information loss during transfer
* Faster resolution times
* Reduced customer effort
* Professional service continuity
**Result:** Higher customer satisfaction and more efficient agent workflows.
***
## Post-Call Insights Webhook
Configure automated post-call data delivery to your systems for analysis and integration.
### Webhook Configuration
Simply provide your webhook URL to receive detailed call information immediately after each call completes.
**Simple Setup:** Just enter your webhook URL - no authentication configuration needed. The webhook will receive unauthenticated POST requests with call data.
```text Webhook URL Setup theme={null}
https://your-domain.com/api/call-insights
```
```json Example Webhook Payload theme={null}
{
"dbUrl": "Vodex_",
"projectId": "68ad89e46ba60ab120b9aaed",
"campaignRunId": "68ad8e79a5f47ab2fd36cca0",
"call_uuid": "68adc5c4-2709-40e4-9f10-ea01d0731d",
"callRecordingUrl": "https://storage.googleapis.com/botstream-recordings/68adc5c4-2709-40e4-9f10-ea01d0731d.mp3",
"summary": "Sandeep called ANS Hospital to book an appointment for physiotherapy. The agent, Rana, helped him book an appointment with Mr. AA for tomorrow at 10:00 AM. Sandeep confirmed the details and said he had no further questions.",
"questions": [
{"key": "department", "value": "physiotherapy"},
{"key": "appointment_time", "value": "2025-08-27t10:00:00"},
{"key": "appointment", "value": true},
{"key": "doctor", "value": "AA"}
],
"mobileNo": "120523644",
"callStatus": "Ended",
"contactId": null,
"email": "email@string.com",
"transcript": [
{
"type": "input",
"value": " hi",
"created_date": "26-08-2025 16:09:36"
},
{
"type": "response",
"value": " \"Hello, thank you for calling Kims Hospital. I'm rana, how can I help you today?\"",
"created_date": "26-08-2025 16:09:36"
}
],
"mandatory_params": {
"FirstName": "Name",
"LastName": "Name",
"PhoneNum": "120523644",
"firstName": "Name",
"lastName": "Name",
"phone": "1205236446,
"time_zone": "+05:30",
"today": ""
},
"duration": 106.5584888458252
}
```
**Questions Field:** The `questions` array content will vary for each client as the data is pulled from your custom Insights configuration. However, the structure always remains the same: an array of objects with `key` and `value` properties.
### Webhook Data Fields
**Unique Identifiers:**
* `call_uuid` - Unique call identifier
* `projectId` - Your project identifier
* `campaignRunId` - Campaign run identifier
* `dbUrl` - Database reference
**Conversation Data:**
* `summary` - AI-generated call summary
* `transcript` - Complete conversation transcript
* `questions` - Extracted key-value pairs
* `callRecordingUrl` - Audio recording URL
**Participant Details:**
* `mobileNo` - Contact phone number
* `email` - Contact email address
* `contactId` - Internal contact identifier
* `mandatory_params` - Custom field values
**Performance Data:**
* `duration` - Call length in seconds
* `callStatus` - Final call status
* `created_date` - Timestamp for each interaction
### Webhook Best Practices
**Secure Your Webhook**
* Use HTTPS endpoints only
* Validate incoming requests
* Rate limit webhook calls
* Consider IP whitelisting if needed
**Handle Webhook Data**
* Respond with HTTP 200 for successful processing
* Implement retry logic for failures
* Store data before processing
* Handle duplicate deliveries gracefully
**Integrate with Your Systems**
* Parse JSON payload correctly
* Map fields to your database schema
* Trigger automated workflows
* Generate reports and analytics
***
## Configuration Best Practices
### Language and ASR Optimization
**Performance Tip:** Always test language code and ASR combinations in a development environment before deploying to production campaigns.
| Scenario | Recommended ASR | Language Code | Notes |
| --------------------- | --------------- | ------------- | --------------------------- |
| **English Business** | Alpha Echo | `en-US` | Best overall performance |
| **Multi-language** | Google ASR | Various | Broad language support |
| **High Accuracy** | OpenAI Whisper | Any supported | Maximum accuracy |
| **Arabic Markets** | Nova Echo | `ar-SA` | Specialized for Gulf region |
| **Privacy-sensitive** | Genesis Echo | Any supported | On-premises option |
### Transfer Configuration Guidelines
**Important:** Always verify that your gateway supports SIP REFER before configuring Transfer Call mode. Use Bridge Call as a fallback option.
### Webhook Integration Tips
**Test Your Integration:**
* Use webhook testing tools (ngrok, RequestBin)
* Validate JSON parsing for both webhook types
* Test error handling and retry logic
* Verify data mapping and conversation parsing
* Test transfer webhook timing and delivery
**Production Readiness:**
* Implement proper logging for all webhook events
* Set up monitoring and alerts for transfer webhooks
* Configure backup endpoints for critical transfers
* Document data flows and agent integration processes
* Ensure real-time processing for transfer webhooks
**Agent Integration:**
* Display conversation history in agent interface
* Parse user\_data for customer context
* Implement real-time webhook processing
* Configure agent notification systems
* Test transfer scenarios thoroughly
***
## Next Steps
After configuring advanced settings:
1. **Test language and ASR combinations** in development
2. **Configure transfer settings** based on your gateway capabilities
3. **Set up webhook endpoints** for both post-call insights and transfer notifications
4. **Configure agent systems** to receive and display transfer webhook data
5. **Test transfer scenarios** with conversation context delivery
6. **Monitor performance** and adjust settings as needed
7. **Document your configuration** for team reference
**Advanced Configuration Complete?** These settings provide fine-grained control over your AI calling campaigns. Proper configuration ensures optimal performance, cost efficiency, and seamless integration with your existing systems.
***
**Need basic configuration help?** Check out our [Call Settings Overview](/call-settings/overview) for fundamental setup guidance and voice configuration options.
# โ๏ธ Call Settings Overview
Source: https://docs.vodex.ai/call-settings/overview
Configure your AI calling campaigns with advanced call settings, AI models, voice options, and transfer capabilities
# Call Settings Overview
**What you'll learn:** How to configure call settings including transfer numbers, AI models, voice options, caller ID, and call management features for optimal campaign performance.
## Core Call Settings
### Call Transfer Number
The phone number or SIP URI that your AI bot will transfer calls to when needed.
**Standard Phone Number Format**
Enter the phone number without the `+` prefix:
```
12185262990
```
The system will automatically format the number with the appropriate country code during call processing.
**SIP URI Format**
For SIP-based transfers, use the standard SIP URI format:
```
sip:username@domain.com
sip:12185262990@sip.provider.com
```
SIP URIs must start with `sip:` to be recognized by the system.
**Custom Trunk and DID**
For advanced setups with custom trunks and Direct Inward Dialing (DID):
* **Open field configuration** allows flexible routing
* **Custom trunk integration** for enterprise solutions
* **DID mapping** for specific number routing
Contact [support@vodex.ai](mailto:support@vodex.ai) for custom trunk configuration assistance.
***
### Disconnect Call Automatically
Automatically disconnect calls after a specified duration to prevent misuse and control costs.
#### **Why Use Auto-Disconnect?**
**Protection Against Misuse**
* Stops people from playing with your bot indefinitely
* Prevents unnecessary resource consumption
* Maintains professional call handling
**Cost Management**
* Limits maximum call duration charges
* Prevents runaway costs from stuck calls
* Ensures predictable billing
**Resource Optimization**
* Frees up system resources for legitimate calls
* Maintains optimal performance
* Reduces server load
#### **Configuration Options**
| Duration | Use Case | Recommended For |
| ----------------- | ---------------------------- | ---------------------- |
| **2-3 minutes** | Quick surveys, confirmations | Simple interactions |
| **5-7 minutes** | Customer service, support | Standard conversations |
| **10-15 minutes** | Sales calls, consultations | Complex discussions |
| **Custom** | Specialized use cases | Enterprise needs |
***
### Gateway Configuration
The communication gateway through which your calls are routed and processed.
#### **Default Gateway Options**
**Included with all plans:**
* Vodex default gateway (Only for testing)
* Standard SIP routing
* Basic call management
* Standard quality assurance
#### **Custom SIP Integration**
**Available for paid tiers:**
* Custom SIP provider integration
* Enterprise-grade routing
* Advanced call management
* Dedicated support
**To integrate:** Contact [support@vodex.ai](mailto:support@vodex.ai)
**Need SIP Trunk Integration?** Check our comprehensive [SIP Trunk Requirements Guide](/faqs/sip-trunk-requirements) for detailed technical requirements, configuration examples, and integration steps.
***
## AI Model Selection
Choose the AI model that best fits your use case and performance requirements.
### Out-of-the-Box Models
Professional AI models ready for immediate use:
**Anthropic Claude Series**
| Model | Best For | Characteristics |
| ----------------- | ----------------------------- | -------------------------------- |
| **Claude Haiku** | Quick responses, simple tasks | Fast, efficient, cost-effective |
| **Claude Sonnet** | Balanced conversations | Good reasoning, natural dialogue |
**Ideal for:**
* Customer service interactions
* Appointment scheduling
* Information gathering
* Professional conversations
**OpenAI GPT Series**
| Model | Best For | Characteristics |
| ----------------- | ------------------------- | ------------------------------------------ |
| **GPT-3.5 Turbo** | General conversations | Fast, reliable, cost-effective |
| **GPT-4** | Complex reasoning | Advanced understanding, detailed responses |
| **GPT-4 Turbo** | Long conversations | Extended context, efficient processing |
| **GPT-4o** | Multimodal interactions | Vision, audio, text capabilities |
| **GPT-4o Mini** | Lightweight multimodal | Fast multimodal processing, cost-effective |
| **GPT-5** | Next-generation AI | Advanced reasoning, enhanced capabilities |
| **GPT-5 Mini** | Efficient next-gen | Optimized performance, faster responses |
| **GPT-5 Chat** | Conversational excellence | Specialized for dialogue, natural flow |
**Ideal for:**
* Sales conversations
* Technical support
* Detailed consultations
* Multi-step processes
* Multimodal applications
* Next-generation AI experiences
**Meta Llama Series**
| Model | Best For | Characteristics |
| -------------- | ----------------------- | ------------------------------------ |
| **Llama 2** | Open-source flexibility | Customizable, privacy-focused |
| **Llama 3** | Enhanced performance | Improved reasoning, better responses |
| **Code Llama** | Technical discussions | Programming, technical support |
**Ideal for:**
* Technical conversations
* Privacy-sensitive applications
* Custom implementations
* Specialized domains
### Vodex Optimized Models
Specially tuned models optimized for calling scenarios:
**Vodex Spark Models**
Based on Vodex's custom architecture, optimized for voice conversations:
| Model | Optimization |
| -------------------- | --------------------------------------------- |
| **Spark** | Balanced performance for professional calls |
| **Spark Flash** | Ultra-fast responses, real-time conversations |
| **Spark Flash Lite** | Lightweight, cost-effective interactions |
**Spark Foundation**
* **Advanced reasoning** for complex conversations
* **Multimodal capabilities** for rich interactions
* **Large context window** for detailed discussions
* **High accuracy** in understanding and responses
**Spark Flash Foundation**
* **Ultra-low latency** for real-time conversations
* **Efficient processing** for high-volume campaigns
* **Optimized for speed** without sacrificing quality
* **Cost-effective** for large-scale operations
**Spark Flash Lite Foundation**
* **Minimal resource usage** for simple interactions
* **Maximum cost efficiency** for basic conversations
* **Quick deployment** for straightforward use cases
* **Reliable performance** for standard scenarios
**Model Selection Guide:** Choose Spark for complex sales calls, Spark Flash for customer service, and Spark Flash Lite for simple confirmations or surveys.
***
## Voice Configuration
Select from premium voice providers to create the perfect audio experience for your calls.
### Available Voice Providers
**Premium AI Voices**
**Features:**
* Ultra-realistic voice synthesis
* Multiple voice personalities
* Emotional expression capabilities
* Multiple languages and accents
**Model Recommendations:**
* **For English:** Select ElevenLabs Turbo v2 or ElevenLabs Flash V2
* **For Multi-lingual:** Use ElevenLabs Flash 2.5 or Turbo 2.5 to get proper accent
**Availability:** โ
**Included with all plans**
**Best for:**
* Professional business calls
* Customer service interactions
* Sales conversations
* Any scenario requiring natural-sounding voices
**Advanced Voice Technology**
**Features:**
* High-quality voice synthesis
* Natural conversation flow
* Specialized voice models
* Custom voice training options
**Availability:** ๐ **Contact support for access**
**Best for:**
* Specialized industry applications
* Custom voice requirements
* Enterprise implementations
**Microsoft Azure Voices**
**Features:**
* Enterprise-grade reliability
* Global language support
* Neural voice technology
* SSML support for fine control
**Availability:** ๐ **Contact support for access**
**Best for:**
* Enterprise applications
* Multi-language campaigns
* Integration with Microsoft ecosystem
**Google Cloud Text-to-Speech**
**Features:**
* WaveNet technology
* Ultra-realistic voices
* Multiple languages and variants
* Custom voice models
**Availability:** ๐ **Contact support for access**
**Best for:**
* High-quality voice requirements
* Global campaigns
* Google Cloud integrations
**Voice Provider Access:** While ElevenLabs is available by default, access to RimeLabs, Azure, and Google voices requires contacting [support@vodex.ai](mailto:support@vodex.ai) for configuration.
***
## Voicemail Detection
Advanced voicemail detection system to optimize call handling and costs.
### How It Works
**Voice Activity Detection Technology**
* Non-LLM based detection system
* Works across all countries and languages
* Independent of ASR, LLM, and voice settings
* **85% accuracy rate** in standard conditions
**Optimized Detection Timing**
* Bot starts speaking after **10 seconds** of voicemail detection
* Allows for various voicemail greeting lengths
* Reduces false positives from long greetings
**Enhanced Accuracy with Beep Recognition**
* Detects voicemail beep signals
* Restarts message delivery after beep detection
* Ensures **90% voicemail drop success rate**
* Maximizes message delivery effectiveness
### Cost Structure
| Scenario | Charge | Explanation |
| ------------------------------------- | ----------------- | --------------------------------- |
| **Voicemail Detected + Disconnected** | **3 cents** | Call ends without leaving message |
| **Voicemail Detected + Message Left** | **3 cents** | Successful voicemail delivery |
| **Live Person Answered** | **Standard rate** | Normal conversation charges apply |
**Cost Optimization:** The 3-cent voicemail charge is significantly lower than full conversation rates, helping you manage costs while maintaining campaign effectiveness.
***
## Caller ID Configuration
### Twilio Caller ID Management
**Twilio Exclusive Feature:** Caller ID configuration is only available when using Twilio as your gateway provider.
**Geographic Limitation:** Only US and Canada Caller IDs are supported for Twilio. For custom trunks, please check with your trunking provider on supported caller IDs.
#### **How Twilio Caller ID Works**
Twilio's Caller ID system allows you to display specific phone numbers to recipients, improving answer rates and call legitimacy.
#### **Configuration Requirements**
**Verify Your Numbers**
* All caller ID numbers must be verified with Twilio
* Verification prevents spoofing and ensures compliance
* Process typically takes 24-48 hours
**Regulatory Compliance**
* Follow local telecommunications regulations
* Ensure proper business registration
* Maintain accurate caller identification
**Optimize Number Usage**
* Rotate between verified numbers
* Match caller ID to campaign type
* Monitor number reputation and performance
#### **Best Practices**
**Caller ID Strategy:** Use local numbers for regional campaigns, toll-free numbers for national campaigns, and business numbers for professional services.
| Campaign Type | Recommended Caller ID | Benefits |
| -------------------- | ----------------------- | ------------------------------------------------- |
| **Local Business** | Local area code numbers | Higher answer rates, local trust |
| **National Service** | Toll-free numbers | Professional appearance, no charges to recipients |
| **Customer Service** | Main business line | Brand recognition, established trust |
| **Sales Outreach** | Dedicated sales numbers | Call tracking, performance measurement |
***
## Next Steps
Now that you understand call settings:
1. **Configure your transfer number** based on your routing needs
2. **Select the appropriate AI model** for your use case
3. **Choose your voice provider** (contact support for premium options)
4. **Set up voicemail detection** to optimize costs
5. **Configure caller ID** if using Twilio
**Ready to optimize your calls?** Proper call settings configuration ensures professional, cost-effective, and successful AI calling campaigns. Take time to configure each setting according to your specific needs.
***
**Need advanced configuration?** Check out our [Advanced Settings](/call-settings/advanced-settings) guide for language codes, ASR options, webhooks, and transfer configurations.
# ๐ Campaign Run - Control Your Running Campaigns
Source: https://docs.vodex.ai/campaign/campaign-run
Learn how to control your running campaigns, stop calls when needed, and view detailed information about your campaign performance
**What you'll learn:** How to control your running campaigns, stop calls when needed, and see all the details about what's happening with your calls.
## What Is a Campaign Run?
Think of a **campaign run** like a **live TV show** - it's what happens when your campaign is actually making phone calls right now!
* **Campaign Run** = Your campaign is actively calling people
* **Running Campaign** = Phone calls are happening right now
* **Campaign Run Details** = All the information about what happened during the calls
## How to Get to the Campaign Run Page
### **Step 1: Find the Redirect Icon**
1. **Look for a small arrow icon** (โ๏ธ) in your campaign page
2. **This icon is like a door** that takes you to different places
3. **Click on this redirect icon** when you want to see your running campaigns
**Important:** The redirect icon looks like a small arrow pointing up and to the right. It's usually located near your campaign information.
### **Step 2: You're Now on the Campaign Run Page!**
After clicking the redirect icon, you'll see the **"Campaign Run"** page. This page shows you:
* **All your running campaigns** (campaigns that are making calls right now)
* **Campaign status** (is it working? is it paused?)
* **Action buttons** (things you can do to control your campaign)
## What You Can Do on the Campaign Run Page
### **๐ซ Stop Your Campaign (Stop All Calls)**
Sometimes you need to **stop calling people immediately**. Here's how:
1. **Find your running campaign** in the list
2. **Look for the "Actions" section** (it's like a toolbox with buttons)
3. **Click on "Stop Campaign"** button
4. **All calls will stop immediately** - no more phone calls will be made
**Why stop a campaign?** Maybe you made a mistake, or you want to change something, or you've reached your goal. Stopping is like pressing a big red "STOP" button!
### **๐๏ธ View Campaign Details (See What Happened)**
Want to know **exactly what happened** with your calls? Here's how:
1. **Find your campaign** in the list
2. **Look for "View Details"** button
3. **Click on "View Details"**
4. **You'll go to the "Campaign Run Details" page**
## What You'll See on the Campaign Run Details Page
The **Campaign Run Details** page is like a **detailed report card** for your campaign. It shows you:
### **๐ Call Information**
* **How many calls were made** (total number)
* **How many calls were answered** (people who picked up)
* **How many calls were missed** (people who didn't answer)
* **How long each call lasted** (call duration)
### **๐ฏ Call Results**
* **What happened in each call** (did the person show interest?)
* **Call outcomes** (successful, not interested, wrong number, etc.)
* **Insights collected** (information gathered from the calls)
### **โฐ Timing Information**
* **When calls started** (start time)
* **When calls finished** (end time)
* **How long the campaign ran** (total duration)
## Simple Example: Understanding Campaign Run
Let's say you have a **"Pizza Delivery Campaign"**:
### **Before Running:**
* Campaign is created โ
* AI Agent is ready โ
* Audience list is loaded โ
* Campaign is NOT running yet โ
### **During Campaign Run:**
* Campaign is ACTIVE ๐ข
* AI Agent is calling people ๐
* Phone calls are happening right now โฐ
* You can see live updates ๐
### **After Stopping:**
* Campaign is STOPPED ๐ด
* No more calls are being made โ
* You can see final results ๐
* You can start again if needed ๐
## Visual Guide: Campaign Run Flow
Here's a simple picture showing how campaign run works:
```mermaid theme={null}
flowchart TD
A[Campaign Created] --> B[Click Start Campaign]
B --> C[Campaign is Running!]
C --> D[Phone Calls Happening]
D --> E{Want to Stop?}
E -->|Yes| F[Click Stop Campaign]
E -->|No| G[Let it Continue]
F --> H[All Calls Stop]
G --> I[More Calls Continue]
H --> J[View Campaign Details]
I --> J
J --> K[See All Results]
K --> L[Campaign Complete!]
style C fill:#90EE90
style D fill:#90EE90
style H fill:#FFB6C1
style K fill:#87CEEB
```
## Common Questions About Campaign Run
### **โ "Can I stop my campaign and start it again?"**
**Answer:** Yes! You can stop your campaign anytime and start it again later. It's like pausing a video and then playing it again.
### **โ "What happens if I stop my campaign?"**
**Answer:** When you stop a campaign:
* **Calls that are already happening** will finish normally
* **New calls won't start** (like turning off a faucet)
* **All your progress is saved** (nothing is lost)
### **โ "How do I know if my campaign is running?"**
**Answer:** Look for:
* **Green status indicator** (๐ข = running)
* **Live call counter** (numbers changing)
* **"Stop Campaign" button** (visible when running)
### **โ "Can I see what's happening while calls are running?"**
**Answer:** Yes! You can:
* **Watch live updates** on the campaign run page
* **See call progress** in real-time
* **Monitor performance** as it happens
## Best Practices for Campaign Run
### **๐ฏ Before Starting Your Campaign**
* **Test with a small audience first** (like trying a recipe with a small portion)
* **Make sure your AI Agent is ready** (check your prompts and settings)
* **Have your audience list ready** (make sure phone numbers are correct)
### **๐ While Your Campaign is Running**
* **Monitor the progress** (check in regularly to see how it's going)
* **Watch for any issues** (like calls not connecting or wrong numbers)
* **Be ready to stop if needed** (have a plan for emergencies)
### **๐ After Your Campaign Finishes**
* **Review the results** (see what worked and what didn't)
* **Check the insights** (what information did you collect?)
* **Plan improvements** (what can you do better next time?)
## What's Next?
Now that you understand how to control your running campaigns:
1. **Try starting a small campaign** to see how it works
2. **Practice stopping and starting** to get comfortable with the controls
3. **Explore the campaign details** to see all the information available
4. **Check out other campaign guides** to learn more advanced features
**Remember:** Campaign Run is like being the director of a live show. You can start it, stop it, and see exactly what's happening at any time!
***
## Need Help?
If you have questions about controlling your campaigns:
* **Check the troubleshooting guide** for common issues
* **Review your campaign settings** to make sure everything is correct
* **Contact support** if you need additional help
Go back to the main Campaign Guide to learn more about creating and managing campaigns.
# ๐ข Campaign Guide
Source: https://docs.vodex.ai/campaign/guide
Learn how to create and run calling campaigns that connect your AI agents with your audience - complete step-by-step instructions
**What you'll learn:** How to create calling campaigns that connect your AI agents with your audience lists, and how to start making calls automatically.
## What Is a Campaign?
Think of a **campaign** as a **calling project** - it's how you organize and start your AI calling activities. A campaign connects three important things:
1. **Your AI Agent** - The virtual caller that makes the phone calls
2. **Your Audience** - The list of people you want to call
3. **Your Calling Strategy** - How and when the calls will happen
## Why Do You Need Campaigns?
* **Organize your calling activities** - Keep different calling projects separate
* **Track results** - See how well each calling effort performs
* **Control the process** - Decide when to start and stop calling
* **Measure success** - Know how many calls were made and their outcomes
## How to Create Your First Campaign
### **Step 1: Start Creating a Campaign**
1. Go to the **Campaign section** in your dashboard
2. Click the **"+ Add New Campaign"** button
3. You'll see a form where you can set up your campaign
### **Step 2: Give Your Campaign a Name**
First, you need to identify your campaign:
| Field | What to Enter | Example |
| ----------------- | --------------------------------------- | ----------------------- |
| **Campaign Name** | A name to identify this calling project | "Q1 Customer Follow-up" |
**Important:** Choose a clear, descriptive name for your campaign. This helps you track different calling efforts and measure their success.
### **Step 3: Select Your Audience**
This is where you choose who your AI agent will call:
1. **Click on the audience dropdown** menu
2. **Select the audience list** you created earlier
3. **This tells your campaign** which people to call
**Pro Tip:** Make sure you've already created your audience list before starting a campaign. If you haven't, check out our [Audience Guide](/audience/guide) first.
### **Step 4: Choose Campaign Type**
You have **two options** for how your campaign will work:
#### **Option A: Default Campaign Type**
* **What it does:** Makes calls one after another automatically
* **When to use:** When you want to call everyone in your audience list
* **How it works:** The system calls each person in order until everyone has been contacted
#### **Option B: Range Campaign Type**
* **What it does:** Gives you control over how many calls to make
* **When to use:** When you want to test with a smaller group first
* **How it works:** You can set limits on the number of calls or specific time periods
**Recommendation:** Start with "Default" for your first campaign. It's simpler and will call everyone in your audience automatically.
### **Step 5: Save Your Campaign**
1. **Review your settings** to make sure everything is correct
2. **Click "Save"** to create your campaign
3. **Your campaign is now ready** but not yet running
## Visual Guide: Creating a Campaign
Here's a simple flowchart showing the campaign creation process:
```mermaid theme={null}
flowchart TD
A[Click + Add New Campaign] --> B[Enter Campaign Name]
B --> C[Select Audience List]
C --> D[Choose Campaign Type]
D --> E{Type Selection}
E -->|Default| F[Default Campaign Type]
E -->|Range| G[Range Campaign Type]
F --> H[Click Save]
G --> H
H --> I[Campaign Created Successfully!]
I --> J[Ready to Run Campaign]
J --> K[Click Run Campaign]
K --> L[AI Agent Starts Making Calls]
L --> M[Calls Go to Entire Audience]
M --> N[Conversations Based on Prompt]
```
## What Happens After You Create a Campaign?
Once your campaign is saved:
1. **It appears in your campaign list** - You can see it in the dashboard
2. **It's ready to run** - But not yet making calls
3. **You can edit it** - Change settings if needed
4. **You can start it** - Begin making calls when you're ready
## How to Run Your Campaign
### **Starting Your Campaign:**
1. **Find your campaign** in the campaign list
2. **Click "Run Campaign"** button
3. **Confirm the action** if prompted
4. **Your campaign is now active!**
### **What Happens When You Run a Campaign:**
Once you click "Run Campaign":
* **AI Agent starts working** - Begins making phone calls automatically
* **Calls go to your entire audience** - Everyone in your selected list gets called
* **Conversations begin** - Each call follows the instructions in your AI agent's prompt
* **Progress tracking starts** - You can monitor how many calls are made and their results
**Important:** Make sure your AI agent is properly configured with a good prompt before running your campaign. The quality of your calls depends on how well your agent is set up.
## Campaign Types Explained
### **Default Campaign Type:**
**What it does:**
* Calls everyone in your audience list automatically
* 5,000 limits on the number of calls
* Runs until all people have been contacted
**Best for:**
* Complete audience coverage under 5000
* When you want to reach everyone
* Simple, straightforward calling campaigns
**Example:**
* Audience: 10,000 customers
* Campaign: "Customer Satisfaction Survey"
* Result: The first 5,000 customers will receive calls initially, and once that group is completed, the remaining 5,000 customers will then receive calls.
### **Range Campaign Type:**
**What it does:**
* Gives you control over call volume and timing
* Can limit the number of calls per day
* Allows for more strategic calling patterns
**Best for:**
* Testing campaigns with smaller groups
* Controlling call volume during business hours
* A/B testing different approaches
**Example:**
* Audience: 10000 customers
* Campaign: "Test Campaign - 2000 Calls"
* Result: Only 2000 customers receive calls initially
## Campaign Management Tips
### **Before Running Your Campaign:**
1. **Test your AI agent** - Make sure it works correctly
2. **Verify your audience** - Check that contact information is correct
3. **Review your prompt** - Ensure your agent has good instructions
4. **Set appropriate timing** - Consider when people are most likely to answer
### **While Your Campaign is Running:**
1. **Monitor progress** - Watch how many calls are being made
2. **Check call quality** - Listen to recordings if available
3. **Track results** - See how people are responding
4. **Be ready to adjust** - Make changes if needed
### **After Your Campaign:**
1. **Review results** - See how many calls were successful
2. **Analyze performance** - Understand what worked and what didn't
3. **Update your strategy** - Make improvements for next time
4. **Plan follow-ups** - Decide what to do with the results
## Common Questions About Campaigns
### **How Long Does a Campaign Take?**
* **Depends on audience size** - 100 people might take a few hours
* **Depends on call duration** - Longer conversations = fewer calls per hour
* **Depends on system capacity** - How many calls can happen simultaneously
### **Can I Stop a Campaign?**
* **Yes!** You can pause or stop campaigns anytime
* **Pause temporarily** - Stop calling but keep the campaign active
* **Stop completely** - End the campaign and don't make more calls
### **What Happens If Someone Doesn't Answer?**
* **Your AI agent handles it** - Follows the instructions in your prompt
* **May leave voicemail** - If you've configured voicemail messages
* **May try again later** - Depending on your campaign settings
### **Can I Run Multiple Campaigns at Once?**
* **Yes!** You can have several campaigns running simultaneously
* **Different audiences** - Target different groups of people
* **Different purposes** - Sales, customer service, surveys, etc.
* **Track separately** - Monitor each campaign's performance individually
## Best Practices for Successful Campaigns
### **1. Start Small**
* **Test with small audiences** first (10-20 people)
* **Verify everything works** before scaling up
* **Learn from early results** and make adjustments
### **2. Use Clear Naming**
* **Be specific:** "Q1 Sales Follow-up" instead of "Campaign 1"
* **Include purpose:** "Customer Satisfaction Survey March 2024"
* **Add audience info:** "VIP Customer Retention Campaign"
### **3. Monitor Progress**
* **Check regularly** while campaigns are running
* **Look for patterns** in call results
* **Be ready to adjust** if something isn't working
### **4. Learn and Improve**
* **Review results** after each campaign
* **Identify what worked** and what didn't
* **Make changes** to improve future campaigns
## What Happens When Calls Are Made?
### **The Calling Process:**
1. **AI Agent selects** the next person from your audience
2. **Makes the phone call** using the phone number in your list
3. **Delivers greeting** based on your agent's configuration
4. **Follows the prompt** - Has conversations according to your instructions
5. **Handles responses** - Adapts to what the person says
6. **Ends call appropriately** - Uses tags or natural conversation flow
7. **Moves to next person** - Continues with the audience list
### **Call Outcomes:**
* **Successful conversations** - Person answered and talked to your agent
* **Voicemail messages** - Left appropriate messages when no one answered
* **No answers** - Calls that didn't connect
* **Busy signals** - Lines that were occupied
## Next Steps
Now that you understand how to create campaigns:
1. **Go to the Campaign section** and click "+ Add New Campaign"
2. **Give your campaign a clear name** for easy identification
3. **Select the audience** you want to call
4. **Choose campaign type** (start with Default)
5. **Save your campaign** and review the settings
6. **Click "Run Campaign"** when you're ready to start calling
**Ready to launch your calling campaign?** Follow these steps to create professional, effective campaigns that will help your AI agents reach your audience and achieve your calling goals.
***
**Need help with audiences?** Check out our [Audience Guide](/audience/guide) to learn how to create the contact lists your campaigns will use.
**Want to learn about AI agents?** Visit our [Agents Overview](/agents/overview) to understand how to create the virtual callers that will make your campaign calls.
# โ
Custom Fields Best Practices
Source: https://docs.vodex.ai/custom-fields/best-practices
Learn the essential rules and best practices for using custom fields effectively in your AI prompts
**What you'll learn:** Essential rules, naming conventions, and best practices to make your custom fields work perfectly every time.
## The Golden Rules of Custom Fields
### **Rule 1: No Spaces Ever** ๐จ
This is the most important rule: **Custom field names cannot contain spaces**.
| โ
**Correct** | โ **Wrong** | What Happens |
| ----------------- | ------------------ | ---------------- |
| `{FirstName}` | `{First Name}` | โ System error |
| `{AccountNumber}` | `{Account Number}` | โ Data not found |
| `{PaymentAmount}` | `{Payment Amount}` | โ Field fails |
### **Rule 2: Use Underscores for Multiple Words**
When you need multiple words, connect them with underscores:
```
{Account_Number} โ
Correct
{Payment_Amount} โ
Correct
{Appointment_Date} โ
Correct
{Doctor_Name} โ
Correct
```
### **Rule 3: Be Consistent with Naming**
Choose a naming style and stick to it throughout your system:
**PascalCase (Recommended)**
```
{FirstName}
{AccountNumber}
{PaymentAmount}
```
**Important:** Pick this style and use it consistently. Don't mix different naming conventions in the same system.
## Field Naming Guidelines
### **โ
Good Field Names**
* **Clear and descriptive:** `{AccountNumber}` instead of `{Acc}`
* **Consistent format:** All fields follow the same pattern
* **Easy to understand:** `{PaymentAmount}` instead of `{PayAmt}`
* **Professional:** `{CustomerName}` instead of `{CustName}`
### **โ Avoid These Naming Patterns**
* **Abbreviations:** `{AccNum}` (unclear)
* **Mixed formats:** `{FirstName}` and `{last_name}` (inconsistent)
* **Too long:** `{CustomerAccountPaymentAmountDueDate}` (confusing)
* **Special characters:** `{Account#}` or `{Amount$}` (causes errors)
## Common Custom Field Categories
### **Personal Information Fields**
| Field Name | Purpose | Example |
| ------------- | ------------------ | ----------------- |
| `{FirstName}` | User's first name | "Hello John" |
| `{LastName}` | User's last name | "Mr. Smith" |
| `{FullName}` | Complete name | "John Smith" |
| `{Title}` | Professional title | "Dr. Smith" |
| `{Company}` | Company name | "ABC Corporation" |
### **Contact Information Fields**
| Field Name | Purpose | Example |
| ---------------- | ---------------- | ----------------------------------------- |
| `{PhoneNumber}` | Contact phone | "555-123-4567" |
| `{EmailAddress}` | Email address | "[john@email.com](mailto:john@email.com)" |
| `{Address}` | Physical address | "123 Main St" |
| `{City}` | City name | "New York" |
| `{State}` | State/province | "NY" |
| `{ZipCode}` | Postal code | "10001" |
### **Account and Financial Fields**
| Field Name | Purpose | Example |
| ----------------- | ------------------- | ------------------- |
| `{AccountNumber}` | Account identifier | "ACC12345" |
| `{AccountType}` | Type of account | "Savings" |
| `{Balance}` | Current balance | "\$1,250.00" |
| `{AmountDue}` | Outstanding amount | "\$500.00" |
| `{DueDate}` | Payment deadline | "March 30, 2024" |
| `{LastPayment}` | Last payment amount | "\$200.00" |
| `{PaymentDate}` | Last payment date | "February 15, 2024" |
### **Time and Date Fields**
| Field Name | Purpose | Example |
| ------------------- | ---------------- | -------------------------- |
| `{today}` | Current date | "March 15, 2024" |
| `{time_zone}` | User's time zone | "+05:30" or "Asia/Kolkata" |
| `{AppointmentDate}` | Scheduled date | "March 20, 2024" |
| `{AppointmentTime}` | Scheduled time | "3:00 PM" |
### **Product and Service Fields**
| Field Name | Purpose | Example |
| ---------------- | -------------------- | ------------------- |
| `{ProductName}` | Product name | "Premium Plan" |
| `{ServiceType}` | Service category | "Technical Support" |
| `{OrderNumber}` | Order identifier | "ORD789" |
| `{OrderDate}` | Order placement date | "March 10, 2024" |
| `{ProductPrice}` | Product cost | "\$99.99" |
## Advanced Custom Field Techniques
### **Combining Multiple Fields**
You can use multiple custom fields in the same sentence for rich, personalized conversations:
```
"Hello {FirstName}, I can see you have an outstanding balance of {AmountDue}
on account {AccountNumber} that was due on {DueDate}. Based on your
payment history, I'd like to discuss a payment plan that works for you."
```
### **Conditional Custom Fields**
Some systems support conditional logic with custom fields:
```
"Hello {FirstName}, your account {AccountNumber} shows a balance of {Balance}.
{IfBalancePositive: Since you have a credit, you're all set!}
{IfBalanceNegative: You have an outstanding amount of {AmountDue} due by {DueDate}.}"
```
**Note:** Conditional custom fields require advanced system support. Check with your platform provider for availability.
## Testing Your Custom Fields
### **Before Going Live**
1. **Test with sample data** - Use real user information to verify fields populate correctly
2. **Check field names** - Ensure no spaces or special characters
3. **Verify data accuracy** - Confirm the right information appears in the right places
4. **Test conversation flow** - Make sure the personalized message sounds natural
### **Common Testing Scenarios**
| Test Case | What to Check | Expected Result |
| -------------------- | --------------------------- | ---------------------------------- |
| **Basic fields** | `{FirstName}`, `{LastName}` | Names appear correctly |
| **Financial fields** | `{AmountDue}`, `{DueDate}` | Numbers and dates format properly |
| **Time fields** | `{today}`,`{time_zone}` | Current date displays |
| **Empty fields** | Missing data | Graceful handling or fallback text |
## Troubleshooting Common Issues
### **Problem: Field Not Populating**
**Possible Causes:**
* Field name has spaces
* Field name doesn't match database
* Data is missing for that user
* System configuration error
**Solutions:**
1. Check for spaces in field name
2. Verify field name matches exactly
3. Confirm data exists in database
4. Check system configuration
### **Problem: Wrong Data Appearing**
**Possible Causes:**
* Field name too similar to another field
* Database mapping error
* Data corruption
**Solutions:**
1. Use unique, descriptive field names
2. Verify database field mapping
3. Check data integrity
### **Problem: Field Causes Error**
**Possible Causes:**
* Invalid characters in field name
* System doesn't recognize field
* Syntax error in prompt
**Solutions:**
1. Remove special characters
2. Use only letters, numbers, and underscores
3. Check prompt syntax
## Best Practices Checklist
Use this checklist to ensure your custom fields work perfectly:
* [ ] **Field names have no spaces** - Use underscores instead
* [ ] **Naming is consistent** - Same format throughout system
* [ ] **Names are descriptive** - Clear what each field contains
* [ ] **Testing completed** - Verified with real data
* [ ] **Error handling** - Graceful fallbacks for missing data
* [ ] **Documentation updated** - Team knows how to use fields
* [ ] **Backup plan** - What happens if fields fail
## Performance Considerations
### **Field Loading Speed**
* **Keep field names short** - Long names can slow processing
* **Limit field count** - Too many fields may impact performance
* **Cache frequently used data** - Reduce database lookups
### **Data Accuracy**
* **Real-time updates** - Ensure data is current
* **Validation rules** - Check data quality before using
* **Fallback values** - Provide defaults for missing data
## Security and Privacy
### **Data Protection**
* **Sensitive information** - Don't include passwords or SSNs in custom fields
* **Access control** - Limit who can see custom field data
* **Audit logging** - Track when custom fields are used
### **Compliance**
* **GDPR considerations** - Ensure user consent for personal data
* **Industry regulations** - Follow financial, healthcare, or other specific rules
* **Data retention** - Know how long to keep custom field data
## Next Steps
Now that you understand custom field best practices:
1. **Review your current fields** - Apply these best practices to existing custom fields
2. **Plan new implementations** - Use proper naming conventions from the start
3. **Test thoroughly** - Verify everything works before going live
4. **Train your team** - Ensure everyone follows the same standards
5. **Monitor performance** - Watch for any issues and optimize as needed
**Ready to implement custom fields correctly?** Following these best practices will ensure your custom fields work reliably, efficiently, and professionally. Start implementing them today to create more engaging and personalized AI conversations.
***
**Need the basics?** Check out our [Custom Fields Introduction](/custom-fields/introduction) to understand the fundamentals before diving into these best practices.
# ๐งฎ Computation Custom Fields
Source: https://docs.vodex.ai/custom-fields/computation
Learn how to use advanced computation features including math calculations, date operations, end-of-week, end-of-month, next-date, and date-range utilities in your custom fields
**Beta Feature:** Computation custom fields are currently in beta. While fully functional, this feature may receive updates and improvements. Please test thoroughly before using in production environments.
**What you'll learn:** How to perform mathematical calculations, date manipulations, end-of-week calculations, end-of-month calculations, next-date calculations, and date range calculations directly within your custom fields using `mathutil`, `dateutil`, `end_of_week`, `end_of_month`, `next_date`, and `date_range` utilities.
## What Are Computation Custom Fields?
Computation custom fields are **advanced dynamic placeholders** that can perform calculations and manipulations on your data in real-time. Instead of just inserting static values, these fields can:
* **Perform mathematical operations** (addition, subtraction, multiplication, division)
* **Calculate dates** (add or subtract days, months, years, hours, minutes, seconds)
* **Find next specific weekday** (next Monday, Friday, Sunday, etc.)
* **Calculate end of month** (last day of current month)
* **Find next occurrence of day of month** (next 5th, 15th, 28th, etc.)
* **Calculate date ranges** (formatted list of days from start date + number of days)
* **Create dynamic values** based on existing custom field data
Think of them as **smart calculators** embedded within your custom fields that automatically compute values when your AI conversations start.
## Why Use Computation Custom Fields? ๐ฏ
### **The Problem:**
* Need to calculate payment amounts with interest or fees
* Want to set reminder dates based on due dates
* Require dynamic pricing based on existing values
* Need follow-up dates calculated automatically
### **The Solution:**
* Real-time calculations within your prompts
* No manual math or date calculations needed
* Dynamic values that update automatically
* Professional, accurate, and consistent results
## Math Utility (mathutil) ๐ข
The `mathutil` function lets you perform mathematical operations on numeric custom fields.
### **Basic Syntax**
```
{mathutil:{FieldName}[operation][value]}
```
### **Supported Operations**
| Operation | Symbol | Description | Example |
| ------------------ | ------ | -------------------- | ----------------------------- |
| **Addition** | `+` | Add a number | `{mathutil:{AmountDue}+50}` |
| **Subtraction** | `-` | Subtract a number | `{mathutil:{AmountDue}-25}` |
| **Multiplication** | `*` | Multiply by a number | `{mathutil:{AmountDue}*1.05}` |
| **Division** | `/` | Divide by a number | `{mathutil:{AmountDue}/2}` |
### **Math Examples**
#### **Adding Late Fees**
```
Original Amount: {AmountDue}
With Late Fee: {mathutil:{AmountDue}+25}
```
**Result:**
```
Original Amount: $500.00
With Late Fee: $525.00
```
#### **Calculating Interest**
```
Principal: {LoanAmount}
With 5% Interest: {mathutil:{LoanAmount}*1.05}
```
**Result:**
```
Principal: $10,000.00
With 5% Interest: $10,500.00
```
#### **Payment Plans**
```
Total Amount: {AmountDue}
Monthly Payment (12 months): {mathutil:{AmountDue}/12}
```
**Result:**
```
Total Amount: $1,200.00
Monthly Payment (12 months): $100.00
```
#### **Discounts**
```
Original Price: {ProductPrice}
After 20% Discount: {mathutil:{ProductPrice}*0.8}
```
**Result:**
```
Original Price: $250.00
After 20% Discount: $200.00
```
### **Advanced Math Examples**
#### **Complex Financial Calculations**
```
"Hello {FirstName}, your account {AccountNumber} has an outstanding balance
of {AmountDue}. With the late fee of $25, your total amount due is
{mathutil:{AmountDue}+25}. We can offer you a payment plan of
{mathutil:{AmountDue}/6} per month for 6 months."
```
#### **Pricing Adjustments**
```
"Based on your subscription to {PlanName} at {MonthlyRate} per month,
your annual cost would be {mathutil:{MonthlyRate}*12}. However, if you
upgrade to our annual plan, you'd pay only {mathutil:{MonthlyRate}*10}
for the entire year."
```
## Date Utility (dateutil) ๐
The `dateutil` function lets you calculate dates by adding or subtracting time periods from existing dates.
### **Basic Syntax**
```
{dateutil:{FieldName}[+/-][amount][unit]}
```
### **Supported Time Units**
| Unit | Symbol | Description | Example |
| ----------- | ------ | --------------- | --------------------------- |
| **Days** | `d` | Calendar days | `+5d` (5 days later) |
| **Months** | `m` | Calendar months | `-2m` (2 months ago) |
| **Years** | `y` | Calendar years | `+1y` (1 year later) |
| **Hours** | `h` | Hours | `+24h` (24 hours later) |
| **Minutes** | `min` | Minutes | `+30min` (30 minutes later) |
| **Seconds** | `s` | Seconds | `+3600s` (1 hour later) |
### **Special Date References**
| Reference | Description | Usage |
| ------------- | ----------------- | -------------------------- |
| `{today}` | Current date/time | `{dateutil:{today}+7d}` |
| `{FieldName}` | Any date field | `{dateutil:{DueDate}+30d}` |
### **Date Examples**
#### **Payment Reminders**
```
Today: {today}
Payment Due: {DueDate}
Final Notice Date: {dateutil:{DueDate}+30d}
```
**Result:**
```
Today: March 15, 2024
Payment Due: March 30, 2024
Final Notice Date: April 29, 2024
```
#### **Appointment Scheduling**
```
Current Date: {today}
Next Available: {dateutil:{today}+3d}
Follow-up Date: {dateutil:{AppointmentDate}+14d}
```
**Result:**
```
Current Date: March 15, 2024 09:30:00
Next Available: March 18, 2024 09:30:00
Follow-up Date: April 2, 2024 14:00:00
```
#### **Contract Periods**
```
Contract Start: {StartDate}
Contract End: {dateutil:{StartDate}+1y}
Renewal Notice: {dateutil:{StartDate}+10m}
```
**Result:**
```
Contract Start: January 1, 2024
Contract End: January 1, 2025
Renewal Notice: November 1, 2024
```
### **Advanced Date Examples**
#### **Debt Collection Timeline**
```
"Hello {FirstName}, your payment of {AmountDue} was due on {DueDate}.
It's now {dateutil:{DueDate}+15d} past due. If we don't receive payment
by {dateutil:{today}+7d}, we'll need to escalate this matter."
```
#### **Subscription Management**
```
"Your {PlanName} subscription started on {SubscriptionStart} and will
renew on {dateutil:{SubscriptionStart}+1m}. Your next billing date is
{dateutil:{today}+{DaysUntilBilling}d}."
```
## End of Week Utility (end\_of\_week) ๐
The `end_of_week` function calculates the next occurrence of a specific day of the week from today's date.
### **Basic Syntax**
```
{end_of_week:[day_number]}
```
### **Day Numbers (Python Convention)**
| Day Number | Day of Week | Description |
| ---------- | ----------- | ---------------------- |
| `0` | Monday | Next Monday |
| `1` | Tuesday | Next Tuesday |
| `2` | Wednesday | Next Wednesday |
| `3` | Thursday | Next Thursday |
| `4` | Friday | Next Friday |
| `5` | Saturday | Next Saturday |
| `6` | Sunday | Next Sunday |
| `7` | Sunday | Alternative for Sunday |
The day numbers follow Python's `weekday()` convention where Monday is 0 and Sunday is 6. You can also use `7` for Sunday.
### **How It Works**
The `end_of_week` utility calculates the **next occurrence** of the specified day:
* If today is Tuesday and you specify `{end_of_week:0}` (Monday), you'll get the date for next Monday (6 days later)
* If today is Monday and you specify `{end_of_week:0}` (Monday), you'll get the date for next Monday (7 days later, not today)
* The function always returns a future date, never today's date
### **End of Week Examples**
#### **Setting Deadlines by Day**
```
Today: {today}
By Next Monday: {end_of_week:0}
By Next Friday: {end_of_week:4}
By Next Sunday: {end_of_week:6}
```
**Result (assuming today is Wednesday, March 13, 2024):**
```
Today: 13 Mar 2024
By Next Monday: 18 Mar 2024
By Next Friday: 15 Mar 2024
By Next Sunday: 17 Mar 2024
```
#### **Weekly Payment Reminders**
```
"Hello {FirstName}, your payment of {AmountDue} is due by this coming
Friday, {end_of_week:4}. Please ensure payment is received by end of day."
```
#### **Appointment Scheduling with Specific Days**
```
"We have availability next Monday ({end_of_week:0}) or next Thursday
({end_of_week:3}). Which day works better for you?"
```
### **Practical Use Cases**
#### **Weekly Follow-ups**
```
"Hello {CustomerName}, we'll follow up with you by {end_of_week:4}
regarding your account {AccountNumber}."
```
#### **Business Week Deadlines**
```
"Your order {OrderNumber} will be shipped by end of business week on
{end_of_week:4} (Friday)."
```
#### **Weekend Coordination**
```
"This weekend opportunity ends on {end_of_week:6} (Sunday) at midnight.
Don't miss out on this special offer of {mathutil:{ProductPrice}*0.8}!"
```
## End of Month Utility (end\_of\_month) ๐
The `end_of_month` function calculates the last day of the current month.
### **Basic Syntax**
```
{end_of_month}
```
The `end_of_month` utility is straightforward - it simply returns the last day of the current month. No parameters needed!
### **How It Works**
* Automatically calculates the last day of the current month
* Handles varying month lengths (28, 29, 30, or 31 days)
* Accounts for leap years in February
* Returns date in format: "DD MMM YYYY" (e.g., "31 Mar 2024")
### **End of Month Examples**
#### **Monthly Deadlines**
```
Today: {today}
End of This Month: {end_of_month}
```
**Result (assuming today is March 15, 2024):**
```
Today: 15 Mar 2024
End of This Month: 31 Mar 2024
```
#### **Monthly Payment Reminders**
```
"Hello {FirstName}, your monthly payment of {MonthlyPayment} is due by
the end of this month on {end_of_month}. Please ensure timely payment
to avoid late fees."
```
#### **Subscription Billing**
```
"Your {PlanName} subscription will renew at the end of this month
({end_of_month}) for {mathutil:{MonthlyRate}*1}."
```
### **Practical Use Cases**
#### **End of Month Campaigns**
```
"Hello {CustomerName}, our end-of-month sale ends on {end_of_month}!
Get {ProductName} for only {mathutil:{ProductPrice}*0.85} - that's 15% off
the regular price."
```
#### **Billing Cycles**
```
"Your account {AccountNumber} has a balance of {AmountDue}. Payment is
due by {end_of_month} to maintain your service without interruption."
```
#### **Performance Targets**
```
"Team, we have until {end_of_month} to reach our monthly goal. Let's
push forward!"
```
#### **Financial Deadlines**
```
"Hello {FirstName}, your quarterly payment of {QuarterlyAmount} must be
received by end of month ({end_of_month}). This covers your service
through {dateutil:{today}+3m}."
```
## Next Date Utility (next\_date) ๐
The `next_date` function calculates the next occurrence of a specific day of the month, making it perfect for setting deadlines, billing dates, and recurring monthly events.
### **Basic Syntax**
```
{next_date:[start_date]+[day_number]}
```
### **Parameters**
| Parameter | Description | Example | Required |
| ------------ | ------------------------------------- | -------------------------- | -------- |
| `start_date` | Starting date (field name or {today}) | `{StartDate}` or `{today}` | โ
Yes |
| `day_number` | Target day of the month (1-31) | `5`, `15`, `28` | โ
Yes |
### **How It Works**
The `next_date` utility calculates the next occurrence of a specific day of the month:
* **Start Date**: Can be any custom field containing a date or `{today}`
* **Day Number**: The target day of the month (1-31)
* **Logic**:
* If current day โค target day: Returns target day in the **current month**
* If current day > target day: Returns target day in the **next month**
* **Result**: Returns the date in "DD MMM YYYY, (DayName)" format
### **Next Date Examples**
#### **From Today for Next 5th**
```
Today: {today}
Next 5th: {next_date:{today}+5}
```
**Result (assuming today is November 1, 2024):**
```
Today: 01 Nov 2024
Next 5th: 05 Nov 2024, (Tuesday)
```
**Result (assuming today is November 15, 2024):**
```
Today: 15 Nov 2024
Next 5th: 05 Dec 2024, (Thursday)
```
#### **From Start Date for Next 10th**
```
Start Date: {StartDate}
Next 10th: {next_date:{StartDate}+10}
```
**Result (if StartDate is January 8, 2024):**
```
Start Date: 08 Jan 2024
Next 10th: 10 Jan 2024, (Wednesday)
```
**Result (if StartDate is January 20, 2024):**
```
Start Date: 20 Jan 2024
Next 10th: 10 Feb 2024, (Saturday)
```
#### **Monthly Billing Date**
```
Current Date: {today}
Next Billing: {next_date:{today}+15}
```
**Result:**
```
Current Date: 05 Mar 2024
Next Billing: 15 Mar 2024, (Friday)
```
**Result (if today is March 20, 2024):**
```
Current Date: 20 Mar 2024
Next Billing: 15 Apr 2024, (Monday)
```
### **Advanced Next Date Examples**
#### **Monthly Payment Deadlines**
```
"Hello {FirstName}, your payment of {AmountDue} is due on the 5th of each month.
Your next payment deadline is {next_date:{today}+5}. Please ensure payment is
received by then to avoid late fees."
```
#### **Billing Cycle Management**
```
"Your {ServiceName} subscription bills on the 15th of each month.
Your next billing date is {next_date:{today}+15} for {mathutil:{MonthlyRate}*1}.
This will be automatically charged to your account."
```
#### **Recurring Deadlines**
```
"Project {ProjectName} has a monthly review on the 28th.
Your next review deadline is {next_date:{today}+28}.
Please submit your progress report by then."
```
### **Practical Use Cases**
#### **Monthly Payment Reminders**
```
"Hello {CustomerName}, your account {AccountNumber} has a monthly payment
due on the 5th. Your next payment of {AmountDue} is due on
{next_date:{today}+5}. Please ensure payment is received by end of day."
```
#### **Subscription Renewals**
```
"Your {PlanName} subscription renews on the 1st of each month.
Your next renewal date is {next_date:{today}+1} for
{mathutil:{MonthlyRate}*1}. Your service will continue automatically."
```
#### **Report Submission Deadlines**
```
"Your monthly report is due on the 10th of each month.
The next submission deadline is {next_date:{today}+10}.
Please ensure all data is submitted by end of day."
```
#### **Rent Payment Due Dates**
```
"Your rent payment of {RentAmount} is due on the 1st of each month.
Your next payment is due on {next_date:{today}+1}.
Late payments after the 5th will incur a fee of {mathutil:{RentAmount}*0.05}."
```
## Date Range Utility (date\_range) ๐
The `date_range` function calculates a date range FROM a start date FOR a specified number of days, making it perfect for creating time-based windows, billing periods, and scheduling ranges.
### **Basic Syntax**
```
{date_range:[start_date]-[number_of_days]}
```
### **Parameters**
| Parameter | Description | Example | Required |
| ---------------- | ------------------------------------------ | -------------------------- | -------- |
| `start_date` | Starting date (field name or {today}) | `{StartDate}` or `{today}` | โ
Yes |
| `number_of_days` | Number of days from start date (inclusive) | `5`, `30`, `90` | โ
Yes |
### **How It Works**
The `date_range` utility calculates a date range starting from a specified date:
* **Start Date**: Can be any custom field containing a date or `{today}`
* **Number of Days**: Specifies how many days forward from the start date (inclusive)
* **Result**: Returns a formatted list showing each day in the range with date and day of week
* **Inclusive**: The range includes both the start date and the end date
* **Format**: Each day shows as "DD MMM YYYY, DayName"
### **Date Range Examples**
#### **From Today for 6 Days**
```
Today: {today}
Range: {date_range:{today}-6}
```
**Result (assuming today is October 21, 2025):**
```
Today: 21 Oct 2025
Range:
1: 22 Oct 2025, Wednesday
2: 23 Oct 2025, Thursday
3: 24 Oct 2025, Friday
4: 25 Oct 2025, Saturday
5: 26 Oct 2025, Sunday
6: 27 Oct 2025, Monday
```
#### **From Start Date for 5 Days**
```
Start Date: {StartDate}
Range: {date_range:{StartDate}-5}
```
**Result:**
```
Start Date: 01 Jan 2024
Range:
1: 02 Jan 2024, Tuesday
2: 03 Jan 2024, Wednesday
3: 04 Jan 2024, Thursday
4: 05 Jan 2024, Friday
5: 06 Jan 2024, Saturday
```
#### **Payment Window**
```
Payment Due: {DueDate}
Grace Period: {date_range:{DueDate}-7}
```
**Result:**
```
Payment Due: 15 Mar 2024
Grace Period:
1: 16 Mar 2024, Saturday
2: 17 Mar 2024, Sunday
3: 18 Mar 2024, Monday
4: 19 Mar 2024, Tuesday
5: 20 Mar 2024, Wednesday
6: 21 Mar 2024, Thursday
7: 22 Mar 2024, Friday
```
### **Advanced Date Range Examples**
#### **Billing Cycle Window**
```
"Hello {FirstName}, your billing cycle starts today ({today}) and runs
for 7 days. Here are your billing days:
{date_range:{today}-7}
Your next payment of {mathutil:{MonthlyRate}*1} is due by the last day."
```
#### **Trial Period Tracking**
```
"Your {ServiceName} trial started on {TrialStart} and runs for 14 days:
{date_range:{TrialStart}-14}
You have until the last day to upgrade to avoid service interruption."
```
#### **Project Timeline**
```
"Project {ProjectName} started on {ProjectStart} and has a 5-day timeline:
{date_range:{ProjectStart}-5}
Please complete all tasks within this timeframe."
```
### **Practical Use Cases**
#### **Payment Grace Period**
```
"Hello {FirstName}, your payment of {AmountDue} was due on {DueDate}.
You have a 5-day grace period:
{date_range:{DueDate}-5}
After the last day, late fees of {mathutil:{AmountDue}*0.05} will apply."
```
#### **Subscription Trial**
```
"Your {PlanName} trial started on {TrialStart} and runs for 14 days:
{date_range:{TrialStart}-14}
To continue service, please upgrade by the last day."
```
#### **Campaign Duration**
```
"Our {CampaignName} campaign runs from {CampaignStart} for 7 days:
{date_range:{CampaignStart}-7}
Don't miss this limited-time offer!"
```
#### **Warranty Period**
```
"Your {ProductName} warranty is valid from {PurchaseDate} for 30 days:
{date_range:{PurchaseDate}-30}
Any claims must be submitted before the warranty expires."
```
## Combining Multiple Utilities ๐
You can combine math, date, end-of-week, end-of-month, next-date, and date-range utilities in the same prompt for sophisticated calculations:
### **Dynamic Payment Scheduling**
```
"Hello {FirstName}, your total amount of {AmountDue} can be split into
3 payments of {mathutil:{AmountDue}/3} each. The payment schedule would be:
- First payment: {mathutil:{AmountDue}/3} due {dateutil:{today}+7d}
- Second payment: {mathutil:{AmountDue}/3} due {dateutil:{today}+37d}
- Final payment: {mathutil:{AmountDue}/3} due {dateutil:{today}+67d}"
```
### **Interest Calculations with Dates**
```
"Your loan of {LoanAmount} has been outstanding since {LoanDate}.
With interest, your current balance is {mathutil:{LoanAmount}*1.05}.
If paid by {dateutil:{today}+30d}, you can settle for
{mathutil:{LoanAmount}*0.95}."
```
### **Weekly and Monthly Deadlines with Discounts**
```
"Hello {FirstName}, your account {AccountNumber} shows a balance of {AmountDue}.
Pay by this Friday ({end_of_week:4}): {mathutil:{AmountDue}*0.95} (5% discount)
Pay by end of month ({end_of_month}): {mathutil:{AmountDue}*0.98} (2% discount)
Pay after {end_of_month}: Full amount of {AmountDue} plus {mathutil:{AmountDue}*0.05} late fee"
```
### **Comprehensive Campaign with All Utilities**
```
"Hi {CustomerName}, special offer ending {end_of_week:6}!
Original Price: {ProductPrice}
Today's Discount: {mathutil:{ProductPrice}*0.80} (20% off)
Monthly Plan: {mathutil:{ProductPrice}/12} per month
First payment due: {end_of_week:4}
Final payment: {dateutil:{today}+11m}
Offer expires: {end_of_month}"
```
### **Advanced Analytics with Date Ranges**
```
"Hello {CustomerName}, your trial period started on {TrialStart} and
runs for 14 days:
{date_range:{TrialStart}-14}
Your subscription of {mathutil:{MonthlyRate}*12} annually will begin
after the trial ends.
Upgrade by the last day to avoid service interruption."
```
### **Monthly Billing with Next Date**
```
"Hello {FirstName}, your {ServiceName} subscription bills monthly on the 5th.
Your next billing date is {next_date:{today}+5} for {mathutil:{MonthlyRate}*1}.
Your account {AccountNumber} has been active since {AccountStart}.
Payment will be automatically charged on {next_date:{today}+5}.
If payment fails, you have until {dateutil:{next_date:{today}+5}+7d} to update your payment method."
```
## Required Fields and Dependencies ๐
### **For Date Utilities (dateutil, end\_of\_week, end\_of\_month, next\_date, date\_range):**
**Mandatory Fields for Date Operations:** When using any date utilities (`dateutil`, `end_of_week`, `end_of_month`, `next_date`, or `date_range`), both `{today}` and `{time_zone}` fields are **mandatory** and must be included in your prompt. During testing or when uploading audience data, you **must** provide the `time_zone` field, while `today` will be filled automatically by Vodex.
#### **Required Fields:**
* `today` - Current date/time (automatically provided by Vodex)
* `raw_today` - Raw timestamp format (automatically provided, used by end\_of\_week, end\_of\_month, and next\_date)
* `time_zone` - User's timezone (must be provided)
* **Date fields** - For `date_range` and `next_date`, start date fields must exist and contain valid dates
#### **Valid Timezone Formats:**
```
Asia/Kolkata โ
Correct
+05:30 โ
Correct
-08:00 โ
Correct
EST โ Avoid (use full timezone names)
```
**Important:** The `time_zone` field must be a valid timezone. Invalid timezones will cause "Something went wrong" errors.
The field `today` should be left blank when making calls via Agent Call, Campaign Run, or API. Vodex will fill it automatically using the `time_zone` field. For more details about these base fields, see our [Custom Fields Introduction](/custom-fields/introduction).
### **For Math Utilities:**
* The referenced field must contain numeric data
* Field must exist in your custom fields data
* Values must be convertible to numbers
## Error Handling and Validation โ ๏ธ
### **Common Math Errors**
| Error Scenario | Cause | Solution |
| --------------------- | ------------------------------ | ------------------------------------- |
| **Division by zero** | `{mathutil:{Amount}/0}` | Use non-zero divisors |
| **Invalid operation** | `{mathutil:{Amount}%5}` | Use supported operators (+, -, \*, /) |
| **Non-numeric field** | Field contains text | Ensure field has numeric data |
| **Missing field** | Referenced field doesn't exist | Verify field name and data |
### **Common Date Errors**
| Error Scenario | Cause | Solution |
| ------------------------- | ----------------------------------------- | ---------------------------------- |
| **Missing today field** | `today` not provided | Vodex provides this automatically |
| **Missing raw\_today** | Required for end\_of\_week/end\_of\_month | Vodex provides this automatically |
| **Invalid timezone** | Wrong timezone format | Use valid timezone strings |
| **Invalid date format** | Can't parse source date | Use standard date formats |
| **Missing time unit** | `{dateutil:{today}+5}` | Include unit: `+5d` |
| **Invalid day number** | `{end_of_week:8}` | Use 0-7 only (0=Mon, 6=Sun) |
| **Missing date field** | `{date_range:{MissingField}-5}` | Ensure start date field exists |
| **Invalid number format** | `{date_range:{today}-abc}` | Use numeric values only |
| **Negative days** | `{date_range:{today}--5}` | Use positive numbers only |
| **Invalid day of month** | `{next_date:{today}+32}` | Use 1-31 only (valid day of month) |
| **Missing start date** | `{next_date:{MissingField}+5}` | Ensure start date field exists |
| **Invalid date format** | `{next_date:{InvalidDate}+5}` | Use valid date format |
### **Error Examples**
#### **Math Error - Division by Zero:**
```
โ Wrong: {mathutil:{AmountDue}/0}
โ
Correct: {mathutil:{AmountDue}/12}
```
#### **Date Error - Missing Unit:**
```
โ Wrong: {dateutil:{today}+30}
โ
Correct: {dateutil:{today}+30d}
```
#### **Field Missing Error:**
```
โ Wrong: {mathutil:{NonExistentField}+100}
โ
Correct: {mathutil:{AmountDue}+100}
```
#### **End of Week Error - Invalid Day Number:**
```
โ Wrong: {end_of_week:8}
โ
Correct: {end_of_week:0} (Monday) or {end_of_week:6} (Sunday)
```
#### **Missing Required Field Error:**
```
โ Wrong: Using {end_of_month} without time_zone in audience data
โ
Correct: Provide time_zone field in your audience upload
```
#### **Date Range Error - Missing Field:**
```
โ Wrong: {date_range:{NonExistentField}-5}
โ
Correct: {date_range:{StartDate}-5}
```
#### **Date Range Error - Invalid Number:**
```
โ Wrong: {date_range:{today}-abc}
โ
Correct: {date_range:{today}-5}
```
#### **Date Range Error - Negative Days:**
```
โ Wrong: {date_range:{today}--5}
โ
Correct: {date_range:{today}-5}
```
#### **Next Date Error - Invalid Day of Month:**
```
โ Wrong: {next_date:{today}+32}
โ
Correct: {next_date:{today}+5} (valid day 1-31)
```
#### **Next Date Error - Missing Field:**
```
โ Wrong: {next_date:{NonExistentField}+5}
โ
Correct: {next_date:{StartDate}+5}
```
## Best Practices for Computation Fields ๐
### **1. Always Validate Your Data**
* Ensure numeric fields contain valid numbers
* Verify date fields have proper date formats
* Test with sample data before going live
### **2. Use Descriptive Field Names**
```
โ
Good: {mathutil:{MonthlyPayment}*12}
โ Avoid: {mathutil:{MP}*12}
```
### **3. Handle Edge Cases**
* Plan for missing data scenarios
* Consider what happens with zero values
* Test with various data types
### **4. Keep Calculations Simple**
* Use straightforward operations when possible
* Break complex calculations into multiple fields
* Make calculations easy to understand and verify
### **5. Test Thoroughly**
* Test with different numeric values
* Try various date scenarios
* Verify timezone handling
## Real-World Use Cases ๐
### **Debt Collection Agency**
```
"Hello {FirstName}, your account {AccountNumber} shows an outstanding
balance of {AmountDue}. This amount has been past due since {DueDate},
which is now {dateutil:{DueDate}+{DaysPastDue}d} overdue.
We can offer you a settlement of {mathutil:{AmountDue}*0.8} if paid by
this Friday ({end_of_week:4}), or a payment plan of {mathutil:{AmountDue}/6}
per month for 6 months with first payment due by {end_of_month}."
```
### **Healthcare Appointment Reminders**
```
"Hi {PatientName}, this is a reminder for your appointment with
Dr. {DoctorName} on {AppointmentDate}. Please arrive 15 minutes early.
Your next follow-up should be scheduled for approximately
{dateutil:{AppointmentDate}+3m}. Your estimated co-pay is
{mathutil:{BaseCopay}+{AdditionalFees}}."
```
### **Subscription Services**
```
"Hello {CustomerName}, your {PlanName} subscription of {MonthlyRate}
per month will renew on {end_of_month}.
Your annual cost is {mathutil:{MonthlyRate}*12}, but you can save
{mathutil:{MonthlyRate}*2} by switching to our annual plan before
{end_of_week:4} (this Friday)."
```
### **Real Estate Follow-ups**
```
"Hi {ClientName}, it's been {dateutil:{LastContact}+{DaysSince}d} since
we last spoke about the {PropertyAddress} listing at {ListingPrice}.
Based on current market conditions, a competitive offer would be around
{mathutil:{ListingPrice}*0.95}. Would you like to schedule a viewing
for {dateutil:{today}+2d}?"
```
## Testing Your Computation Fields ๐งช
### **Testing Checklist**
* [ ] **Math operations work correctly** - Test all four operations (+, -, \*, /)
* [ ] **Date calculations are accurate** - Verify dateutil arithmetic
* [ ] **End of week calculations** - Test all day numbers (0-7)
* [ ] **End of month calculations** - Test across different months and leap years
* [ ] **Next date calculations** - Test with different days of month (1-31)
* [ ] **Date range calculations** - Test with different day ranges
* [ ] **Field references resolve** - Ensure all fields exist
* [ ] **Error handling works** - Test with invalid data
* [ ] **Timezone handling correct** - Test with different timezones
* [ ] **Conversation flows naturally** - Verify the computed values make sense
* [ ] **Combined utilities work** - Test mixing multiple utility types
### **Sample Test Data**
```json theme={null}
{
"FirstName": "John",
"AmountDue": "500.00",
"DueDate": "2024-03-30",
"MonthlyRate": "99.99",
"time_zone": "America/New_York"
}
```
### **Expected Results**
```
{mathutil:{AmountDue}+25} = 525.00
{mathutil:{MonthlyRate}*12} = 1199.88
{dateutil:{DueDate}+30d} = 2024-04-29
{dateutil:{today}+7d} = [7 days from current date]
{end_of_week:4} = [Next Friday's date]
{end_of_week:0} = [Next Monday's date]
{end_of_month} = [Last day of current month]
{next_date:{today}+5} = "05 Nov 2024, (Tuesday)" (if today is Nov 1) or "05 Dec 2024, (Thursday)" (if today is Nov 15)
{date_range:{StartDate}-5} = "1: 02 Jan 2024, Tuesday \n2: 03 Jan 2024, Wednesday \n3: 04 Jan 2024, Thursday \n4: 05 Jan 2024, Friday \n5: 06 Jan 2024, Saturday"
{date_range:{today}-6} = "1: 22 Oct 2025, Wednesday \n2: 23 Oct 2025, Thursday \n3: 24 Oct 2025, Friday \n4: 25 Oct 2025, Saturday \n5: 26 Oct 2025, Sunday \n6: 27 Oct 2025, Monday"
```
## Troubleshooting Guide ๐ง
### **Math Issues**
**Problem:** Field shows wrong calculation
* Check field contains numeric data
* Verify operation syntax
* Test with simple values first
**Problem:** Division returns unexpected results
* Ensure you're not dividing by zero
* Check for decimal vs integer division
* Verify the divisor value
### **Date Issues**
**Problem:** Date calculation fails
* Verify timezone is properly set
* Check source date format
* Ensure time unit is included
* Confirm raw\_today is available (for end\_of\_week/end\_of\_month)
**Problem:** Wrong date returned
* Confirm timezone is correct
* Check if daylight saving affects calculation
* Verify source date is accurate
### **End of Week Issues**
**Problem:** Wrong weekday calculated
* Verify day number (0=Monday, 6=Sunday)
* Check that raw\_today field exists
* Confirm timezone is set correctly
**Problem:** Returns today instead of next occurrence
* System always returns next occurrence, not current day
* If you need current day, use {today} instead
### **End of Month Issues**
**Problem:** Wrong last day calculated
* Verify raw\_today field exists
* Check timezone setting
* Confirm current month/year is correct
**Problem:** Leap year not handled
* System automatically handles leap years
* Verify raw\_today format is correct
### **Next Date Issues**
**Problem:** Wrong date calculated
* Verify start date field exists and contains valid date
* Check that day number is between 1-31
* Confirm timezone is set correctly
**Problem:** Invalid day of month error
* Use only valid days of the month (1-31)
* Avoid days that don't exist in certain months (e.g., Feb 30)
* System will automatically handle month boundaries
**Problem:** Missing field error
* Ensure the start date field exists in your custom fields
* Verify field name spelling and case sensitivity
**Problem:** Date parsing error
* Start date must be in a valid date format
* System handles various date formats automatically
* Check that raw\_today is available when using {today}
### **Date Range Issues**
**Problem:** Wrong end date calculated
* Verify start date field exists and contains valid date
* Check that number of days is a positive integer
* Confirm timezone is set correctly
**Problem:** Invalid number error
* Use only numeric values for days (5, 30, 90)
* Avoid non-numeric characters or negative numbers
**Problem:** Missing field error
* Ensure the start date field exists in your custom fields
* Verify field name spelling and case sensitivity
**Problem:** Date format issues
* Start date must be in a valid date format
* System handles various date formats automatically
## Next Steps ๐
Now that you understand computation custom fields:
1. **Start with simple calculations** - Begin with basic math operations
2. **Test thoroughly** - Verify calculations with sample data
3. **Add date computations** - Include timeline calculations with dateutil
4. **Use weekday and month-end features** - Leverage end\_of\_week and end\_of\_month
5. **Set monthly deadlines** - Use next\_date for recurring monthly dates
6. **Calculate time periods** - Use date\_range for duration analysis
7. **Combine all utilities** - Create sophisticated prompts with multiple computation types
8. **Monitor and optimize** - Track performance and accuracy
## Quick Reference Summary ๐
| Utility | Syntax | Example | Output Format |
| ---------------- | -------------------------------------- | -------------------------- | --------------------------------------------------------- |
| **Math** | `{mathutil:{Field}[op][value]}` | `{mathutil:{Amount}*1.05}` | Number |
| **Date** | `{dateutil:{Field}[+/-][count][unit]}` | `{dateutil:{today}+7d}` | Full datetime |
| **End of Week** | `{end_of_week:[0-7]}` | `{end_of_week:4}` | DD MMM YYYY |
| **End of Month** | `{end_of_month}` | `{end_of_month}` | DD MMM YYYY |
| **Next Date** | `{next_date:{start}+{day}}` | `{next_date:{today}+5}` | "05 Nov 2024, (Tuesday)" |
| **Date Range** | `{date_range:{start}-{days}}` | `{date_range:{today}-6}` | "1: 22 Oct 2025, Wednesday \n2: 23 Oct 2025, Thursday..." |
**Ready to supercharge your custom fields?** Computation fields unlock powerful dynamic capabilities that make your AI conversations more intelligent, accurate, and useful. Start implementing them today to create more sophisticated and helpful interactions.
***
**Need the basics first?** Check out our [Custom Fields Introduction](/custom-fields/introduction) and [Best Practices](/custom-fields/best-practices) guides before diving into computation features.
# ๐ท๏ธ Introduction to Custom Fields
Source: https://docs.vodex.ai/custom-fields/introduction
Learn how custom fields make your AI prompts dynamic and personalized by automatically inserting user-specific information
**What you'll learn:** How custom fields work as dynamic placeholders that automatically insert personalized information into your AI conversations.
## What Are Custom Fields?
Custom fields are like **smart placeholders** that you put inside your AI prompt. Think of them as empty boxes that automatically fill up with specific information about each user when the AI talks to them.
Instead of writing the same script for everyone, custom fields let you create **one prompt that works for thousands of users** by automatically including their personal details.
## How Custom Fields Work ๐
Here's the simple process:
1. **You write a prompt** with placeholders like `{FirstName}` and `{AccountNumber}`
2. **The system finds the user** and looks up their information
3. **Custom fields get filled** with real data from your database
4. **AI delivers personalized message** using the actual user information
It's like having a smart template that automatically personalizes itself for each person!
## Why Custom Fields Matter ๐ฏ
### **The Problem Without Custom Fields:**
* Writing separate scripts for every single user
* Manually updating information for each call
* Risk of errors when copying and pasting details
* Time-consuming and inefficient process
### **The Solution With Custom Fields:**
* One prompt works for everyone
* Information updates automatically
* No more copy-paste errors
* Fast, efficient, and accurate
## Basic Custom Field Examples
### **Personal Information Fields**
These are the most commonly used custom fields:
| Field | What It Does | Example Output |
| ------------- | ----------------------------- | ---------------- |
| `{FirstName}` | Inserts the user's first name | "Hello **John**" |
| `{LastName}` | Inserts the user's last name | "Mr. **Smith**" |
| `{FullName}` | Inserts complete name | "**John Smith**" |
### **Time and Date Fields (default)**
These provide dynamic time information:
| Field | What It Does | Example Output |
| ------------- | ---------------- | ------------------------------ |
| `{today}` | Current date | "Today is **March 15, 2024**" |
| `{time_zone}` | User's time zone | "Your time zone is **+05:00**" |
The field `today` should be left blank when trying to make a call either via Agent Call, Campaign Run, Or API. Vodex will fill it automatically using `time_zone` field
The `time_zone` field must be a valid time zone field. The time zone can be **Asia/Kolkata** or **+05:30**. If any other is provided, an unexpected error `Something went wrong` will be thrown
### **Account and Financial Fields**
These are essential for business conversations:
| Field | What It Does | Example Output |
| ----------------- | ------------------- | --------------------------- |
| `{AccountNumber}` | User's account ID | "Account **12345**" |
| `{AmountDue}` | Outstanding balance | "Balance of **\$500.00**" |
| `{DueDate}` | Payment deadline | "Due by **March 30, 2024**" |
## Real-World Example
### **Without Custom Fields (Static Script):**
```
"Hello, this is Alex from Stone & Saunders. I'm calling regarding your account.
Our records show an outstanding balance. Can we discuss this today?"
```
**Problems:** Generic, impersonal, no specific details
### **With Custom Fields (Dynamic Script):**
```
"Hello {FirstName}, this is Alex from Stone & Saunders. I'm calling regarding
your account number {AccountNumber}. Our records show an outstanding balance
of {AmountDue}. Can we discuss this today?"
```
**Benefits:** Personal, specific, professional, engaging
### **What the User Actually Hears:**
```
"Hello John, this is Alex from Stone & Saunders. I'm calling regarding
your account number 12345. Our records show an outstanding balance
of $500.00. Can we discuss this today?"
```
## How Custom Fields Make Conversations Better
### **1. Personalization**
* User feels recognized and valued
* Conversation feels natural and human
* Higher engagement and response rates
### **2. Accuracy**
* Information is always current
* No outdated or incorrect details
* Professional and trustworthy appearance
### **3. Efficiency**
* One prompt works for everyone
* No need to rewrite scripts
* Easy to maintain and update
### **4. Scalability**
* Handle thousands of users
* Add new users without changing prompts
* Consistent quality across all conversations
## Common Use Cases
### **Debt Collection**
```
"Hello {FirstName}, your outstanding balance of {AmountDue} on account
{AccountNumber} is due by {DueDate}."
```
### **Appointment Reminders**
```
"Hi {FirstName}, this is a reminder about your appointment on {AppointmentDate}
at {AppointmentTime} with Dr. {DoctorName}."
```
### **Customer Service**
```
"Thank you for calling, {FirstName}. I can see you're calling about
order {OrderNumber} placed on {OrderDate}."
```
### **Sales and Marketing**
```
"Hello {FirstName}, I noticed you were interested in our {ProductName}
service. Based on your location in {City}, I think this would be perfect for you."
```
## Important Rules to Remember
### **๐จ Critical: No Spaces in Field Names**
Custom fields are **space-sensitive** and must follow strict naming rules:
| โ
**Correct** | โ **Wrong** | Why It Matters |
| ----------------- | ------------------ | --------------------------- |
| `{FirstName}` | `{First Name}` | Spaces cause errors |
| `{AccountNumber}` | `{Account Number}` | System can't find the field |
| `{AmountDue}` | `{Amount Due}` | Data retrieval fails |
### **โ
Use Underscores Instead of Spaces**
When you need multiple words, connect them with underscores:
```
{Account_Number} โ
Correct
{Payment_Amount} โ
Correct
{Due_Date} โ
Correct
```
## Getting Started with Custom Fields
### **Step 1: Identify Your Data**
* What information do you have about users?
* What details would make conversations more personal?
* What data changes frequently?
### **Step 2: Choose Field Names**
* Use clear, descriptive names
* Always use underscores instead of spaces
* Keep names consistent across your system
### **Step 3: Test Your Fields**
* Verify that data populates correctly
* Check for any naming errors
* Ensure the conversation flows naturally
## Next Steps
Now that you understand the basics of custom fields:
1. **Review your current prompts** - Identify where personalization would help
2. **List your available data** - What user information can you access?
3. **Start with simple fields** - Begin with `{FirstName}` and `{today}`
4. **Test and expand** - Add more fields as you become comfortable
**Ready to personalize your AI conversations?** Custom fields are the key to making your prompts dynamic, engaging, and professional. Start implementing them today to see immediate improvements in user engagement and conversation quality.
***
**Need help with best practices?** Check out our [Custom Fields Best Practices](/custom-fields/best-practices) guide to learn how to use custom fields effectively and avoid common mistakes.
# Why Choose Enterprise?
Source: https://docs.vodex.ai/enterprise/overview
Advanced enterprise-grade capabilities for large-scale AI voice operations with enhanced control, monitoring, and cutting-edge technology access
**Unlock Enterprise Power:** Advanced features designed for large-scale operations, enhanced control, real-time monitoring, and priority access to the latest AI innovations.
Transform your voice operations with enterprise-grade capabilities that provide unparalleled control, monitoring, and access to cutting-edge AI technology. Our Enterprise plan is designed for organizations that demand the highest levels of performance, reliability, and innovation.
***
## ๐ Why Choose Enterprise?
**Built for Enterprise Success**
Enterprise features are specifically designed for organizations running high-volume campaigns, managing complex compliance requirements, and requiring advanced operational control. Get the tools you need to scale your voice operations while maintaining complete oversight and control.
***
## ๐ Exclusive Enterprise Features
### ๐ Intelligent DND Management
**Smart Campaign Scheduling**
**What it does:**
* Automatically shuts down and turns on gateways based on Do Not Disturb (DND) hours
* Prevents calls during restricted time periods
* Ensures compliance with local calling regulations
* Customizable DND schedules per campaign or region
**Business Impact:**
* **Compliance Assurance:** Never accidentally call during restricted hours
* **Brand Protection:** Avoid customer complaints from inappropriate timing
* **Operational Efficiency:** Automated scheduling reduces manual oversight
* **Global Operations:** Set different DND hours for different time zones
**How It Works:**
**Configure Restrictions**
* Define specific hours when calls should not be made
* Set different schedules for weekdays, weekends, and holidays
* Configure region-specific restrictions for global campaigns
**Intelligent Control**
* System automatically disables gateways during DND periods
* Campaigns pause automatically and resume when appropriate
* Real-time monitoring ensures compliance
**Seamless Operations**
* Gateways automatically reactivate when DND period ends
* No manual intervention required
***
### ๐ Real-Time Performance Monitoring
**Live Campaign Intelligence**
**What you get:**
* Automated hourly performance reports delivered to Slack
* Real-time campaign metrics and KPIs
* Instant alerts for performance anomalies
* Customizable reporting dashboards
**Key Metrics Included:**
* **Call Volume:** Completed, in-progress, and queued calls
* **Success Rates:** Connection rates, conversion metrics
* **Performance Trends:** Hour-over-hour comparisons
* **Issue Alerts:** Immediate notification of problems
**Sample Slack Update:**
```
๐ Campaign Performance Update - 2:00 PM
๐ Calls This Hour: 1,247 (โ12% vs last hour)
โ
Success Rate: 87.3% (โ2.1%)
๐ฏ Conversions: 156 (12.5% conversion rate)
โก Avg Call Duration: 3m 42s
๐ฅ Top Performing Campaign: "Q4 Sales Outreach"
โ ๏ธ Alert: Gateway latency increased by 15ms
```
***
### ๐ Emergency Campaign Control
**Instant Crisis Management**
**What it does:**
* Immediately stops all active calls across all campaigns
* Prevents new calls from being initiated
* Provides instant control during emergencies
* Detailed logging of shutdown events
**When to Use:**
* **System Issues:** Technical problems affecting call quality
* **Compliance Concerns:** Immediate regulatory compliance needs
* **Business Emergencies:** Unexpected business situations
* **Quality Control:** Stopping campaigns with identified issues
**Emergency Control Dashboard:**
**Instant Response Capabilities**
* **Stop All Calls:** Terminate every active call immediately
* **Pause Campaigns:** Suspend all campaigns without data loss
* **Gateway Shutdown:** Disable all calling gateways instantly
* **Alert Team:** Automatic notifications to key stakeholders
**Smart Restart Process**
* **Selective Resume:** Choose which campaigns to restart
* **Quality Checks:** Verify system health before resuming
* **Gradual Ramp-up:** Slowly increase call volume to ensure stability
* **Incident Reporting:** Detailed logs for post-incident analysis
***
### ๐ค Cutting-Edge AI Access
**Stay Ahead of the Curve**
**What you get:**
* Access to newest AI models within hours of release
* Priority testing and feedback opportunities
* Beta access to experimental features
* Dedicated AI research team support
**Recent Model Additions:**
* **GPT-5 Series:** Next-generation conversational AI
* **Claude Sonnet:** Advanced reasoning capabilities
* **Vodex Spark:** Our most advanced proprietary model
* **Custom Fine-tuned Models:** Industry-specific optimizations
**AI Innovation Pipeline:**
**Immediate Access**
* New models available within 2-4 hours of public release
* Comprehensive testing and validation
* Performance benchmarks and recommendations
* Migration assistance from existing models
**Exclusive Preview Access**
* Early access to experimental capabilities
* Direct feedback channel to development team
* Influence future feature development
* Competitive advantage through early adoption
**Tailored AI Solutions**
* Industry-specific model fine-tuning
* Custom training on your data
* Specialized conversation flows
* Dedicated model optimization
***
## ๐ผ Enterprise Value Proposition
### ๐ฏ **Operational Excellence**
**Comprehensive Protection**
* Automated compliance management
* Emergency response capabilities
* Real-time monitoring and alerts
* Detailed audit trails
**Maximum Efficiency**
* Hourly performance insights
* Proactive issue identification
* Automated optimization recommendations
* Continuous improvement tracking
**Competitive Advantage**
* First access to breakthrough AI models
* Beta testing opportunities
* Custom feature development
* Technology roadmap influence
**Complete Command**
* Granular campaign management
* Intelligent scheduling automation
* Emergency response systems
* Custom workflow integration
***
***
## ๐ Enterprise Success Stories
### **Fortune 500 Financial Services**
**Challenge:** Managing 50,000+ daily collection calls across multiple time zones while ensuring regulatory compliance.
**Solution:** Enterprise DND management + hourly monitoring + emergency controls
**Results:**
* **100% compliance** with calling hour regulations
* **35% reduction** in operational overhead
* **Zero incidents** of inappropriate timing violations
* **\$2.3M annual savings** in compliance and operational costs
### **Healthcare Network**
**Challenge:** Coordinating appointment reminders for 200+ locations while maintaining HIPAA compliance.
**Solution:** Latest AI models + intelligent scheduling + real-time monitoring
**Results:**
* **45% improvement** in appointment show rates
* **60% reduction** in manual scheduling overhead
* **99.9% uptime** with emergency controls
* **\$5.1M annual value** from improved patient engagement
***
## ๐ Getting Started with Enterprise
### **Implementation Process**
**Needs Assessment**
* Detailed requirements analysis
* Custom feature configuration
* Integration planning
* Success metrics definition
**Tailored Configuration**
* DND schedule configuration
* Slack integration setup
* Emergency control protocols
* AI model selection and testing
**Knowledge Transfer**
* Advanced feature training
* Best practices workshops
* Emergency procedure training
* Ongoing support setup
**Launch Excellence**
* Dedicated launch support
* Real-time monitoring
* Performance optimization
* Success measurement
***
## ๐ Enterprise Pricing & Support
### **What's Included**
**Complete Enterprise Suite**
* Intelligent DND management with custom scheduling
* Hourly Slack performance updates
* One-click emergency shutdown capabilities
* Priority access to latest AI models (within hours)
* Custom model fine-tuning options
* Advanced compliance tools
**Dedicated Enterprise Support**
* Dedicated customer success manager
* 24/7 priority technical support
* Custom integration assistance
* Quarterly business reviews
* Direct access to engineering team
* Custom feature development consideration
**Enterprise Intelligence**
* Custom reporting dashboards
* Advanced performance analytics
* Predictive insights and recommendations
* Custom KPI tracking
* Executive-level reporting
* ROI measurement and optimization
***
## ๐ Ready to Transform Your Operations?
**Contact Our Enterprise Team**
Ready to scale your voice operations with enterprise-grade capabilities? Our team is standing by to design a custom solution that meets your specific needs and drives measurable business results.
**Get Started:** [support@vodex.ai](mailto:support@vodex.ai)
**Include in your email:**
* "Enterprise Plan Inquiry" in the subject line
* Your current call volume and growth projections
* Specific compliance or operational requirements
* Timeline for implementation
**Limited Availability:** Enterprise features require dedicated infrastructure and support resources. Contact us early to ensure availability for your desired launch timeline.
***
## ๐ฏ Next Steps
After contacting our enterprise team:
1. **Discovery Call** - Detailed needs assessment and feature demonstration
2. **Custom Proposal** - Tailored solution with pricing and timeline
3. **Pilot Program** - Limited trial to validate value and fit
4. **Full Implementation** - Complete rollout with dedicated support
5. **Ongoing Optimization** - Continuous improvement and feature updates
**Ready for Enterprise Excellence?** Transform your voice operations with advanced automation, real-time intelligence, and cutting-edge AI technology. Contact our enterprise team today to unlock the full potential of AI-powered voice communications.
***
**Questions about Enterprise features?** Our enterprise specialists are available to discuss your specific requirements and demonstrate how these advanced capabilities can transform your voice operations.
# โ General FAQs - Frequently Asked Questions
Source: https://docs.vodex.ai/faqs/general-faqs
Find answers to common questions about Vodex.ai platform, features, pricing, and implementation
**What you'll find:** Comprehensive answers to the most frequently asked questions about Vodex.ai, organized by category for easy navigation.
## Overview
This page contains answers to the most common questions about Vodex.ai. If you can't find what you're looking for here, please check our other documentation sections or contact our support team.
***
## General Questions
### **What is Vodex.ai?**
Vodex.ai is an AI-powered platform that helps businesses automate customer interactions using advanced voice and conversational intelligence.
### **How does Vodex.ai work?**
It uses natural language processing (NLP) and AI models to understand customer queries and provide personalized, human-like responses across multiple channels.
### **Who can benefit from using Vodex.ai?**
Any business that manages customer interactionsโsuch as call centers, e-commerce, finance, healthcare, and SaaS companiesโcan benefit.
### **What industries does Vodex.ai serve?**
Vodex.ai serves industries including retail, e-commerce, healthcare, finance, education, and telecom.
### **Is Vodex.ai suitable for small businesses as well as enterprises?**
Yes, Vodex.ai is scalable and works for startups, SMEs, and large enterprises alike.
***
## Product & Features
### **What makes Vodex.ai different from other AI solutions?**
Vodex.ai combines powerful voice AI with seamless integrations, delivering natural conversations and easy setup.
### **Does Vodex.ai use voice text or both for customer interactions?**
It supports both voice and text-based interactions, depending on business needs.
### **Can Vodex.ai integrate with my existing CRM or business tools?**
Yes, Vodex.ai integrates with popular CRMs, ticketing systems, and communication platforms.
### **How customizable are the AI responses?**
Responses are fully customizable to match your brand tone, workflows, and customer requirements.
### **Does Vodex.ai support multiple languages?**
Yes, Vodex.ai supports multiple languages for global customer engagement.
***
## Data & Security
### **How secure is the data processed by Vodex.ai?**
All data is encrypted in transit and at rest, ensuring enterprise-grade security.
### **Does Vodex.ai comply with GDPR/CCPA and other data regulations?**
Yes, Vodex.ai complies with ISO, SOC2, and other global data protection standards.
### **How does Vodex.ai handle customer privacy?**
Customer data is anonymized and only used to improve interactions as per compliance rules.
### **Where is the data stored?**
Data is stored in secure cloud servers with region-specific options.
***
## Pricing & Plans
### **How much does Vodex.ai cost?**
Pricing depends on usage and plan type. Flexible packages are available.
### **Do you offer a free trial or demo?**
Yes, Vodex.ai offers free demos and trial accounts for new customers.
### **Are there different pricing plans based on usage?**
Yes, plans vary based on call volume, features, and support levels.
### **Can I scale my plan as my business grows?**
Absolutely, Vodex.ai is built to scale with your growth.
***
## Implementation & Support
### **Do you provide onboarding and training?**
Yes, our team provides onboarding, training sessions, and documentation.
### **What kind of customer support is available?**
Vodex.ai offers email, chat, and dedicated account support for enterprise clients.
### **How long does it take to see results after implementation?**
Most customers see value within the first few weeks of deployment.
***
## Technical Questions
### **What AI technologies power Vodex.ai?**
Vodex.ai uses NLP, speech recognition, and machine learning models for conversational AI.
### **Can Vodex.ai handle large volumes of customer interactions?**
Yes, Vodex.ai is designed to scale and handle thousands of concurrent interactions.
### **Does Vodex.ai integrate with WhatsApp, SMS, or email?**
Yes, Vodex.ai supports integrations with WhatsApp, SMS, email, and other channels.
### **Can Vodex.ai replace my call center or work alongside it?**
It can complement existing call centers or fully automate certain functions depending on your needs.
***
## Company Information & Future
### **Where is Vodex.ai based?**
Vodex.ai is headquartered in Bangalore, with clients across the globe.
### **Who are the founders of Vodex.ai?**
Vodex.ai was founded by Anshul Srivastava and Kumar Saurav.
### **What is the long-term vision of Vodex.ai?**
Our mission is to redefine customer communication by making AI-driven voice interactions seamless and human-like.
### **How do I get started with Vodex.ai?**
Simply book a demo or sign up through our website to begin.
***
## Quick Reference Guide
**New to Vodex.ai?**
* Book a free demo
* Sign up for trial account
* Check our quickstart guide
**Support Options**
* Email support
* Live chat
* Documentation
* Training sessions
***
## Still Have Questions?
If you couldn't find the answer you're looking for:
### **๐ Check Other Documentation**
* [Getting Started Guide](/introduction) - Complete setup instructions
* [Campaign Guide](/campaign/guide) - Learn about campaign management
* [Agent Configuration](/agents/prompt) - AI agent setup guide
* [Call Settings](/call-settings/overview) - Technical configuration
### **๐ Contact Support**
* **Email:** [support@vodex.ai](mailto:support@vodex.ai)
* **Response Time:** Within 24 hours during business days
* **Include:** Clear description of your question and any relevant details
### **๐ Search Documentation**
Use the search function in our documentation to find specific topics or keywords.
***
## Related FAQs
Learn about SIP Trunk integration requirements and setup for Vodex.ai
Find solutions to common problems and issues
**Remember:** This FAQ page is regularly updated. If you have a question that should be added here, please let our support team know!
# Requirements for SIP Trunk Integrations
Source: https://docs.vodex.ai/faqs/sip-trunk-requirements
Complete guide to SIP Trunk integration requirements and setup for Vodex.ai
**๐ฐ Paid Plan Feature:** SIP Trunk integration is available on paid plans only. Free tier users can integrate Twilio SIP Trunks as an alternative.
## Overview
SIP (Session Initiation Protocol) Trunks allow you to connect your existing telephony infrastructure with Vodex.ai for seamless call routing and management. This guide outlines the technical requirements and information needed for successful SIP Trunk integration.
***
## Required Information
To integrate a SIP Trunk with Vodex.ai, you'll need to provide the following technical details:
### 1. Connection Details
**IP Address:** Static IP address of your SIP Trunk provider
**FQDN:** Fully Qualified Domain Name (e.g., sip.yourprovider.com)
*Example: `203.0.113.10` or `trunk.siprovider.com`*
**SIP Port:** Usually 5060 (UDP) or 5061 (TLS)
**RTP Port Range:** For media transmission
*Example: `5060` or `5061`*
### 2. Authentication (If Required)
Authentication is only required if your SIP Trunk is not configured for peer-to-peer connection.
| Field | Description | Example |
| ------------ | ------------------------------- | ------------------ |
| **Username** | SIP authentication username | `vodex_user_123` |
| **Password** | SIP authentication password | `SecurePass123!` |
| **Realm** | Authentication realm (optional) | `sip.provider.com` |
### 3. Caller Line Identification (CLI)
CLI management allows Vodex to handle caller ID presentation and routing.
**CLI Requirements:**
* **Format:** E.164 format preferred (+1234567890)
* **Validation:** Must be authorized by your SIP provider
* **Presentation:** Configure how caller ID appears to recipients
### 4. DID Configuration (Optional)
#### DID Range
Specify the range of Direct Inward Dialing numbers available:
```
Start DID: +1234567000
End DID: +1234567999
Total DIDs: 1000 numbers
```
#### DID Prefix
Configure number formatting and routing:
```
Country Code: +1
Area Code: 234
Prefix: 567
Format: +1234567XXXX
```
***
## SIP Trunk Types
### Peer-to-Peer Connection
* **Authentication:** Not required
* **Security:** IP-based authentication
* **Configuration:** Simpler setup
* **Use Case:** Direct carrier connections
### Registered Connection
* **Authentication:** Username/Password required
* **Security:** Credential-based authentication
* **Configuration:** More secure
* **Use Case:** Third-party SIP providers
***
## Technical Requirements
### Network Configuration
Open required ports for SIP signaling and RTP media:
* **SIP Signaling:** 5060 (UDP) or 5061 (TLS)
* **RTP Media:** 10000-20000 (UDP range)
Configure NAT traversal if your SIP Trunk is behind NAT:
* Enable STUN/TURN servers if needed
* Configure proper port forwarding
Implement QoS policies for optimal call quality:
* Prioritize SIP and RTP traffic
* Ensure sufficient bandwidth allocation
### Codec Support
Vodex.ai supports the following audio codecs:
| Codec | Bitrate | Quality | Bandwidth Usage |
| --------------------- | ------- | -------- | --------------- |
| **G.711 (PCMU/PCMA)** | 64 kbps | High | \~87 kbps |
| **G.729** | 8 kbps | Good | \~31 kbps |
| **G.722** | 64 kbps | HD Audio | \~87 kbps |
***
## Integration Checklist
Before submitting your SIP Trunk integration request, ensure you have:
* [ ] **Connection Details**
* [ ] IP Address or FQDN
* [ ] Port configuration
* [ ] Protocol specification (UDP/TCP/TLS)
* [ ] **Authentication Information** (if required)
* [ ] Username and password
* [ ] Authentication realm
* [ ] **CLI Configuration**
* [ ] Authorized caller ID numbers
* [ ] CLI presentation preferences
* [ ] **DID Information** (if applicable)
* [ ] DID range specification
* [ ] Number formatting preferences
* [ ] Routing requirements
* [ ] **Network Preparation**
* [ ] Firewall rules configured
* [ ] NAT traversal setup (if needed)
* [ ] QoS policies implemented
***
## Common Configuration Examples
### Example 1: Basic Peer-to-Peer Setup
```yaml theme={null}
Connection Type: Peer-to-Peer
SIP Server: 203.0.113.10
Port: 5060
Protocol: UDP
Authentication: None
CLI: +1234567890
```
### Example 2: Registered SIP Trunk
```yaml theme={null}
Connection Type: Registered
SIP Server: sip.provider.com
Port: 5061
Protocol: TLS
Username: vodex_account
Password: SecurePassword123
CLI Range: +1234567000 to +1234567999
DID Prefix: +1234567
```
### Example 3: Enterprise Setup
```yaml theme={null}
Connection Type: Registered
SIP Server: enterprise.siptrunk.com
Port: 5060
Protocol: UDP
Username: enterprise_user
Password: EnterprisePass456
CLI Management: Vodex Managed
DID Range: +1555000000 to +1555000099
DID Prefix: +1555000
Codec Preference: G.711, G.729
```
***
## Free Tier Alternative: Twilio Integration
Free tier users can integrate Twilio SIP Trunks for telephony functionality.
For free tier users, consider using Twilio SIP Trunks:
1. **Create Twilio Account:** Sign up at [twilio.com](https://twilio.com)
2. **Configure SIP Trunk:** Set up SIP trunk in Twilio console
3. **Get Credentials:** Obtain SIP domain and authentication details
4. **Integrate with Vodex:** Use Twilio SIP credentials in Vodex configuration
**Twilio SIP Configuration Example:**
```yaml theme={null}
SIP Domain: yourapp.sip.twilio.com
Username: Your Twilio Account SID
Password: Your Twilio Auth Token
```
***
## Support and Next Steps
### Getting Help
If you need assistance with SIP Trunk integration:
* **Technical Support:** [support@vodex.ai](mailto:support@vodex.ai)
* **Documentation:** Review our [Call Settings Guide](/call-settings/overview)
* **Live Chat:** Available in your Vodex dashboard
### Integration Process
1. **Gather Requirements:** Complete the checklist above
2. **Submit Request:** Contact support with your SIP Trunk details
3. **Testing Phase:** We'll configure and test the connection
4. **Go Live:** Activate your SIP Trunk integration
**Pro Tip:** Have your network administrator available during the integration process to assist with any firewall or network configuration changes that may be needed.
# ๐ GHL Overview and Steps
Source: https://docs.vodex.ai/ghl/integration
Complete guide to integrating Vodex.ai with Go High Level for seamless CRM automation and appointment management
**What you'll learn:** How to integrate Vodex.ai with Go High Level (GHL) for automated calling, CRM updates, and appointment management directly from your GHL workflows.
Vodex.ai provides seamless out-of-the-box integration with Go High Level for premium clients, enabling powerful automation workflows that combine GHL's CRM capabilities with Vodex's AI-powered calling technology.
***
## ๐ Integration Capabilities
### What GHL Integration Supports
**GHL โ Vodex Calls**
* Trigger AI calls directly from GHL workflows
* Pass contact data and custom fields automatically
* Initiate calls based on GHL triggers and conditions
* Seamless workflow integration
**Vodex โ GHL Data Sync**
* Automatically update contact notes after calls
* Add tags based on call outcomes
* Sync call results and insights back to GHL
* Real-time CRM data updates
**Enterprise Appointment Features**
* Book appointments directly in GHL calendars
* Cancel existing appointments via AI
* Reschedule appointments automatically
* Sync appointment data between systems
**Enterprise Only:** Appointment booking, canceling, and rescheduling features are available exclusively for Enterprise plan customers.
***
## ๐ง Setup Process
### Step 1: Install Vodex App from GHL Marketplace
The Vodex app is available directly in the Go High Level marketplace for easy installation.
**Prepare Your Accounts**
* Login to [app.vodex.ai](https://app.vodex.ai) in one browser tab
* Login to your Go High Level account in another tab
* Ensure you're using the same browser for both logins
**Create Connection**
* In a new tab (same browser), navigate to: `https://app.vodex.ai/account/ghl-integration`
* Click **"Create Connection"** button
* This will initiate the OAuth process with GHL
**Authorize Integration**
* OAuth flow will automatically redirect to GHL
* Authorize Vodex app permissions in GHL
* GHL app will be installed in your GHL account
* Return to Vodex dashboard
**Verify Integration**
* app.vodex.ai will display "Integration Successfully" popup
* Vodex app should now appear in your GHL workflows
* Test connection by creating a simple workflow
**Browser Requirement:** Use the same browser for both Vodex and GHL logins to ensure proper OAuth authentication.
***
## ๐ Making Calls via GHL Workflows
### Adding Vodex Action to Workflows
**Access GHL Workflows**
* Navigate to your GHL workflow builder
* Create a new workflow or edit an existing one
* Choose your trigger conditions
**Insert Vodex Action**
* In the workflow builder, search for "Vodex"
* Insert the Vodex action where you want calls to be triggered
* The action will appear as a configurable step
**Set Up Call Parameters**
* Open the Vodex action configuration
* Fill in all required fields (detailed below)
* Test the configuration before going live
### Required Configuration Fields
**Core Configuration**
| Field | Description | Example |
| ------------- | ------------------------------------ | ---------------------------- |
| **PROJECT** | Select the Vodex project to use | "Sales Outreach Q4" |
| **CALENDAR** | GHL calendar for appointment booking | "Sales Team Calendar" |
| **TIME ZONE** | Contact's time zone | `+05:30` or `America/Denver` |
**Time Zone Format:** Use the same format as described in [Custom Fields documentation](/custom-fields/introduction) - either UTC offset (`+05:30`) or timezone names (`America/Denver`).
**Additional Data Fields**
**CUSTOMFIELD1 through CUSTOMFIELD5**
Use these fields for custom data beyond the standard FirstName, LastName, and PhoneNum:
```
CUSTOMFIELD1: {{contact.company}}
CUSTOMFIELD2: {{contact.source}}
CUSTOMFIELD3: {{contact.lead_score}}
CUSTOMFIELD4: {{contact.last_interaction}}
CUSTOMFIELD5: {{contact.interest_level}}
```
**GHL Variables:** Use GHL's contact variables to dynamically populate custom fields with contact-specific data.
**QUESTIONS Field**
Configure AI insights using the special GHL format instead of JSON:
**Format:** `question#key#type;`
**Examples:**
```
Is the user not interested in taking loans?#not_interested#boolean;
What is the name that user said?#first_name#string;
How many days until they need the service?#timeline_days#number;
What specific requirements did they mention?#requirements#string;
```
**Field Types:**
* `string` - Text responses
* `number` - Numeric values
* `boolean` - True/false responses
**CALL RESPONSE TAG**
Set a prefix for automatic tagging based on call outcomes:
**Example:** If prefix is `vodex_auto`, tags will be:
* `vodex_auto_voicemail` - Voicemail detected
* `vodex_auto_call_failed` - Call failed to connect
* `vodex_auto_call_ended` - Call completed successfully
* `vodex_auto_transferred` - Call transferred to human
**Usage:**
```
CALL RESPONSE TAG: vodex_auto
```
**CONTACT\_ID Field**
**Required Value:** `{{contact.id}}`
```
CONTACT_ID: {{contact.id}}
```
**Hard Code Required:** Always use exactly `{{contact.id}}` - this GHL variable ensures proper contact linking.
***
## ๐
Enterprise Appointment Management
### Booking Appointments via AI
**Enterprise Feature:** Appointment booking, canceling, and rescheduling are available exclusively for Enterprise plan customers.
#### Using the (appointment) Tag
To enable appointment booking, use the special `(appointment)` tag in your AI prompt:
```text Example Prompt theme={null}
"Hello {FirstName}, I'm calling to schedule your consultation.
If the user gives you a specific time and date to book an appointment, then please say that you are booking an appointment and add (appointment) to your response. The backend will book and confirm the appointment for you.
What day and time works best for you this week?"
```
```text Strict Booking Prompt theme={null}
"Hello {FirstName}, I'm calling to schedule your consultation.
If the user gives you a specific time and date, say 'I'm booking your appointment now' and add (appointment) to your response.
You please do not tell anything by yourself, the backend will book the appointment, you just say that you are booking."
```
**Strict Mode:** For better control, use the strict version that prevents the AI from making promises about appointment details. The backend handles all booking confirmations.
#### Available Appointment Slots
Use the `(slots)` tag to have the AI read available appointment slots:
```text theme={null}
"Let me check our available slots for you. (slots)
Which of these times works best for you?"
```
The system will automatically insert available slots from your GHL calendar.
***
## โ๏ธ Appointment Configuration
### Customizing Appointment Messages
**Static Configuration:** The fields in the appointment-config page are static. Bots cannot dynamically say "Congratulations, your appointment has been booked on \[date] at \[time]" - all appointment messaging is pre-configured.
#### Accessing Appointment Config
To customize how the AI communicates appointment information:
1. Navigate to: `https://app.vodex.ai/account/project//appointment-config`
2. Replace `` with your actual project ID
3. Configure static messages for different appointment scenarios
#### Configuration Options
**Static Message Templates**
* Booking confirmation message
* Cancellation confirmation message
* Rescheduling confirmation message
* Slot availability message
* Error handling messages
**Available Slots Format**
* How slots are read to customers
* Time format preferences
* Date format preferences
* Slot grouping options
**Fallback Messages**
* No slots available message
* Booking failure message
* Calendar conflict message
* System error message
***
## ๐ Workflow Examples
### Basic Lead Qualification Workflow
```yaml GHL Workflow Configuration theme={null}
Trigger: New Lead Added
โ
Vodex Action:
PROJECT: "Lead Qualification"
CALENDAR: "Sales Team"
TIME_ZONE: "{{contact.timezone}}"
CUSTOMFIELD1: "{{contact.source}}"
CUSTOMFIELD2: "{{contact.budget}}"
QUESTIONS: "Is the lead interested in our service?#interested#boolean;What is their budget range?#budget#string;"
CALL_RESPONSE_TAG: "lead_qual"
CONTACT_ID: "{{contact.id}}"
```
```text AI Prompt Example theme={null}
"Hi {{FirstName}}, this is Sarah from ABC Company. I see you expressed interest in our services through {{source}}.
I'd love to learn more about your needs and see if we're a good fit.
What specific challenges are you looking to solve with our service?
[Continue conversation based on responses...]
If they're interested and want to schedule a consultation, say: 'Let me book a consultation for you' and add (appointment) to your response."
```
### Appointment Reminder Workflow
```yaml GHL Workflow Configuration theme={null}
Trigger: 24 Hours Before Appointment
โ
Vodex Action:
PROJECT: "Appointment Reminders"
CALENDAR: "Main Calendar"
TIME_ZONE: "{{contact.timezone}}"
QUESTIONS: "Will the customer attend the appointment?#will_attend#boolean;Do they need to reschedule?#needs_reschedule#boolean;"
CALL_RESPONSE_TAG: "reminder"
CONTACT_ID: "{{contact.id}}"
```
```text AI Prompt Example theme={null}
"Hi {{FirstName}}, this is a reminder about your appointment tomorrow at {{appointment.time}}.
Will you be able to make it at the scheduled time?
If they need to reschedule: 'Let me help you reschedule' and add (appointment) to your response.
If they want to cancel: 'I'll cancel that for you' and add (appointment) to your response."
```
***
## ๐ Integration Benefits
### Automated Workflow Advantages
**Complete Integration**
* Trigger calls from any GHL workflow
* Automatic data sync between platforms
* No manual intervention required
* Real-time updates and responses
**Rich Data Collection**
* Automatic note updates after calls
* Intelligent tagging based on outcomes
* Insights data synced to contact records
* Complete conversation history
**Enterprise Appointments**
* AI-powered appointment booking
* Automatic calendar management
* Conflict resolution and rescheduling
* Confirmation and reminder automation
**Streamlined Operations**
* Reduced manual calling tasks
* Consistent follow-up processes
* Scalable lead management
* Improved conversion rates
***
## ๐ ๏ธ Troubleshooting
### Common Integration Issues
| Issue | Cause | Solution |
| ---------------------------- | ------------------------------ | -------------------------------------- |
| **OAuth Failed** | Different browsers used | Use same browser for both platforms |
| **App Not Found** | Integration not completed | Retry integration process |
| **Calls Not Triggering** | Incorrect field configuration | Verify all required fields |
| **Appointments Not Booking** | Enterprise feature not enabled | Contact support for Enterprise upgrade |
### Best Practices
**Setup Best Practices**
* Test workflows with small contact lists first
* Use descriptive project names for easy identification
* Set up proper time zones for accurate scheduling
* Configure meaningful tag prefixes for organization
**AI Prompt Guidelines**
* Keep appointment booking prompts simple and direct
* Use the strict booking approach for better control
* Test prompts with various customer responses
* Include clear fallback options for edge cases
**Performance Tracking**
* Monitor call success rates through GHL tags
* Track appointment booking conversion rates
* Review insights data for optimization opportunities
* Set up alerts for failed integrations
***
## ๐ Getting Started
### Quick Setup Checklist
**Before You Begin**
* [ ] Active Vodex.ai premium account
* [ ] Go High Level account with workflow access
* [ ] Project created in Vodex dashboard
* [ ] GHL calendar set up for appointments (if using Enterprise features)
**Connect the Platforms**
* [ ] Complete OAuth integration process
* [ ] Verify "Integration Successfully" message
* [ ] Test Vodex action appears in GHL workflows
**Create Test Workflow**
* [ ] Set up simple lead qualification workflow
* [ ] Configure all required Vodex action fields
* [ ] Test with a small contact list
* [ ] Verify call triggers and data sync
**Refine and Scale**
* [ ] Review call outcomes and insights
* [ ] Optimize AI prompts based on results
* [ ] Scale to larger contact lists
* [ ] Set up additional workflows as needed
***
## ๐ก Next Steps
After setting up your GHL integration:
1. **Start Small** - Test with a limited contact list first
2. **Monitor Results** - Track call outcomes and appointment bookings
3. **Optimize Prompts** - Refine AI instructions based on performance
4. **Scale Gradually** - Expand to larger workflows once optimized
5. **Explore Enterprise** - Consider Enterprise features for advanced appointment management
**Ready to automate your GHL workflows?** The Vodex-GHL integration provides powerful automation capabilities that can transform your lead management and customer engagement processes.
***
**Need help with the integration?** Contact our support team at [support@vodex.ai](mailto:support@vodex.ai) with "GHL Integration Support" in the subject line for specialized assistance.
# ๐ Generic SIP Provider Configuration
Source: https://docs.vodex.ai/inbound/generic-sip-providers
Configure SIP Trunks with various providers (Vonage, Bandwidth, etc.) for Vodex AI integration
**Universal Guide:** This guide covers SIP Trunk configuration for various providers including Vonage, Bandwidth, Flowroute, and other SIP-compatible services to integrate with Vodex AI.
Configure SIP Trunks with any SIP provider to route incoming calls to your Vodex AI agents. While each provider has a slightly different interface, the core configuration principles remain the same.
***
## ๐ฏ Universal SIP Configuration
### Core Vodex Settings
**These settings apply to ALL SIP providers:**
| Setting | Value | Description |
| ------------------- | --------------- | ------------------------------ |
| **SIP Server/Host** | `34.27.110.155` | Vodex AI SIP Gateway |
| **Port** | `5080` | SIP Communication Port |
| **Transport** | `TCP` | Recommended transport protocol |
| **Authentication** | None/IP-based | No username/password required |
### Universal SIP URI Format
```
sip:[identifier]@34.27.110.155:5080;transport=tcp
```
**Critical:** Replace `[identifier]` with your unique Vodex SIP identifier from your Dialer Config setup. The IP address `34.27.110.155` must be used exactly as shown.
***
## ๐ Provider-Specific Guides
### Vonage (formerly Nexmo)
**Configuration Steps**
**1. Access Vonage Dashboard:**
* Login to [Vonage API Dashboard](https://dashboard.nexmo.com)
* Navigate to Voice โ SIP Endpoints or Voice โ Applications
**2. Create SIP Endpoint:**
```
Endpoint Name: Vodex-AI-Integration
SIP URI: sip:[your-identifier]@34.27.110.155:5080;transport=tcp
```
**3. Routing Configuration:**
* **Destination:** `34.27.110.155:5080`
* **Protocol:** TCP
* **Priority:** 1 (highest)
* **Weight:** 100
**4. Phone Number Linking:**
* Go to Numbers โ Your Numbers
* Select the phone number to configure
* Set Voice webhook to route to your SIP endpoint
* Configure answer URL to point to Vodex SIP
**Example Webhook URL:**
```
sip:[your-identifier]@34.27.110.155:5080;transport=tcp
```
**Optional Configuration**
**Call Recording:**
* Enable if required for compliance
* Configure storage settings
* Set recording format (MP3/WAV)
**Fallback Routing:**
* Configure backup endpoints if needed
* Set timeout values for connection attempts
* Define retry logic for failed connections
**Security Settings:**
* IP whitelisting (add 34.27.110.155)
* Rate limiting configuration
* Access control policies
### Bandwidth
**Setup Process**
**1. Access Bandwidth Dashboard:**
* Login to [Bandwidth Dashboard](https://dashboard.bandwidth.com)
* Navigate to Voice โ SIP Domains or Trunks
**2. Create SIP Domain/Trunk:**
```
Domain Name: vodex-ai-trunk
Description: Vodex AI Integration
```
**3. Termination Settings:**
```
Termination Host: 34.27.110.155
Port: 5080
Transport: TCP
Authentication: None (IP-based)
```
**4. Routing Rules:**
* Create routing rule for inbound calls
* Set destination to Vodex SIP gateway
* Configure priority and weight settings
**5. Phone Number Assignment:**
* Assign phone numbers to the SIP domain
* Configure voice routing to use SIP termination
* Test call routing to Vodex
**Additional Features**
**Call Detail Records (CDR):**
* Configure CDR collection and storage
* Set up automated CDR delivery
* Define CDR format and fields
**Quality Monitoring:**
* Enable voice quality monitoring
* Configure alerting for call quality issues
* Set up performance dashboards
**Failover Configuration:**
* Define backup routing rules
* Configure automatic failover triggers
* Set up monitoring and alerting
### Flowroute
**Configuration Steps**
**1. Flowroute Portal Access:**
* Login to [Flowroute Portal](https://manage.flowroute.com)
* Navigate to Preferences โ SIP โ Termination
**2. Add Termination Target:**
```
Target Name: Vodex-AI-Gateway
Target IP: 34.27.110.155
Port: 5080
Transport: TCP
```
**3. Route Configuration:**
* Go to Preferences โ Routes
* Create new route for Vodex integration
* Set route priority and selection criteria
**4. DID Assignment:**
* Navigate to Numbers โ DIDs
* Select phone numbers to configure
* Assign route to direct calls to Vodex
* Enable and test configuration
**Advanced Configuration**
**Least Cost Routing (LCR):**
* Configure multiple termination targets
* Set cost-based routing priorities
* Define failover sequences
**Call Analytics:**
* Enable detailed call reporting
* Configure real-time monitoring
* Set up automated alerts
**Security Features:**
* IP access control lists
* Rate limiting and fraud protection
* Call pattern monitoring
### VoIP.ms
**Setup Process**
**1. VoIP.ms Portal:**
* Login to [VoIP.ms Portal](https://voip.ms)
* Navigate to DID Numbers โ Manage DID
**2. DID Configuration:**
```
Routing: SIP URI
SIP URI: sip:[your-identifier]@34.27.110.155:5080
```
**3. Advanced Routing:**
* Go to Account โ Sub Accounts (if using)
* Configure SIP authentication settings
* Set up call routing preferences
**4. Testing:**
* Use VoIP.ms testing tools
* Verify call routing to Vodex
* Check audio quality and connection stability
***
## ๐ ๏ธ Generic Configuration Template
### Universal Setup Steps
**Pre-Configuration Checklist**
* [ ] SIP provider account with admin access
* [ ] Phone numbers purchased and assigned
* [ ] Vodex Dialer Config completed
* [ ] Vodex SIP identifier obtained
**Platform Access**
1. Login to your SIP provider's control panel
2. Navigate to SIP/Voice/Trunk configuration section
3. Locate termination or routing settings
4. Prepare to create new configuration
**Core Settings**
```
Destination Host: 34.27.110.155
Port: 5080
Transport Protocol: TCP
Authentication: None/IP-based
SIP URI: sip:[your-identifier]@34.27.110.155:5080;transport=tcp
```
**Call Direction**
1. Create routing rule for inbound calls
2. Set Vodex SIP as the termination target
3. Configure priority and weight (usually Priority: 1, Weight: 100)
4. Enable the routing rule
**Number Assignment**
1. Select phone numbers to configure
2. Assign SIP routing rule to numbers
3. Set call handling to use SIP termination
4. Save and activate configuration
**Validation**
1. Make test calls to configured numbers
2. Verify calls reach Vodex AI agents
3. Check call quality and response time
4. Monitor for any connection issues
***
## ๐ง Common Configuration Parameters
### Standard SIP Settings
| Parameter | Typical Location | Vodex Value | Notes |
| ------------------ | ------------------- | -------------------- | ------------------------ |
| **Host/Server** | Termination/Routing | `34.27.110.155` | Always use this IP |
| **Port** | Termination/Routing | `5080` | Standard SIP port |
| **Transport** | Advanced/Protocol | `TCP` | Preferred over UDP |
| **Authentication** | Security/Auth | `None` or `IP-based` | No credentials needed |
| **Codec** | Audio/Media | Provider default | Usually G.711 works best |
| **DTMF** | Audio/Signaling | `RFC 2833` | Standard DTMF handling |
### Priority and Weight Settings
```
Priority: 1-10 (lower numbers = higher priority)
Weight: 1-100 (higher numbers = more traffic)
Recommended for Vodex:
Priority: 1
Weight: 100
```
### Timeout and Retry Settings
```
Connection Timeout: 30 seconds
Retry Attempts: 3
Retry Interval: 5 seconds
Call Timeout: 60 seconds
```
***
## ๐ Troubleshooting Guide
### Common Issues Across Providers
**Symptoms:**
* Calls fail to connect
* Busy signal or fast busy
* "Number not in service" messages
**Diagnosis:**
1. Verify IP address is exactly `34.27.110.155`
2. Check port is set to `5080`
3. Confirm transport is TCP
4. Validate SIP identifier in URI
**Solutions:**
* Double-check all configuration parameters
* Test with provider's diagnostic tools
* Verify Vodex Dialer Config is properly set up
* Contact provider support for routing verification
**Symptoms:**
* Caller can hear AI but AI can't hear caller
* AI can speak but caller hears silence
* Intermittent audio quality issues
**Diagnosis:**
1. Check NAT and firewall settings
2. Verify RTP port ranges
3. Test with different transport protocols
4. Review media codec configuration
**Solutions:**
* Ensure TCP transport is used
* Configure proper RTP port ranges
* Check provider's NAT handling
* Test from different network locations
**Symptoms:**
* Long delays before AI answers
* Timeout before connection
* Slow call establishment
**Diagnosis:**
1. Check network latency to Vodex servers
2. Review provider's routing efficiency
3. Verify no unnecessary authentication delays
4. Test during different times of day
**Solutions:**
* Optimize routing configuration
* Remove unnecessary authentication steps
* Consider provider network performance
* Contact Vodex support for server status
### Provider-Specific Troubleshooting
**Testing Tools by Provider**
**Vonage:**
```bash theme={null}
# Use Vonage's SIP testing tool
# Check webhook responses
# Review call logs in dashboard
```
**Bandwidth:**
```bash theme={null}
# Use Bandwidth's network testing
# Check SIP domain connectivity
# Review call detail records
```
**Flowroute:**
```bash theme={null}
# Use Flowroute's diagnostics
# Test termination targets
# Check route effectiveness
```
**What to Check**
**Call Logs:**
* Call setup times and success rates
* SIP response codes and errors
* Audio quality metrics
**Network Metrics:**
* Latency to Vodex servers
* Packet loss and jitter
* Connection stability
**Configuration Audit:**
* Recent changes to settings
* Comparison with working configurations
* Validation of all parameters
***
## ๐ Configuration Checklist
### Pre-Configuration
* [ ] SIP provider account with appropriate permissions
* [ ] Phone numbers purchased and available
* [ ] Vodex Dialer Config completed and tested
* [ ] SIP identifier obtained from Vodex
### Provider Configuration
* [ ] SIP endpoint/trunk created with descriptive name
* [ ] Termination host set to `34.27.110.155`
* [ ] Port configured as `5080`
* [ ] Transport protocol set to TCP
* [ ] Authentication disabled or set to IP-based
* [ ] SIP URI properly formatted with Vodex identifier
### Routing Setup
* [ ] Routing rules created for inbound calls
* [ ] Priority and weight values configured
* [ ] Phone numbers assigned to SIP routing
* [ ] Configuration saved and activated
### Testing and Validation
* [ ] Test calls completed successfully
* [ ] AI agents respond appropriately
* [ ] Call quality is acceptable
* [ ] No connection errors or timeouts
* [ ] End-to-end integration verified
***
## ๐ก Best Practices
### Configuration Management
* **Documentation:** Keep detailed records of all provider configurations
* **Naming Conventions:** Use consistent, descriptive names across providers
* **Version Control:** Track changes and maintain configuration backups
* **Testing:** Always test thoroughly before going live
### Security Considerations
* **IP Whitelisting:** Add Vodex IP (34.27.110.155) to allowed lists
* **Access Control:** Limit configuration access to authorized personnel
* **Monitoring:** Set up alerts for unusual call patterns or failures
* **Regular Audits:** Review configurations periodically for security and efficiency
### Performance Optimization
* **Load Distribution:** Use multiple providers for redundancy if needed
* **Quality Monitoring:** Track call quality metrics and optimize accordingly
* **Cost Management:** Monitor usage and optimize routing for cost efficiency
* **Capacity Planning:** Ensure provider capacity meets your call volume needs
***
## ๐ Next Steps
After configuring your SIP provider:
1. **Test Thoroughly** - Verify all call flows work correctly
2. **Monitor Performance** - Track call quality and connection reliability
3. **Optimize Settings** - Fine-tune based on initial performance data
4. **Scale Operations** - Add more numbers or providers as needed
5. **Document Everything** - Maintain detailed configuration records
**Generic SIP Integration Complete!** Your SIP provider is now configured to route calls to Vodex AI. Incoming calls to your configured numbers will be automatically handled by your AI agents.
***
**Need provider-specific help?** Contact your SIP provider's support team for platform-specific configuration assistance, or reach out to [Vodex support](mailto:support@vodex.ai) for integration guidance and troubleshooting.
# ๐ Inbound/ViciDialer Integration (Dialer Config)
Source: https://docs.vodex.ai/inbound/overview
Enterprise and invite-only inbound calling capabilities with SIP integration and ViciDialer support
**Enterprise & Invite Only:** Inbound calling capabilities are available for Enterprise customers and by special invitation. Contact support for access to these advanced features.
Vodex supports sophisticated inbound calling through SIP integration, enabling seamless integration with ViciDialer and other telephony systems. This powerful feature allows you to handle incoming calls with the same AI intelligence used for outbound campaigns.
***
## ๐ How Inbound Integration Works
### System Architecture
```mermaid theme={null}
graph TD
A[Incoming Call] --> B[Dialer/Twilio SIP]
B --> C[SIP URI: sip:xxxxxxxxxx @ 34.27.110.155:5080 - no spaces]
C --> D[Vodex SIP Gateway]
D --> E{Extract Call ID}
E --> F[Lookup Attached Call Settings]
F --> G[Load AI Agent Configuration]
G --> H[Start AI Conversation]
H --> I[Process Call with Locked Settings]
I --> J[Call Completion & Insights]
K[Project Settings] -.-> L[Dialer Config Section]
L --> M[Attach Reference Call]
M --> N[Generate SIP URI]
N --> C
style A fill:#e1f5fe
style D fill:#f3e5f5
style F fill:#e8f5e8
style I fill:#fff3e0
style M fill:#ffebee
```
### Dual Functionality
**True Inbound Handling**
* Receive calls from customers calling your business
* Handle customer service inquiries automatically
* Process appointment requests and information calls
* Manage support tickets and follow-ups
**Outbound via ViciDialer**
* Use ViciDialer for predictive dialing
* Leverage Vodex AI for conversation handling
* Combine dialer efficiency with AI intelligence
* Scale outbound operations with automation
***
## โ๏ธ Configuration Process
### Step 1: Create Reference Call
**Create Template Call**
* Create a new outbound call in your project
* Configure all desired settings (AI model, voice, prompts, etc.)
* Set up custom fields and insights as needed
* Test the call to ensure everything works correctly
**Enable Dialer Configuration**
* Navigate to your project settings
* Look for "Dialer Config" section
* **Note:** This section is enabled on request only
* Contact support if you don't see this option
**Link Call to Inbound**
* In Dialer Config section, select your test call
* Click "Attach Call" to link it to inbound routing
* System will generate a unique SIP URI
* Save the configuration
**Retrieve Connection Details**
* System displays SIP URI: `sip:xxxxxxxxxx@34.27.110.155:5080`
* Copy this URI for your dialer/Twilio configuration
* The `xxxxxxxxxx` is your unique call identifier
### Step 2: Configure Your Dialer
**Twilio SIP Trunk Setup**
**Origination URI:**
```
sip:xxxxxxxxxx@34.27.110.155:5080
```
**Configuration Steps:**
1. Login to your Twilio Console
2. Navigate to Elastic SIP Trunking
3. Create or edit your SIP Trunk
4. Add the Vodex SIP URI to Origination settings
5. Configure authentication if required
**Whitelist Status:** All Twilio SIP Trunks are pre-whitelisted on Vodex servers for seamless connectivity.
**ViciDialer Configuration**
**Carrier Settings:**
* **Carrier Name:** Vodex-AI
* **Gateway:** `34.27.110.155:5080`
* **Dialplan:** Custom with Vodex SIP URI
* **Protocol:** SIP
**Dial String Format:**
```
SIP/xxxxxxxxxx@34.27.110.155:5080
```
**Campaign Configuration:**
* Set up your ViciDialer campaign normally
* Use Vodex carrier for outbound routing
* Configure lead lists and dialing parameters
* Vodex AI handles the conversation once connected
**Other SIP Systems**
**Universal Configuration:**
* **SIP Server:** `34.27.110.155`
* **Port:** `5080`
* **Username:** `xxxxxxxxxx` (from your SIP URI)
* **Protocol:** SIP/UDP or SIP/TCP
**Dial Pattern:**
```
sip:xxxxxxxxxx@34.27.110.155:5080
```
***
## ๐ Call Attachment System
### Why Use Call Attachment?
**Quality Protection:** The call attachment system acts as a locking mechanism to ensure inbound call quality remains consistent even when project settings are being modified.
#### The Problem Without Attachment
**Potential Problems:**
* Inbound calls affected by real-time project changes
* Inconsistent AI behavior during settings updates
* Quality degradation during agent modifications
* Unpredictable call outcomes during maintenance
#### The Solution: Call Attachment
**Stability Advantages:**
* Inbound calls use frozen, tested settings
* Project modifications don't affect active inbound routing
* Consistent AI behavior for all incoming calls
* Quality assurance through configuration locking
### How Call Attachment Works
**Settings Capture**
* When you attach a call, Vodex captures all settings
* AI prompt, voice settings, model configuration
* Custom fields, insights, and workflow rules
* Complete configuration is "frozen" for inbound use
**Independent Processing**
* Inbound calls operate independently from project changes
* Live project modifications don't affect inbound routing
* Attached call settings remain stable and consistent
* Quality is maintained regardless of ongoing work
**Changing Inbound Settings**
* To modify inbound behavior, create a new outbound call
* Configure the new call with desired changes
* Test thoroughly before attaching
* Replace the old attachment with the new call
***
## ๐ Operational Workflow
### Inbound Call Processing
**Incoming Call Handling**
1. Call arrives at Vodex SIP gateway
2. System extracts unique identifier from SIP URI
3. Looks up attached call configuration
4. Loads frozen AI agent settings
5. Initiates AI conversation with caller
**Conversation Management**
* AI uses locked prompt and personality settings
* Processes caller input using configured model
* Applies custom fields and insights collection
* Handles conversation flow according to attached settings
* Maintains consistent behavior throughout call
**Insights and Analytics**
* Collects insights based on attached call configuration
* Updates CRM systems if configured
* Generates call summaries and transcripts
* Triggers webhooks with call completion data
* Maintains audit trail for quality assurance
### ViciDialer Integration Flow
```mermaid theme={null}
sequenceDiagram
participant V as ViciDialer
participant S as SIP Gateway
participant AI as Vodex AI
participant C as Customer
V->>S: Initiate Call via SIP URI
S->>AI: Load Attached Call Settings
AI->>C: Connect & Start Conversation
C->>AI: Customer Response
AI->>C: AI Response (using locked settings)
Note over AI,C: Conversation continues with
consistent AI behavior
AI->>S: Call Completion Data
S->>V: Return Call Results
AI->>AI: Generate Insights & Summary
```
***
## ๐ ๏ธ Management and Updates
### Updating Inbound Configuration
**Prepare Updated Settings**
* Create a new outbound call with desired changes
* Update prompts, voice settings, or AI model
* Configure new custom fields or insights
* Test thoroughly with sample calls
**Quality Assurance**
* Run multiple test calls to verify behavior
* Check all conversation flows and edge cases
* Validate insights collection and data accuracy
* Ensure voice quality and response timing
**Switch to New Configuration**
* Access Dialer Config section in project
* Detach current call configuration
* Attach the new, tested call
* Verify SIP URI remains the same (or update dialer if changed)
**Post-Update Monitoring**
* Monitor first few inbound calls closely
* Verify AI behavior matches expectations
* Check insights data collection
* Confirm integration stability
### Best Practices
**Setup Best Practices**
* Always test outbound calls thoroughly before attaching
* Use descriptive names for reference calls
* Document configuration changes and reasons
* Maintain backup configurations for quick rollback
**Monitoring Guidelines**
* Monitor inbound call quality regularly
* Review AI conversation transcripts
* Track customer satisfaction metrics
* Analyze insights data for accuracy
**Change Management**
* Schedule configuration updates during low-traffic periods
* Prepare rollback plans before making changes
* Test new configurations extensively
* Communicate changes to relevant team members
***
## ๐ Use Cases and Benefits
### Inbound Customer Service
**24/7 Customer Service**
* Handle customer inquiries automatically
* Provide account information and status updates
* Process service requests and appointments
* Escalate complex issues to human agents
**Benefits:**
* Reduced wait times for customers
* Consistent service quality
* 24/7 availability
* Cost-effective support scaling
### ViciDialer Enhancement
**Enhanced Outbound Operations**
* Combine ViciDialer's predictive algorithms with Vodex AI
* Increase agent efficiency through automation
* Maintain conversation quality at scale
* Reduce training requirements for human agents
**Benefits:**
* Higher contact rates
* Consistent conversation quality
* Scalable operations
* Improved conversion rates
***
## ๐ Getting Started
### Prerequisites
**Access Requirements:** Inbound/ViciDialer integration requires Enterprise plan or special invitation. Contact [support@vodex.ai](mailto:support@vodex.ai) for access.
### Setup Checklist
**Confirm Eligibility**
* [ ] Enterprise plan active or invitation received
* [ ] Dialer Config section visible in project
* [ ] SIP integration permissions enabled
**Create Reference Call**
* [ ] Outbound call created and tested
* [ ] AI prompts optimized for inbound scenarios
* [ ] Custom fields and insights configured
* [ ] Voice and model settings finalized
**Set Up SIP Routing**
* [ ] Call attached in Dialer Config section
* [ ] SIP URI generated and copied
* [ ] Dialer/Twilio configured with Vodex SIP URI
* [ ] Connection tested and verified
**Launch Inbound Operations**
* [ ] Monitor first inbound calls closely
* [ ] Verify AI behavior and quality
* [ ] Check data collection and insights
* [ ] Document configuration for team reference
***
## ๐ก Next Steps
After setting up inbound integration:
1. **Monitor Performance** - Track call quality and AI behavior
2. **Optimize Prompts** - Refine AI instructions based on inbound scenarios
3. **Scale Operations** - Expand to handle higher call volumes
4. **Integrate Analytics** - Connect insights data to your reporting systems
5. **Train Team** - Ensure team understands the locked configuration system
**Ready for inbound AI calling?** The Vodex inbound integration provides enterprise-grade capabilities for handling incoming calls with the same AI intelligence used in outbound campaigns.
***
## ๐ Advanced Features & Customizations
### Undocumented Capabilities
**Beyond Standard Documentation**
The Vodex inbound and ViciDialer integration includes many advanced features and customizations that go beyond what's covered in this documentation. These enterprise-grade capabilities are designed for specific use cases and complex implementations.
**Examples of Advanced Features:**
* Custom SIP routing and failover configurations
* Advanced ViciDialer campaign integrations
* Specialized telephony provider integrations
* Custom data flow and CRM synchronization
* Advanced call routing and distribution logic
* Specialized compliance and recording features
**Unlock Advanced Capabilities:** Many powerful features and customizations are available but not documented here. These enterprise-level capabilities are configured on a case-by-case basis to meet specific business requirements.
### Get Access to Advanced Features
**Discuss Your Requirements**
* Email [support@vodex.ai](mailto:support@vodex.ai)
* Subject: "Advanced Inbound/ViciDialer Features"
* Describe your specific use case and requirements
**Tailored Implementation**
* Our team will assess your needs
* Custom features will be configured for your account
* Specialized documentation provided as needed
**Enterprise Support**
* Dedicated support for advanced features
* Custom training and documentation
* Priority assistance for complex implementations
**Enterprise Advantage:** Advanced inbound and ViciDialer features are part of our commitment to providing enterprise-grade solutions that can be tailored to your specific business needs and technical requirements.
***
**Need access to inbound features?** Contact our enterprise team at [support@vodex.ai](mailto:support@vodex.ai) with "Inbound Integration Access" in the subject line to discuss Enterprise plan options, special invitations, and unlock advanced undocumented features.
# ๐ง Twilio Inbound Configuration
Source: https://docs.vodex.ai/inbound/twilio-configuration
Step-by-step guide to configure Twilio SIP Trunks for inbound calls handled by Vodex AI agents
**Prerequisites:** This guide assumes you have already completed the Dialer Config setup in your Vodex project and obtained your SIP URI. If you haven't done this yet, please refer to the [Inbound Overview](/inbound/overview) first.
Configure your Twilio SIP Trunk to route incoming calls directly to your Vodex AI agents. This setup ensures that any call coming to your Twilio phone number will be automatically answered and handled by your configured AI bot.
***
## ๐ฏ Configuration Overview
When you complete this setup:
* **Incoming calls** to your Twilio phone number โ **Automatically answered by Vodex AI**
* **No human intervention** required for call handling
* **Consistent AI behavior** using your locked Dialer Config settings
* **Seamless integration** between Twilio and Vodex platforms
***
## โ๏ธ Step-by-Step Twilio Configuration
### Step 1: Complete Dialer Config Setup
**Required First:** You must complete the Dialer Config setup in your Vodex project before configuring Twilio. This generates the SIP URI needed for the configuration.
**Before proceeding, ensure you have:**
* โ
Created and tested your reference call in Vodex
* โ
Attached the call in Dialer Config section
* โ
Obtained your SIP URI: `sip:xxxxxxxxxx@34.27.110.155:5080`
* โ
Noted down the `xxxxxxxxxx` identifier from your SIP URI
### Step 2: Access Twilio SIP Trunking
**Navigate to SIP Trunking**
1. Open your browser and go to [Twilio Console](https://console.twilio.com/us1/develop/sip-trunking/manage/trunks?frameUrl=/console/sip-trunking/trunks)
2. Login with your Twilio account credentials
3. Navigate to **Develop** โ **Elastic SIP Trunking** โ **Trunks**
**Set Up Trunk**
1. Click **"Create new SIP Trunk"** button
2. Enter a descriptive name (e.g., "Vodex-AI-Inbound")
3. Add any relevant description for future reference
4. Click **"Create"** to proceed
### Step 3: Configure Origination Settings
**Navigate to Origination**
1. In your newly created SIP Trunk, click on **"Origination"** tab
2. This is where you'll configure how Twilio routes incoming calls
3. Click **"Add Origination URI"** to create a new route
**Enter Vodex SIP Details**
**Origination URI:**
```
sip:+xxxxxxxxxx@34.27.110.155:5080;transport=tcp
```
**Configuration Parameters:**
* **URI:** `sip:+xxxxxxxxxx@34.27.110.155:5080;transport=tcp`
* **Priority:** `10`
* **Weight:** `10`
**Important:** Replace `xxxxxxxxxx` with your actual SIP identifier from the Dialer Config setup. Include the `+` sign before your identifier.
**Finalize Setup**
1. Double-check all parameters are correct
2. Verify the SIP URI matches your Vodex configuration
3. Click **"Save Configuration"** or **"Add"** to apply settings
4. Confirm the origination URI appears in your trunk configuration
***
## ๐ง Configuration Details
### SIP URI Format Breakdown
```
sip:+xxxxxxxxxx@34.27.110.155:5080;transport=tcp
```
| Component | Value | Description |
| ------------- | --------------- | ------------------------------------------------ |
| **Protocol** | `sip:` | SIP protocol identifier |
| **User** | `+xxxxxxxxxx` | Your unique Vodex SIP identifier (with + prefix) |
| **Host** | `34.27.110.155` | Vodex SIP gateway IP address |
| **Port** | `5080` | SIP communication port |
| **Transport** | `tcp` | Transport protocol for reliable delivery |
### Priority and Weight Settings
| Parameter | Recommended Value | Purpose |
| ------------ | ----------------- | --------------------------------------------- |
| **Priority** | `10` | Lower numbers = higher priority |
| **Weight** | `10` | Load balancing weight (higher = more traffic) |
**Settings Explanation:** Priority 10 and Weight 10 are standard values that work well for most configurations. Priority determines route preference (lower numbers get higher priority), while weight handles load distribution among routes with the same priority.
***
## ๐ Linking Phone Numbers
### Step 4: Connect Phone Number to SIP Trunk
**Access Phone Number Management**
1. In Twilio Console, go to **Phone Numbers** โ **Manage** โ **Active Numbers**
2. Find the phone number you want to connect to Vodex AI
3. Click on the phone number to edit its configuration
**Set Up Call Routing**
1. In the phone number configuration, find **"Voice & Fax"** section
2. Set **"Configure with"** to **"SIP Trunk"**
3. Select your newly created Vodex SIP Trunk from the dropdown
4. Save the configuration
**Verify Setup**
1. Call your Twilio phone number from any phone
2. The call should be automatically answered by your Vodex AI agent
3. Verify the AI responds according to your Dialer Config settings
4. Check call quality and conversation flow
***
## ๐ How It Works
### Call Flow Process
```mermaid theme={null}
sequenceDiagram
participant C as Caller
participant T as Twilio Number
participant TS as Twilio SIP Trunk
participant V as Vodex SIP Gateway
participant AI as Vodex AI Agent
C->>T: Dials Twilio Phone Number
T->>TS: Routes to Configured SIP Trunk
TS->>V: Forwards via Origination URI
V->>AI: Loads Attached Call Settings
AI->>C: Answers & Starts Conversation
Note over C,AI: Conversation handled by
Vodex AI using locked
Dialer Config settings
AI->>V: Call Completion Data
V->>TS: Return Call Status
TS->>T: Update Call Records
```
### What Happens During a Call
**Incoming Call Processing**
1. Customer dials your Twilio phone number
2. Twilio receives the call and checks configuration
3. Call is routed to your configured SIP Trunk
4. SIP Trunk forwards call to Vodex via Origination URI
**Vodex AI Engagement**
1. Vodex SIP Gateway receives the call
2. System extracts your unique identifier from SIP URI
3. Looks up your attached Dialer Config settings
4. Loads the frozen AI agent configuration
5. AI answers the call and begins conversation
**Call Handling**
1. AI uses your locked prompt and personality settings
2. Processes customer input using configured AI model
3. Applies custom fields and insights collection
4. Maintains consistent behavior throughout the call
5. Generates insights and call summary upon completion
***
## โ
Verification and Testing
### Testing Your Setup
**Basic Functionality Check**
1. Call your Twilio phone number from any device
2. Verify the call is answered automatically
3. Confirm the AI agent responds appropriately
4. Test basic conversation flow
**Detailed Testing**
1. Test different conversation scenarios
2. Verify custom fields are being collected
3. Check insights generation in your Vodex dashboard
4. Assess call quality and response timing
**End-to-End Verification**
1. Confirm calls appear in your Vodex project
2. Review transcripts and conversation data
3. Verify any webhook integrations are working
4. Test multiple concurrent calls if needed
### Troubleshooting Common Issues
**Connection Issues**
**Possible Causes:**
* Incorrect SIP URI in Twilio configuration
* Missing or wrong Vodex SIP identifier
* Twilio trunk not properly linked to phone number
**Solutions:**
1. Double-check your SIP URI format and identifier
2. Verify the origination URI is saved correctly
3. Confirm phone number is linked to the correct SIP trunk
4. Check Twilio console for error logs
**Response Issues**
**Possible Causes:**
* Dialer Config not properly set up in Vodex
* Reference call not attached or configured incorrectly
* SIP identifier mismatch between Twilio and Vodex
**Solutions:**
1. Verify your Dialer Config setup in Vodex project
2. Ensure reference call is properly attached
3. Check that SIP identifiers match exactly
4. Test the reference call directly in Vodex
**Call Quality Problems**
**Possible Causes:**
* Network connectivity issues
* Incorrect transport protocol
* SIP trunk configuration problems
**Solutions:**
1. Ensure transport=tcp is specified in URI
2. Check network connectivity between Twilio and Vodex
3. Verify SIP trunk configuration is complete
4. Contact support if issues persist
***
## ๐ง Advanced Configuration
### Multiple Phone Numbers
**Connecting Multiple Numbers**
You can connect multiple Twilio phone numbers to the same Vodex AI configuration:
1. **Same SIP Trunk:** Link multiple phone numbers to your existing SIP trunk
2. **Same AI Agent:** All numbers will use the same attached Dialer Config
3. **Consistent Experience:** Customers get the same AI interaction regardless of which number they call
4. **Centralized Management:** Manage all inbound calls from one Vodex configuration
### Different AI Agents per Number
**Multiple Configurations**
For different AI behaviors per phone number:
1. **Create separate SIP Trunks** in Twilio for each configuration
2. **Set up different Dialer Configs** in Vodex with unique SIP URIs
3. **Link each phone number** to its corresponding SIP trunk
4. **Different AI experiences** for different business lines or purposes
***
## ๐ Configuration Checklist
### Pre-Configuration
* [ ] Vodex Dialer Config completed
* [ ] SIP URI obtained from Vodex (`sip:xxxxxxxxxx@34.27.110.155:5080`)
* [ ] Twilio account with SIP Trunking enabled
* [ ] Phone number purchased and active in Twilio
### Twilio Configuration
* [ ] SIP Trunk created with descriptive name
* [ ] Origination URI configured: `sip:+xxxxxxxxxx@34.27.110.155:5080;transport=tcp`
* [ ] Priority set to `10`
* [ ] Weight set to `10`
* [ ] Configuration saved successfully
### Phone Number Linking
* [ ] Phone number configured to use SIP Trunk
* [ ] Voice settings updated to route through trunk
* [ ] Configuration saved and active
### Testing and Validation
* [ ] Test call completed successfully
* [ ] AI agent responds appropriately
* [ ] Call quality is acceptable
* [ ] Insights and data collection working
* [ ] Integration verified end-to-end
***
## ๐ก Best Practices
### Configuration Management
* **Document your setup** - Keep records of SIP URIs and configuration details
* **Use descriptive names** - Name your SIP trunks clearly for easy identification
* **Test thoroughly** - Always test after making any configuration changes
* **Monitor performance** - Regularly check call quality and AI performance
### Security Considerations
* **Protect SIP URIs** - Don't share your SIP identifiers publicly
* **Monitor usage** - Watch for unexpected call patterns or volumes
* **Regular audits** - Periodically review your Twilio and Vodex configurations
* **Access control** - Limit who can modify your SIP trunk configurations
***
## ๐ Next Steps
After completing your Twilio configuration:
1. **Monitor Call Performance** - Track call quality and AI behavior
2. **Optimize AI Prompts** - Refine your Dialer Config based on inbound scenarios
3. **Scale Your Operations** - Add more phone numbers as needed
4. **Integrate Analytics** - Connect call data to your reporting systems
5. **Train Your Team** - Ensure staff understand the inbound AI system
**Twilio Integration Complete!** Your phone number is now powered by Vodex AI. Incoming calls will be automatically answered and handled by your configured AI agent using the locked Dialer Config settings.
***
**Need help with your Twilio configuration?** Contact our support team at [support@vodex.ai](mailto:support@vodex.ai) with "Twilio Inbound Setup" in the subject line for assistance with complex configurations or troubleshooting.
# ๐ Twilio SIP Trunk Creation Guide
Source: https://docs.vodex.ai/inbound/twilio-sip-trunk-setup
Complete guide to creating and configuring SIP Trunks in Twilio for Vodex AI integration
**Purpose:** This guide walks you through creating a SIP Trunk in Twilio that can route calls to Vodex AI agents. This is the foundation step before configuring inbound call routing.
Learn how to create and configure SIP Trunks in Twilio to enable seamless integration with Vodex AI. SIP Trunks act as the bridge between your Twilio phone numbers and the Vodex AI system.
***
## ๐ฏ What is a SIP Trunk?
### SIP Trunk Overview
**Communication Bridge**
A SIP Trunk is a virtual connection that enables Voice over IP (VoIP) communication between different systems. In our case, it connects:
* **Twilio's phone system** โ **Vodex AI platform**
* **Your phone numbers** โ **AI agents**
* **Incoming calls** โ **Automated responses**
### Why You Need a SIP Trunk
**Seamless Call Direction**
* Routes incoming calls from Twilio to Vodex AI
* Enables automatic call answering by AI agents
* Provides reliable connection between platforms
* Ensures consistent call quality and delivery
**Flexible Setup Options**
* Configure multiple phone numbers to use one trunk
* Set up different trunks for different AI configurations
* Control call routing and failover options
* Manage authentication and security settings
**Call Tracking**
* Monitor call volumes and success rates
* Track connection quality and performance
* Generate reports on call routing efficiency
* Debug connection issues when they occur
***
## ๐ ๏ธ Step-by-Step SIP Trunk Creation
### Step 1: Access Twilio Console
**Navigate to SIP Trunking**
1. Go to [Twilio Console](https://console.twilio.com)
2. Login with your Twilio account credentials
3. Navigate to **Develop** โ **Elastic SIP Trunking**
4. Click on **"Trunks"** in the sidebar menu
**Start New Trunk**
1. Click the **"Create new SIP Trunk"** button
2. You'll be directed to the trunk configuration page
3. Prepare to enter your trunk details
### Step 2: Basic Trunk Configuration
**Name and Description**
**Friendly Name:** `Vodex-AI-Trunk`
```
Recommended naming: Vodex-AI-[Purpose]
Examples:
- Vodex-AI-Support
- Vodex-AI-Sales
- Vodex-AI-Main
```
**Domain Name:** (Optional - can be left blank)
```
Leave empty unless you have specific requirements
```
**Description:**
```
SIP Trunk for routing calls to Vodex AI agents
IP: 34.27.110.155
Purpose: [Your specific use case]
```
**Security Configuration**
**Authentication:** `None` (Recommended for Vodex integration)
**Why No Authentication:** Vodex AI servers are pre-configured to accept connections from Twilio. Using IP-based authentication simplifies the setup while maintaining security.
**Secure Trunking:** Enable if required by your organization
### Step 3: Origination Configuration
**Outbound Call Routing**
1. Click on the **"Origination"** tab
2. Click **"Add Origination URI"**
3. Configure the URI pointing to Vodex servers
**Origination URI Settings**
**URI:**
```
sip:34.27.110.155:5080;transport=tcp
```
**Priority:** `10`
**Weight:** `10`
**Important:** Use exactly `34.27.110.155` as the IP address. This is the Vodex AI SIP gateway that will handle your calls.
**Optional Configuration**
**Enabled:** โ
Checked
**Friendly Name:** `Vodex-AI-Gateway`
**Additional Parameters:**
* Leave other settings at default values
* Ensure the URI is active and enabled
* Save the origination configuration
### Step 4: Termination Configuration (Optional)
**Inbound Call Handling**
**For Vodex Integration:** Termination configuration is typically not required for basic Vodex AI integration, as calls are primarily routed outbound to Vodex servers.
**If Termination is Required:**
1. Click on **"Termination"** tab
2. Add termination URI if needed for your specific setup
3. Use the same IP: `34.27.110.155:5080`
***
## โ๏ธ Advanced Configuration Options
### Access Control Lists (ACLs)
**Restrict Access by IP**
**Create ACL:**
1. Navigate to **"Access Control"** section
2. Create new ACL named `Vodex-Whitelist`
3. Add Vodex IP addresses to allowed list
**Vodex IP Addresses:**
```
34.27.110.155 (Primary Vodex Gateway)
```
**Additional IPs:** Contact Vodex support for complete IP whitelist if required
**Regional Access Control**
**Geo Permissions:**
* Configure allowed countries/regions
* Restrict access based on geographic location
* Add specific country codes if needed
* Useful for compliance and security requirements
### Recording and Monitoring
**Enable Recording Features**
**Recording Options:**
* **Dual Channel:** Separate channels for each party
* **Single Channel:** Mixed audio recording
* **Trim Silence:** Remove quiet periods
**Storage Settings:**
* Configure recording storage duration
* Set up automatic transcription if needed
* Define access permissions for recordings
**Monitoring Configuration**
**Enable Insights:**
* Voice Insights for call quality analysis
* Call summary and analytics
* Real-time monitoring dashboards
* Custom alerts for issues or thresholds
***
## ๐ง Testing Your SIP Trunk
### Verification Steps
**Double-Check Settings**
1. Verify origination URI: `sip:34.27.110.155:5080;transport=tcp`
2. Confirm priority and weight values are set
3. Check that the trunk is enabled and active
4. Review authentication settings (should be "None")
**Test Trunk Connectivity**
1. Use Twilio's built-in SIP testing tools
2. Send a test call through the trunk
3. Monitor for any connection errors
4. Verify the trunk shows as "Active" status
**Complete Integration Test**
1. Configure a phone number to use this trunk
2. Set up inbound routing to Vodex (see Twilio Configuration guide)
3. Make a test call to verify AI response
4. Check call logs for successful routing
### Troubleshooting Common Issues
**Connection Problems**
**Symptoms:**
* Trunk shows as "Inactive" or "Failed"
* Calls not routing through the trunk
* Connection timeouts or errors
**Solutions:**
1. Verify IP address is exactly `34.27.110.155`
2. Check port is set to `5080`
3. Ensure transport is specified as `tcp`
4. Confirm no typos in the URI format
5. Check Twilio account has SIP Trunking enabled
**Routing Issues**
**Symptoms:**
* Trunk is active but calls fail
* Busy signals or disconnected calls
* Calls don't reach Vodex AI
**Solutions:**
1. Check origination URI is enabled
2. Verify priority and weight settings
3. Ensure phone number is configured to use this trunk
4. Test with Twilio's SIP testing tools
5. Contact Vodex support to verify server status
**Call Quality Problems**
**Symptoms:**
* Poor audio quality
* Choppy or delayed audio
* One-way audio problems
**Solutions:**
1. Verify transport=tcp in URI
2. Check network connectivity and latency
3. Review Twilio's call quality insights
4. Test at different times to rule out network issues
5. Consider enabling call recording for analysis
***
## ๐ Configuration Checklist
### Pre-Creation Requirements
* [ ] Twilio account with SIP Trunking enabled
* [ ] Appropriate Twilio plan (SIP Trunking may require specific plans)
* [ ] Vodex AI project configured and ready
* [ ] Understanding of your intended call routing
### Trunk Creation
* [ ] SIP Trunk created with descriptive name
* [ ] Origination URI configured: `sip:34.27.110.155:5080;transport=tcp`
* [ ] Priority set to `10`
* [ ] Weight set to `10`
* [ ] Authentication set to "None"
* [ ] Trunk enabled and active
### Testing and Validation
* [ ] Trunk shows "Active" status in Twilio console
* [ ] Test connection successful
* [ ] No configuration errors or warnings
* [ ] Ready for phone number assignment
### Next Steps
* [ ] Link phone numbers to the trunk
* [ ] Configure inbound routing to Vodex
* [ ] Set up specific AI agent routing
* [ ] Test complete call flow
***
## ๐ก Best Practices
### Naming Conventions
```
Recommended Format: Vodex-AI-[Purpose]-[Environment]
Examples:
โ
Vodex-AI-Support-Prod
โ
Vodex-AI-Sales-Test
โ
Vodex-AI-Main-Dev
โ MyTrunk
โ SIPTrunk1
```
### Security Considerations
* **Monitor Usage:** Regularly check call volumes and patterns
* **Access Control:** Use ACLs if your organization requires IP restrictions
* **Authentication:** Use "None" for Vodex integration unless specific security requirements exist
* **Regular Audits:** Periodically review trunk configurations and usage
### Performance Optimization
* **Multiple Trunks:** Consider separate trunks for different purposes or traffic volumes
* **Load Balancing:** Use weight settings to distribute load across multiple URIs if needed
* **Monitoring:** Enable Twilio Insights for call quality monitoring
* **Documentation:** Keep detailed records of your trunk configurations
***
## ๐ Managing Multiple Trunks
### Use Cases for Multiple Trunks
**When to Create Multiple Trunks**
**Different AI Configurations:**
* Separate trunks for different Vodex AI agents
* Different business lines (Sales, Support, etc.)
* Testing vs. Production environments
**Traffic Management:**
* High-volume vs. low-volume call routing
* Geographic or regional routing
* Failover and redundancy planning
**Security Requirements:**
* Different access control needs
* Compliance-specific routing
* Department-specific restrictions
### Trunk Management Best Practices
**Logical Grouping**
* Name trunks clearly to indicate their purpose
* Group related trunks for easy management
* Document the intended use of each trunk
**Regular Assessment**
* Track call success rates per trunk
* Monitor quality metrics and issues
* Review usage patterns and optimization opportunities
**Configuration Records**
* Keep detailed records of each trunk's purpose
* Document any custom configurations or requirements
* Track which phone numbers use which trunks
***
## ๐ Next Steps
After creating your SIP Trunk:
1. **Link Phone Numbers** - Configure your Twilio phone numbers to use this trunk
2. **Set Up Inbound Routing** - Follow the [Twilio Configuration Guide](/inbound/twilio-configuration)
3. **Configure Vodex Integration** - Set up your Dialer Config in Vodex
4. **Test Complete Flow** - Verify end-to-end call routing works correctly
5. **Monitor and Optimize** - Track performance and make adjustments as needed
**SIP Trunk Created Successfully!** Your Twilio SIP Trunk is now ready to route calls to Vodex AI. The next step is configuring inbound call routing to connect your phone numbers to AI agents.
***
**Need help with SIP Trunk setup?** Contact Twilio support for platform-specific issues or [Vodex support](mailto:support@vodex.ai) for integration assistance.
# โจ Insights Overview
Source: https://docs.vodex.ai/insights/overview
Create intelligent post-call analysis questions to extract valuable insights from every conversation using AI
**What you'll learn:** How to create precise AI-powered questions that automatically analyze your calls and extract valuable business insights from every conversation.
**Critical:** Make your insights questions as **precise as possible**. Don't just ask "if the customer is interested" - ask very specifically what you need to know. Precise questions generate accurate, actionable insights.
## What Are Insights?
Insights are intelligent questions that you feed into the Vodex system. After every call, Vodex's AI automatically generates answers to these questions based on the conversation content, providing you with structured data and valuable business intelligence.
### Key Benefits
* **Automated Analysis:** No manual call review needed
* **Structured Data:** Get consistent, queryable results
* **Business Intelligence:** Track trends, conversion rates, and customer behavior
* **Webhook Integration:** Automatically receive insights via API
* **Campaign Optimization:** Use data to improve future campaigns
***
## How Insights Work
**Before Running Campaigns**
* Define specific questions you want answered
* Set up insights at the campaign level
* Configure via API or dashboard interface
**During Calls**
* AI listens to the entire conversation
* Records all relevant information
* Prepares data for analysis
**After Each Call**
* AI analyzes the complete conversation
* Answers your predefined questions
* Generates structured insights data
**Get Your Insights**
* Access via dashboard
* Receive via webhook (if configured)
* Use data for business decisions
**Important:** Insights must be created **before** you run the campaign. You cannot add insights to calls that have already completed.
***
## Insights Configuration
### Three Required Fields
Every insight requires these three components:
**Programming Variable**
The technical identifier for your insight, used in webhooks and API responses.
**Rules:**
* No spaces allowed
* No dashes allowed
* Only underscores for separation
* Use descriptive, clear names
**Examples:**
```
โ
customer_interested
โ
payment_timeline
โ
product_requirements
โ
appointment_confirmed
โ customer interested (spaces)
โ customer-interested (dashes)
โ interested (too vague)
```
**Data Type Selection**
Choose the appropriate data type for your expected answer:
| Type | Use Case | Example Output |
| -------------- | -------------------- | --------------------------------- |
| **Text** | Open-ended responses | "Customer needs premium features" |
| **Number** | Numeric values | `30` (days), `5000` (budget) |
| **True/False** | Yes/no questions | `true`, `false`, `N/A` |
**Selection Guide:**
* Use **Text** for descriptions, requirements, feedback
* Use **Number** for quantities, timelines, budgets
* Use **True/False** for confirmation, agreement, decisions
**AI Analysis Prompt**
The specific question you want the AI to answer about each call.
**Best Practices:**
* Be extremely specific and detailed
* Include fallback instructions (return "N/A" if unclear)
* Define exactly what constitutes a positive/negative response
* Provide context for edge cases
**Question Quality:**
```
โ Poor: "Is the customer interested?"
โ
Good: "Did the customer verbally agree that they are going to purchase the product? Return True or False. If the customer does not commit or is unclear, return N/A"
```
***
## Insights Examples
### Example 1: Purchase Intent
**Name:** `customer_interested`
**Type:** True/False
**Question:** "Did the customer agree verbally that they are going to purchase the product? Return True or False. If the customer does not have anything definitive or seems uncertain, return N/A"
**Use Case:** Track conversion rates and sales pipeline
### Example 2: Payment Timeline
**Name:** `num_days`
**Type:** Number
**Question:** "In how many days did the customer say they are going to make the payment? Return only the number of days mentioned. If no specific timeline was discussed or the customer was vague, return N/A"
**Use Case:** Cash flow planning and follow-up scheduling
### Example 3: Customer Requirements
**Name:** `requirements`
**Type:** Text
**Question:** "What are the customer's specific requirements for the product? Include any features, specifications, or conditions they mentioned. If no specific requirements were discussed, return N/A"
**Use Case:** Product customization and service delivery
### Example 4: Appointment Confirmation
**Name:** `appointment_confirmed`
**Type:** True/False
**Question:** "Did the customer confirm a specific appointment date and time? Return True only if both date and time were agreed upon. If only tentative or partial scheduling occurred, return False. If no appointment was discussed, return N/A"
**Use Case:** Schedule management and confirmation tracking
### Example 5: Budget Information
**Name:** `customer_budget`
**Type:** Number
**Question:** "What budget amount did the customer mention they are willing to spend? Return only the numerical value without currency symbols. If they mentioned a range, return the higher number. If no budget was discussed, return N/A"
**Use Case:** Pricing strategy and proposal preparation
***
## Advanced Insights Strategies
### Precision Guidelines
**Instead of vague questions, define exact conditions:**
โ **Vague:** "Is the customer happy?"
โ
**Specific:** "Did the customer express satisfaction with our service using positive language such as 'great', 'excellent', 'satisfied', or similar positive terms? Return True only for clearly positive feedback, False for negative feedback, and N/A for neutral or unclear responses."
**Always provide instructions for unclear situations:**
โ
**Good Example:** "What is the customer's company size? Return the number of employees if mentioned. If they say 'small business' return 10, if 'medium business' return 100, if 'large business' return 500. If no size information is provided, return N/A."
**Be explicit about what constitutes different responses:**
โ
**Clear Criteria:** "Did the customer agree to a follow-up call? Return True only if they agreed to a specific time or said 'yes' to scheduling. Return False if they declined or said they would call back. Return N/A if follow-up was not discussed."
### Multi-Layered Insights
Create complementary insights that provide deeper analysis:
```
Primary: customer_interested (True/False)
Secondary: interest_level (Number 1-10)
Supporting: objections_mentioned (Text)
Timeline: decision_timeframe (Number - days)
```
***
## Implementation Methods
### Method 1: Campaign-Level Configuration
**Navigate to Your Campaign**
* Open your campaign in the Vodex dashboard
* Go to the Insights section
* Click "Add New Insight"
**Set Up Each Insight**
* Enter the Name (programming variable)
* Select the Type (Text/Number/True-False)
* Write the precise Question
* Save the configuration
**Before Going Live**
* Run test calls to verify insights work
* Check that questions are answered accurately
* Adjust questions if needed
### Method 2: API Integration
```json API Payload Example theme={null}
{
... other params
"campaign_id": "your_campaign_id",
"insights": [
{
"name": "customer_interested",
"type": "boolean",
"question": "Did the customer agree verbally that they are going to purchase the product? Return True or False. If the customer does not commit definitively, return N/A"
},
{
"name": "payment_days",
"type": "number",
"question": "In how many days did the customer say they will make payment? Return only the number. If no timeline mentioned, return N/A"
},
{
"name": "requirements",
"type": "text",
"question": "What specific product requirements did the customer mention? List all features and specifications discussed. If none mentioned, return N/A"
}
]
}
```
```json Webhook Response Example theme={null}
{
"call_uuid": "12345-67890",
"questions": [
{"key": "customer_interested", "value": true},
{"key": "payment_days", "value": 30},
{"key": "requirements", "value": "Premium features with 24/7 support"}
]
}
```
***
## Best Practices
### Question Writing Guidelines
**Precision is Key:** The more specific your question, the more accurate and useful your insights will be. Take time to craft detailed, unambiguous questions.
| Aspect | Best Practice | Example |
| --------------- | ------------------------------- | ------------------------------------------------------------- |
| **Clarity** | Use simple, direct language | "Did the customer confirm..." not "Was there confirmation..." |
| **Specificity** | Define exact conditions | "Return True only if they said 'yes' or 'I agree'" |
| **Fallbacks** | Always include N/A instructions | "If unclear or not discussed, return N/A" |
| **Context** | Provide relevant background | "Based on the sales conversation..." |
### Data Type Selection
**Best for:**
* Customer feedback and comments
* Product requirements and specifications
* Objections and concerns
* Open-ended responses
**Example:** "What objections did the customer raise about the pricing?"
**Best for:**
* Quantities and amounts
* Timelines and dates
* Ratings and scores
* Measurable values
**Example:** "How many users will be using the system?"
**Best for:**
* Yes/no decisions
* Confirmation of actions
* Binary states
* Agreement/disagreement
**Example:** "Did the customer agree to the proposed terms?"
***
## Insights in Webhooks
When you configure post-call insights webhooks, the insights data is included in the `questions` array:
```json Webhook Payload Structure theme={null}
{
"call_uuid": "unique-call-id",
"questions": [
{"key": "your_insight_name", "value": "extracted_value"},
{"key": "another_insight", "value": true},
{"key": "numeric_insight", "value": 45}
],
// ... other call data
}
```
```javascript Processing Insights Data theme={null}
// Example: Processing webhook data
const insights = webhookData.questions;
insights.forEach(insight => {
switch(insight.key) {
case 'customer_interested':
if (insight.value === true) {
// Add to hot leads list
addToHotLeads(webhookData.call_uuid);
}
break;
case 'payment_days':
if (insight.value !== 'N/A') {
// Schedule follow-up
scheduleFollowUp(webhookData.call_uuid, insight.value);
}
break;
}
});
```
***
## Troubleshooting Insights
### Common Issues
| Problem | Cause | Solution |
| -------------------------- | ---------------------------------- | ------------------------------------------------ |
| **Insights not appearing** | Created after campaign run | Create insights before running campaigns |
| **Inaccurate responses** | Vague questions | Make questions more specific and detailed |
| **N/A responses** | Information not discussed in call | Normal behavior - indicates topic wasn't covered |
| **Wrong data type** | Type mismatch with expected answer | Verify question matches selected data type |
### Quality Assurance
**Validate Your Insights**
* Run sample calls with known outcomes
* Verify AI answers match expected results
* Refine questions based on accuracy
**Track Insight Quality**
* Review insights from first few calls
* Look for patterns in N/A responses
* Adjust questions if needed
**Continuous Optimization**
* Refine questions based on results
* Add new insights as needs evolve
* Remove insights that aren't valuable
***
## Next Steps
To get started with Insights:
1. **Plan your questions** - Identify what information you need from calls
2. **Write precise questions** - Follow the specificity guidelines above
3. **Create insights** - Set up insights before running campaigns
4. **Test thoroughly** - Validate accuracy with sample calls
5. **Monitor and optimize** - Continuously improve question quality
**Ready to extract valuable insights?** Well-crafted insights questions transform your call data into actionable business intelligence, helping you make data-driven decisions and optimize your campaigns.
***
**Need help with webhooks?** Check out our [Advanced Settings](/call-settings/advanced-settings) guide to learn how to receive insights data automatically via webhooks.
# ๐ Getting Started with Vodex.ai
Source: https://docs.vodex.ai/introduction
Complete guide to setting up and optimizing your AI-powered voice calling campaigns
Welcome to the comprehensive Vodex.ai documentation. This guide will help you set up, configure, and optimize your AI-powered voice calling campaigns for maximum effectiveness and ROI.
## What You'll Learn
This documentation covers everything you need to know about Vodex.ai:
Learn how to design effective prompts and configure AI agents for natural, human-like conversations.
Configure AI models, voice options, transfer settings, and advanced call parameters for optimal performance.
Extract valuable business insights from every call using AI-powered question analysis.
Set up automated SMS, WhatsApp, and email messaging during or after calls.
***
## Vodex.ai Component Flow
Below is the complete workflow showing how all Vodex.ai components interact and depend on each other:
```mermaid theme={null}
graph TD
A[๐ Start: Create Project] --> B[๐ Project Created]
B --> C[๐ค Create AI Agent]
B --> D[๐ฅ Create Audience List]
C --> E[โ
Agent Configured]
D --> F[โ
Audience List Ready]
E --> G[๐ Create Campaign]
F --> G
G --> H[๐ฏ Campaign Created]
H --> I[โจ Create Insights]
I --> J[๐ Insights Configured]
J --> K[๐ Launch Campaign]
K --> L[๐ Calls Executed]
L --> M[๐ Data Collected]
M --> N[๐ก Insights Generated]
N --> P[๐ Optimize & Iterate]
P --> G
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#e8f5e8
style D fill:#fff3e0
style E fill:#e8f5e8
style F fill:#fff3e0
style G fill:#fce4ec
style H fill:#fce4ec
style I fill:#e0f2f1
style J fill:#e0f2f1
style K fill:#e8eaf6
style L fill:#e8eaf6
style M fill:#f1f8e9
style N fill:#f1f8e9
style O fill:#fff8e1
style P fill:#fce4ec
```
### Component Dependencies & Flow Explanation
**1. Project Foundation** ๐
* **Project Creation**: The starting point that contains all other components
* **Project Settings**: Configure basic parameters, API keys, and integrations
**2. Agent Configuration** ๐ค
* **Agent Creation**: Design AI personality, prompts, and conversation flows
* **Agent Testing**: Validate responses and refine behavior
* **Agent Assignment**: Link agents to specific projects
**3. Audience Management** ๐ฅ
* **Audience List Creation**: Upload contacts, segment by criteria
* **Contact Validation**: Ensure phone numbers are valid and compliant
* **Audience Segmentation**: Group contacts by demographics, behavior, or custom fields
**4. Campaign Setup** ๐
* **Campaign Configuration**: Define objectives, timing, and call parameters
* **Agent Assignment**: Select which AI agent handles the campaign
* **Audience Selection**: Choose which audience list to target
* **Call Settings**: Configure voice, language, and transfer options
**5. Insights & Analytics** โจ
* **Insight Questions**: Define what data to extract from calls
* **Data Types**: Configure response formats and validation rules
* **Webhook Setup**: Enable real-time data delivery to your systems
**6. Execution & Optimization** ๐
* **Campaign Launch**: Start calling campaigns with configured settings
* **Real-time Monitoring**: Track call progress and performance
* **Data Collection**: Gather insights and conversation data
* **Performance Analysis**: Review metrics and identify optimization opportunities
***
## Quick Start Guide
Get your first AI calling campaign up and running in minutes:
**Create Your First Campaign**
* Define your campaign objectives and target audience
* Choose the appropriate AI model for your use case
* Configure basic call settings and voice options
**Create Effective Prompts**
* Write clear, specific instructions for your AI agent
* Define conversation flows and handling scenarios
* Test and refine your agent's responses
๐ [Learn Prompt Design](/agents/prompt)
**Optimize Performance**
* Select the right AI model (GPT, Claude, or Vodex Spark)
* Choose voice providers and configure caller ID
* Set up transfer numbers and voicemail handling
๐ [Configure Call Settings](/call-settings/overview)
**Track What Matters**
* Create precise questions to extract business insights
* Configure data types and naming conventions
* Set up webhook integration for real-time data
๐ [Create Insights](/insights/overview)
**Go Live and Improve**
* Start with test campaigns to validate setup
* Monitor performance and call quality
* Use insights data to optimize future campaigns
***
## Key Features Overview
### ๐ฏ **Campaign Management**
* **Project Organization**: Manage multiple campaigns and use cases
* **Audience Management**: Upload and segment your target contacts
* **Campaign Scheduling**: Control when and how calls are made
* **Performance Tracking**: Monitor success rates and outcomes
### ๐ค **AI Agent Capabilities**
* **Natural Conversations**: Human-like interactions with context awareness
* **Interruption Handling**: Smooth conversation flow even with interruptions
* **Voice Cloning**: Custom voice personalities for brand consistency
* **Multi-Language Support**: English variants, Hindi, German, Spanish, Italian
### ๐ **Analytics & Insights**
* **AI-Powered Analysis**: Automatic extraction of key information from calls
* **Custom Questions**: Define what insights matter to your business
* **Real-Time Data**: Webhook integration for immediate data access
* **Performance Metrics**: Track conversion rates, call duration, and outcomes
### ๐ **Integrations**
* **CRM Systems**: HubSpot, Salesforce, SAP, and custom integrations
* **Communication**: Twilio, custom SIP, WhatsApp Business API
* **Automation**: Zapier, Make, custom webhooks, and API access
* **Messaging**: SMS, WhatsApp, and email during or after calls
***
## Documentation Structure
This documentation is organized into focused sections:
**Foundation Knowledge**
* [What is Vodex.ai](/index) - Company overview and capabilities
* [Getting Started](/introduction) - This guide to help you begin
* [Quick Start](/quickstart) - Fast setup for immediate results
**AI Agent Setup**
* [Prompt Design](/agents/prompt) - Create effective AI agent instructions
* [Agent Tags](/agents/tags) - Organize and categorize your agents
**Technical Configuration**
* [Call Settings Overview](/call-settings/overview) - Basic configuration guide
* [Advanced Settings](/call-settings/advanced-settings) - Language, ASR, webhooks
**Data & Intelligence**
* [Insights Overview](/insights/overview) - AI-powered call analysis
* Create custom questions to extract business value
**Multi-Channel Communication**
* [On-Call Messaging](/messaging/on-call-messaging) - SMS, WhatsApp, Email setup
**Help & Solutions**
* [Common Issues](/troubleshooting/common-issues) - Solutions to frequent problems
* [Best Practices](/custom-fields/best-practices) - Optimization guidelines
***
## Best Practices for Success
### ๐ฏ **Campaign Planning**
**Start Small:** Begin with a focused use case and small audience to test and refine your approach before scaling up.
### ๐ค **Agent Design**
**Be Specific:** Write detailed, specific prompts for your AI agents. The more precise your instructions, the better your results.
### ๐ **Insights Configuration**
**Ask Precise Questions:** Create very specific insights questions. Don't just ask "if customer is interested" - ask exactly what constitutes interest.
### ๐ง **Technical Setup**
**Test Everything:** Always test your configuration with sample calls before launching full campaigns.
***
## Industry Use Cases
Vodex.ai is optimized for various industries and scenarios:
**Sales Automation**
* Lead qualification and scoring
* Product demonstrations and presentations
* Follow-up calls and nurturing
* Appointment scheduling with prospects
**Support Automation**
* Customer inquiry handling
* Account status updates
* Service appointment scheduling
* Satisfaction surveys and feedback
**Financial Communications**
* Payment reminders and collections
* Account verification and updates
* Payment plan negotiations
* Compliance-focused communications
**Healthcare Communications**
* Appointment reminders and confirmations
* Insurance verification calls
* Patient follow-up and care coordination
* Prescription refill reminders
***
## Getting Help
### ๐ **Documentation Resources**
* Browse the complete documentation sections above
* Check [troubleshooting guides](/troubleshooting/common-issues) for common issues
* Review [best practices](/custom-fields/best-practices) for optimization tips
### ๐ฌ **Support Channels**
* **Email Support:** [support@vodex.ai](mailto:support@vodex.ai)
* **Response Time:** Within 24 hours during business days
* **Include:** Clear description, screenshots, and steps you've tried
### ๐ **Ready to Start?**
Follow our step-by-step quickstart guide to create and launch your first AI calling campaign.
***
## What's Next?
After reviewing this introduction:
1. **Explore the [Quickstart Guide](/quickstart)** for hands-on setup
2. **Learn [Prompt Design](/agents/prompt)** to create effective AI agents
3. **Configure [Call Settings](/call-settings/overview)** for optimal performance
4. **Set up [Insights](/insights/overview)** to track important metrics
5. **Review [Troubleshooting](/troubleshooting/common-issues)** for common solutions
**Ready to transform your voice operations?** This documentation provides everything you need to successfully implement and optimize AI-powered calling campaigns with Vodex.ai.
# โก Understanding Latency
Source: https://docs.vodex.ai/latency/understanding-latency
Comprehensive guide to understanding latencies across ASR, AI models, and TTS systems in Vodex
**What you'll learn:** Detailed breakdown of latencies across all Vodex system components including ASR, AI models, and TTS providers with performance characteristics and optimization notes.
Understanding latency is crucial for optimizing your AI calling campaigns. This guide provides comprehensive latency information for all system components to help you make informed decisions about your configuration.
***
## ASR (Automatic Speech Recognition) Latencies
Speech recognition is the first step in processing user input. Different ASR providers offer varying latency characteristics based on their processing approach.
### Streaming ASRs
Real-time speech recognition that processes audio as it's being spoken:
**Ultra-Low Latency Processing**
| Metric | Value |
| ------------------- | ---------------------------------------------- |
| **Base Latency** | 250ms |
| **Processing Type** | Streaming |
| **Best For** | Real-time conversations, interactive scenarios |
**Characteristics:**
* Fastest streaming ASR option
* Optimized for conversational AI
* Minimal delay in speech recognition
**Balanced Streaming Performance**
| Metric | Value |
| ------------------- | --------------------------------------------- |
| **Base Latency** | 300ms |
| **Processing Type** | Streaming |
| **Best For** | Standard voice interactions, customer service |
**Characteristics:**
* Reliable streaming performance
* Good balance of speed and accuracy
* Suitable for most use cases
**Streaming ASR Timing:** For streaming ASRs, we implement adaptive timing - either 300ms OR 1 second depending on user activity to prevent cutting off users mid-sentence.
### Non-Streaming ASRs
Batch processing ASRs that analyze complete audio segments:
**Enterprise-Grade Recognition**
| Metric | Value |
| ---------------------- | ------------- |
| **Processing Latency** | 2 seconds |
| **VAD Time** | 300ms (fixed) |
| **Total Latency** | \~2.3 seconds |
**Best for:** High-accuracy requirements, complex audio processing
**Advanced AI-Powered ASR**
| Metric | Value |
| ---------------------- | ------------- |
| **Processing Latency** | 700ms |
| **VAD Time** | 300ms (fixed) |
| **Total Latency** | \~1 second |
**Best for:** Multi-language support, challenging audio conditions
**Optimized Whisper Implementation**
| Metric | Value |
| ---------------------- | ------------- |
| **Processing Latency** | 400ms |
| **VAD Time** | 300ms (fixed) |
| **Total Latency** | \~700ms |
**Best for:** Fast Whisper processing, quality audio recognition
**Microsoft Cloud ASR**
| Metric | Value |
| ---------------------- | ------------- |
| **Processing Latency** | 800ms |
| **VAD Time** | 300ms (fixed) |
| **Total Latency** | \~1.1 seconds |
**Best for:** Enterprise integrations, Microsoft ecosystem
**Specialized Voice Recognition**
| Metric | Value |
| ---------------------- | ------------- |
| **Processing Latency** | 400ms |
| **VAD Time** | 300ms (fixed) |
| **Total Latency** | \~700ms |
**Best for:** Specialized voice processing, custom implementations
**Non-Streaming ASR Note:** All non-streaming ASRs include a fixed Voice Activity Detection (VAD) time of 300ms to ensure complete speech capture before processing.
***
## AI Model Latencies
Time to first token generation - the critical metric for conversational responsiveness.
**Important:** Listed latencies represent time to first token. Complete response generation typically adds +300ms from the first token delivery.
**Latency vs Capability Trade-off:** Lower latency models are typically smaller LLMs that cannot handle longer prompts, complex rules, or extensive context. Choose based on your specific use case requirements.
### Vodex Optimized Models
Specially tuned models optimized for voice conversations:
**Vodex Custom-Based Architecture**
| Model | First Token Latency | Status | Best For |
| -------------------- | ------------------- | -------- | ------------------------------------------- |
| **Spark** | 1.5s | โ
Stable | Complex reasoning, detailed conversations |
| **Spark Flash** | 400ms | โ
Stable | Balanced performance, standard interactions |
| **Spark Flash Lite** | 200ms | โ
Stable | Quick responses, simple tasks |
**Performance Characteristics:**
* Optimized for voice conversations
* Excellent reasoning capabilities
* Consistent performance across scenarios
**Spark Model Selection Guide**
**Best for complex scenarios**
* Sales conversations requiring detailed reasoning
* Multi-step problem solving
* Technical support discussions
* **Trade-off:** Higher latency for better reasoning
**Balanced performance**
* Customer service interactions
* Standard business conversations
* Appointment scheduling
* **Sweet spot:** Good balance of speed and capability
**Ultra-fast responses**
* Simple confirmations
* Quick surveys
* Basic information gathering
* **Advantage:** Minimal latency for simple tasks
* **Limitation:** Cannot handle complex prompts or extensive context
### OpenAI Models
Industry-leading AI models with varying performance characteristics:
**Advanced Reasoning Models**
| Model | First Token Latency | Status | Characteristics |
| ---------------- | ------------------- | -------- | ------------------------------------------- |
| **GPT-4o** | 800ms | โ
Stable | Multimodal capabilities, advanced reasoning |
| **GPT-4o Mini** | 500ms | โ
Stable | Efficient multimodal processing |
| **GPT-4.1 Mini** | 500ms | โ
Stable | Enhanced efficiency, cost-effective |
**Best for:** Complex conversations, detailed analysis, multimodal interactions
**Cutting-Edge AI Models**
| Model | First Token Latency | Status | Characteristics |
| -------------- | ------------------- | ----------------- | ------------------------------------------- |
| **GPT-5 Nano** | 350ms | โ ๏ธ Latency issues | Ultra-efficient processing, limited context |
| **GPT-5 Mini** | 200ms | โ ๏ธ Latency issues | Fast responses, simplified reasoning |
| **GPT-5 Chat** | 500ms | โ
Stable | Optimized for conversations |
**GPT-5 Status:** GPT-5 Nano and Mini are currently experiencing latency issues. Monitor performance closely if using these models.
**Purpose-Built AI Solutions**
| Model | First Token Latency | Status | Characteristics |
| -------------- | ------------------- | -------- | ------------------------------------- |
| **OpenAI GSS** | 1.2s | โ
Stable | Specialized processing, high accuracy |
**Best for:** Specialized applications requiring high accuracy
### Open Source & Alternative Models
High-performance alternatives to proprietary models:
**Open Source Excellence**
| Model | First Token Latency | Status | Characteristics |
| -------------------- | ------------------- | -------- | ------------------------------------------ |
| **Llama 3.3 70B** | 450ms | โ
Stable | Large parameter model, excellent reasoning |
| **Llama 4 Maverick** | 450ms | โ
Stable | Next-generation open source |
**Advantages:**
* Open source flexibility
* Privacy-focused processing
* Customizable implementations
* Cost-effective scaling
**High-Performance Alternative**
| Model | First Token Latency | Status | Characteristics |
| ----------------- | ------------------- | -------- | ---------------------------------------- |
| **Deepseek v3.1** | 300ms | โ
Stable | Fast processing, competitive performance |
**Benefits:**
* Excellent speed-to-performance ratio
* Reliable processing
* Cost-effective option
***
## TTS (Text-to-Speech) Latencies
Time to first audio chunk - critical for maintaining conversation flow.
**TTS Streaming:** All TTS providers support streaming, allowing audio playback to begin as soon as the first chunk is available, reducing perceived latency.
### ElevenLabs (Default Provider)
Premium AI voice synthesis with multiple performance tiers:
**High-Quality Voice Synthesis**
| Model | First Chunk Latency | Quality | Best For |
| ------------- | ------------------- | -------- | -------------------------------------------- |
| **Turbo 2** | 250ms | High | Professional conversations, customer service |
| **Turbo 2.5** | 250ms | Enhanced | Premium voice quality, sales calls |
**Characteristics:**
* Premium voice quality
* Natural emotional expression
* Multiple voice personalities
* Excellent for professional use
**Ultra-Fast Voice Generation**
| Model | First Chunk Latency | Quality | Best For |
| ------------- | ------------------- | -------- | ---------------------------------------------- |
| **Flash 2** | 95ms | Good | Real-time conversations, interactive scenarios |
| **Flash 2.5** | 95ms | Enhanced | Fast interactions with improved quality |
**Advantages:**
* Ultra-low latency
* Real-time conversation capability
* Optimized for speed
* Maintains good voice quality
**Advanced Multi-Language Support**
| Model | First Chunk Latency | Quality | Best For |
| ------------------- | ------------------- | ------- | ----------------------------------------- |
| **Multilingual V2** | 1.2s | High | Multi-language campaigns, global outreach |
**Characteristics:**
* Advanced multilingual capabilities
* High-quality voice synthesis across languages
* Optimized for international campaigns
* Supports diverse language requirements
**Trade-off:**
* Higher latency for comprehensive language support
* Best when language quality is more important than speed
**ElevenLabs Selection:** Use Flash series for real-time interactions where speed is critical, and Turbo series for professional scenarios where voice quality is paramount.
### Alternative TTS Providers
Additional voice synthesis options for specialized needs:
**Advanced Voice Technology**
| Metric | Value |
| ----------------------- | --------------- |
| **First Chunk Latency** | 350ms |
| **Quality** | High |
| **Availability** | Contact support |
**Best for:**
* Specialized voice requirements
* Custom voice training
* Enterprise implementations
**WaveNet Technology**
| Metric | Value |
| ----------------------- | --------------- |
| **First Chunk Latency** | 400ms |
| **Quality** | Ultra-realistic |
| **Availability** | Contact support |
**Best for:**
* Ultra-realistic voice requirements
* Multi-language campaigns
* Google Cloud integrations
**Microsoft Neural Voices**
| Metric | Value |
| ----------------------- | ---------------- |
| **First Chunk Latency** | 800ms |
| **Quality** | Enterprise-grade |
| **Availability** | Contact support |
**Best for:**
* Enterprise applications
* Microsoft ecosystem integration
* Multi-language support
***
## Latency Optimization Strategies
### Configuration Recommendations
**Ultra-Low Latency Setup**
**Recommended Configuration:**
* **ASR:** Alpha Echo V2 (250ms)
* **Model:** Spark Flash Lite (200ms) or GPT-5 Mini (200ms)\*
* **TTS:** ElevenLabs Flash 2.5 (95ms)
**Total Pipeline Latency:** \~545ms
**Limitations:** Ultra-low latency models cannot handle complex prompts, extensive context, or sophisticated rules. Best for simple, straightforward interactions only.
\*GPT-5 Mini currently experiencing latency issues
**Speed-Quality Balance**
**Recommended Configuration:**
* **ASR:** Nova Echo (300ms)
* **Model:** Spark Flash (400ms) or GPT-4o Mini (500ms)
* **TTS:** ElevenLabs Turbo 2.5 (250ms)
**Total Pipeline Latency:** \~950ms - 1050ms
**Premium Quality Setup**
**Recommended Configuration:**
* **ASR:** OpenAI Whisper (700ms + 300ms VAD)
* **Model:** Spark (1.5s) or GPT-4o (800ms)
* **TTS:** ElevenLabs Turbo 2.5 (250ms)
**Total Pipeline Latency:** \~1.8s - 2.25s
### Performance Monitoring
**Establish Performance Baselines**
* Monitor end-to-end conversation latency
* Track component-specific performance
* Document peak and average response times
**A/B Test Configurations**
* Compare different ASR providers
* Test various AI model combinations
* Evaluate TTS provider performance
**Ongoing Performance Tracking**
* Set up latency alerts
* Monitor for performance degradation
* Track user experience metrics
***
## Technical Considerations
### Latency Factors
**External Factors**
* Geographic distance to servers
* Network congestion and routing
* Internet service provider performance
* CDN and edge server optimization
**System Performance**
* Server capacity and utilization
* Concurrent request handling
* Model loading and initialization
* Resource allocation efficiency
**Input Characteristics**
* Audio sample rate and quality
* Background noise levels
* Speaker clarity and volume
* Connection stability
### Best Practices
**Speech Recognition Best Practices**
* Choose streaming ASR for real-time scenarios
* Consider non-streaming for accuracy-critical applications
* Account for VAD timing in latency calculations
* Test with representative audio samples
**AI Model Optimization**
* Match model complexity to use case requirements
* Monitor for model-specific latency issues
* Consider fallback options for unstable models
* Balance reasoning capability with response speed
**Voice Synthesis Optimization**
* Use streaming TTS for reduced perceived latency
* Select voice quality appropriate for use case
* Consider multiple TTS providers for redundancy
* Test voice quality across different scenarios
***
## Next Steps
**Ready to optimize your latency?** Use this comprehensive guide to select the optimal configuration for your specific use case and performance requirements.
**Recommended Actions:**
1. **Assess your requirements** - Determine if you need real-time, balanced, or high-quality processing
2. **Test configurations** - Experiment with different component combinations
3. **Monitor performance** - Track latency metrics in production
4. **Optimize iteratively** - Continuously refine based on real-world performance
**Need help with configuration?** Contact [support@vodex.ai](mailto:support@vodex.ai) for personalized latency optimization assistance.
***
## Related Configuration Settings
Configure these latency-related settings in your Vodex dashboard:
**Speech Recognition Settings**
Configure ASR providers and settings in [Call Settings](/call-settings/overview) and [Advanced Settings](/call-settings/advanced-settings).
* Choose between streaming and non-streaming ASR
* Configure language codes and detection
* Set up custom ASR parameters
**Model Configuration**
Select and configure AI models in [Call Settings](/call-settings/overview).
* Choose from Vodex optimized models
* Configure OpenAI, Llama, and other providers
* Balance latency vs capability requirements
**Text-to-Speech Configuration**
Configure voice providers and settings in [Call Settings](/call-settings/overview).
* Select ElevenLabs Turbo or Flash series
* Configure alternative TTS providers
* Optimize voice quality vs speed
# ๐ฌ๐ซ Messaging overview
Source: https://docs.vodex.ai/messaging/on-call-messaging
Configure automated messaging during AI calls using your own SMS, WhatsApp, and email providers
**What you'll learn:** How to configure automated messaging during AI calls using your own messaging providers to send SMS, WhatsApp messages, and emails with static content.
## Overview
The messaging feature allows your AI agent to automatically send messages during calls using your own messaging service providers. This is useful for sending confirmations, appointment details, links, or other important information while the conversation is happening.
**Important:** These messages are **static/fixed content only**. You must provide your own SMS, WhatsApp, and email service providers through cURL integration.
***
## Configuration Setup
### Messaging Section Location
In every project, you'll find the messaging configuration in the **Messaging Section** with three input fields:
1. **SMS Provider cURL**
2. **WhatsApp Provider cURL**
3. **Email Provider cURL**
### Provider Requirements
**You must provide:**
* Your own SMS service provider (Twilio, AWS SNS, etc.)
* Your own WhatsApp Business API provider
* Your own email service provider (SendGrid, Mailgun, etc.)
**Vodex does not provide these messaging services - only the integration capability.**
***
## SMS Configuration
### SMS Provider Setup
Configure your SMS provider by entering the complete cURL command in the SMS field.
```bash Example SMS cURL (Twilio) theme={null}
curl -X POST "https://api.twilio.com/2010-04-01/Accounts/YOUR_ACCOUNT_SID/Messages.json" \
-u "YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN" \
-d "From=+1234567890" \
-d "To={PhoneNum}" \
-d "Body=Your appointment is confirmed for tomorrow at 10 AM. Please arrive 15 minutes early."
```
```bash Example SMS cURL (AWS SNS) theme={null}
curl -X POST "https://sns.us-east-1.amazonaws.com/" \
-H "Authorization: AWS4-HMAC-SHA256 Credential=YOUR_ACCESS_KEY/..." \
-H "Content-Type: application/x-amz-json-1.0" \
-H "X-Amz-Target: AmazonSNS.Publish" \
-d '{
"PhoneNumber": "{PhoneNum}",
"Message": "Your appointment is confirmed for tomorrow at 10 AM."
}'
```
### SMS Field Mapping
**Phone Number Field:** Use `{PhoneNum}` as the placeholder for the recipient's phone number in your cURL command.
| Field | Placeholder | Description |
| ------------------- | ------------ | ----------------------------------------------------- |
| **Recipient Phone** | `{PhoneNum}` | Automatically replaced with the caller's phone number |
| **Message Content** | Static text | Fixed message content (cannot be dynamic) |
***
## WhatsApp Configuration
### WhatsApp Provider Setup
Configure your WhatsApp Business API provider with the complete cURL command.
```bash Example WhatsApp cURL (WhatsApp Business API) theme={null}
curl -X POST "https://graph.facebook.com/v17.0/YOUR_PHONE_NUMBER_ID/messages" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "{PhoneNum}",
"type": "text",
"text": {
"body": "Hello! Your appointment is confirmed for tomorrow at 10 AM. We look forward to seeing you."
}
}'
```
```bash Example WhatsApp cURL (Third-party Provider) theme={null}
curl -X POST "https://api.your-whatsapp-provider.com/v1/messages" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "{PhoneNum}",
"message": "Your appointment is confirmed for tomorrow at 10 AM."
}'
```
### WhatsApp Field Mapping
**Phone Number Field:** Use `{PhoneNum}` as the placeholder for the recipient's WhatsApp number in your cURL command.
| Field | Placeholder | Description |
| ------------------- | ------------ | ----------------------------------------------------- |
| **Recipient Phone** | `{PhoneNum}` | Automatically replaced with the caller's phone number |
| **Message Content** | Static text | Fixed message content (cannot be dynamic) |
***
## Email Configuration
### Email Provider Setup
Configure your email service provider with the complete cURL command.
**Email Field Requirement:** You must upload the `email` custom field in your audience list or include it in the API payload when triggering calls via API.
```bash Example Email cURL (SendGrid) theme={null}
curl -X POST "https://api.sendgrid.com/v3/mail/send" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"personalizations": [{
"to": [{"email": "{email}"}],
"subject": "Appointment Confirmation"
}],
"from": {"email": "noreply@yourcompany.com"},
"content": [{
"type": "text/plain",
"value": "Your appointment is confirmed for tomorrow at 10 AM. Please arrive 15 minutes early."
}]
}'
```
```bash Example Email cURL (Mailgun) theme={null}
curl -X POST "https://api.mailgun.net/v3/YOUR_DOMAIN/messages" \
-u "api:YOUR_API_KEY" \
-F "from=noreply@yourcompany.com" \
-F "to={email}" \
-F "subject=Appointment Confirmation" \
-F "text=Your appointment is confirmed for tomorrow at 10 AM."
```
### Email Field Mapping
**Email Field:** Use `{email}` as the placeholder for the recipient's email address in your cURL command.
| Field | Placeholder | Description |
| ------------------- | ----------- | ------------------------------------------------ |
| **Recipient Email** | `{email}` | Must be provided in audience data or API payload |
| **Email Content** | Static text | Fixed email content (cannot be dynamic) |
### Email Data Requirements
**Include Email in Audience List**
* Add an `email` column to your audience CSV
* Ensure all contacts have valid email addresses
* Upload the audience with email data included
**Include Email in API Payload**
* Add `email` field to your API request payload
* Ensure the email address is valid and properly formatted
* Include it in the custom fields section
***
## Important Limitations and Warnings
### Email Collection Limitations
**Email Collection Not Recommended:** Our AI agents can capture emails during calls, but they cannot send emails to those specific captured emails. We strongly advise against collecting emails during calls due to:
* **Accent recognition issues** - Different pronunciations cause errors
* **Alphabet identification problems** - Spelling out emails is error-prone
* **Customer frustration** - Repeated spelling attempts irritate callers
* **Time consumption** - Email collection significantly extends call duration
### Static Message Limitation
**Static Messages Only:** All messages (SMS, WhatsApp, Email) are completely static and cannot include dynamic content from the conversation. The message content is fixed at configuration time.
### Provider Responsibility
**Your Providers Required:** Vodex does not provide SMS, WhatsApp, or email services. You must:
* Set up your own messaging service accounts
* Handle provider billing and limits
* Ensure compliance with provider terms of service
* Manage delivery rates and failures
***
## Best Practices
### Message Content Guidelines
**SMS Message Guidelines:**
* Keep messages under 160 characters when possible
* Include clear call-to-action or next steps
* Add your company name for identification
* Include opt-out instructions if required by regulations
**Example:** "ABC Company: Your appointment is confirmed for Jan 15 at 2 PM. Reply STOP to opt out."
**WhatsApp Message Guidelines:**
* Use conversational, friendly tone
* Include relevant emojis if appropriate
* Keep messages concise but informative
* Follow WhatsApp Business Policy guidelines
**Example:** "Hi! ๐ Your appointment with ABC Company is confirmed for Jan 15 at 2 PM. See you soon!"
**Email Message Guidelines:**
* Use clear, descriptive subject lines
* Include complete information in the body
* Add your company contact information
* Follow email marketing compliance rules
**Example Subject:** "Appointment Confirmation - ABC Company"
### Technical Implementation Tips
**Testing Recommendation:** Test your cURL commands independently before adding them to Vodex to ensure they work correctly with your providers.
**Error Handling:** Configure your messaging providers with appropriate error handling and retry logic for failed deliveries.
**Rate Limits:** Be aware of your messaging provider's rate limits and plan your call volume accordingly.
***
## Troubleshooting
### Common Issues
| Issue | Cause | Solution |
| --------------------------------- | ------------------------------ | -------------------------------------- |
| **Messages not sending** | Incorrect cURL syntax | Test cURL command independently |
| **Wrong phone number format** | Missing {PhoneNum} placeholder | Use exact placeholder: `{PhoneNum}` |
| **Email not found** | Missing email in audience/API | Ensure email field is included in data |
| **Provider authentication error** | Invalid API keys/tokens | Verify provider credentials |
### Testing Your Setup
**Verify Provider Integration**
* Test each cURL command in terminal/command prompt
* Replace placeholders with actual test data
* Confirm messages are delivered successfully
**Integration Testing**
* Configure cURL commands in Vodex messaging section
* Run test calls with known phone numbers/emails
* Verify messages are triggered during calls
**Check Provider Dashboards**
* Monitor delivery rates in provider dashboards
* Check for failed deliveries or errors
* Adjust configuration if needed
***
## Next Steps
After configuring messaging:
1. **Set up your messaging providers** and obtain API credentials
2. **Test cURL commands** independently to ensure they work
3. **Configure the messaging section** in your Vodex project
4. **Test with sample calls** to verify integration
5. **Monitor delivery rates** and adjust as needed
**Ready to send messages during calls?** Proper messaging configuration enables automated follow-up and confirmation delivery, enhancing your customer experience and reducing manual work.
***
**Need help with call settings?** Check out our [Call Settings Overview](/call-settings/overview) and [Advanced Settings](/call-settings/advanced-settings) for comprehensive call configuration guidance.
# ๐ Security & Compliance Overview
Source: https://docs.vodex.ai/security/overview
Comprehensive overview of Vodex security protocols, certifications, and data protection mechanisms
**Enterprise-Grade Security:** Vodex maintains the highest standards of data security through multiple industry-recognized certifications and robust security protocols.
Vodex is committed to maintaining the highest standards of data security and compliance. We have achieved several key certifications and implement comprehensive security measures to protect your sensitive data and AI communications.
***
## ๐ Security Certifications & Compliance
### HIPAA Compliance
**Protected Health Information (PHI) Security**
Vodex ensures the confidentiality and security of protected health information, adhering to stringent healthcare data protection standards.
**Key Features:**
* Complete PHI confidentiality and security
* Healthcare industry's most rigorous data protection requirements
* Patient privacy guarantees for medical AI applications
* Business Associate Agreement (BAA) support for healthcare clients
### SOC 2 Type II Certification
**Comprehensive Security Framework**
Demonstrates our commitment to managing customer data based on five trust service principles.
**The Five Pillars:**
* **Security** - Robust protection against unauthorized access
* **Availability** - Reliable system uptime and accessibility
* **Processing Integrity** - Accurate and complete data processing
* **Confidentiality** - Protection of sensitive information
* **Privacy** - Proper collection, use, and disposal of personal data
### ISO 27001 Certification
**International Security Standard**
Specifies requirements for establishing, implementing, maintaining, and continually improving an information security management system.
**Key Components:**
* Systematic approach to managing sensitive information
* Risk management and threat mitigation
* Continuous improvement of security protocols
* International recognition and compliance
***
## ๐ก๏ธ Data Encryption & Security Mechanisms
### Data at Rest Encryption
**Military-Grade Data Protection**
**Advanced Encryption Standard (AES-256):**
* Industry-standard encryption with 256-bit keys
* Same encryption level used by government and military organizations
* Computationally infeasible to break with current technology
* FIPS 140-2 validated encryption modules
**Protected Data Includes:**
* Call recordings and transcripts
* Customer information and profiles
* AI model configurations and prompts
* Analytics and insights data
* Custom fields and audience data
**Secure Data Storage Practices**
**Storage Protection Features:**
* Encrypted databases with automatic key rotation
* Secure backup systems with encrypted storage
* Geographic distribution with redundancy
* Access logging and audit trails
* Secure deletion and data lifecycle management
### Data in Transit Encryption
**Secure Data Transmission**
**TLS Protocol Implementation:**
* Latest TLS 1.3 protocols for maximum security
* End-to-end encryption from client to server
* Perfect Forward Secrecy (PFS) for session protection
* Certificate pinning for additional security
**Encrypted Communications:**
* All API calls and data transfers
* Real-time call processing and AI responses
* Dashboard and web interface access
* Inter-service communication within infrastructure
**Comprehensive Network Protection**
**Security Layers:**
* SSL/TLS certificates for authenticated connections
* Web Application Firewall (WAF) protection
* DDoS protection and mitigation
* Intrusion detection and prevention systems
* Network segmentation and isolation
***
## ๐ Data Transfer Protocols
### RESTful APIs
**Security-First API Architecture**
Our APIs are designed with security as a fundamental principle, incorporating multiple layers of protection:
**Authentication Mechanisms:**
* API key authentication with secure key management
* OAuth 2.0 support for enterprise integrations
* Token-based access control with expiration
* Multi-factor authentication for administrative access
**Communication Security:**
* All endpoints use HTTPS/TLS encryption
* Request signing and validation
* Rate limiting and abuse protection
* Input sanitization and validation
### API Security Features
**Multi-Layer Access Control**
**Authentication Methods:**
* API key authentication with rotation policies
* OAuth 2.0 for third-party integrations
* JWT tokens with secure signing algorithms
* Role-based access control (RBAC)
**Authorization Features:**
* Granular permission management
* Resource-level access control
* Time-based access restrictions
* IP whitelisting and geographic restrictions
**Comprehensive API Protection**
**Security Controls:**
* Rate limiting to prevent abuse and DDoS attacks
* Input validation and sanitization for all data
* SQL injection and XSS protection
* CORS (Cross-Origin Resource Sharing) policies
* Secure error handling that doesn't expose sensitive information
**Monitoring & Logging:**
* Complete audit logging of all API access
* Real-time threat detection and response
* Anomaly detection for unusual access patterns
* Automated security incident alerts
***
## ๐๏ธ Infrastructure Security
### Cloud Security Architecture
**Secure, Compliant Hosting**
**Infrastructure Features:**
* Enterprise-grade cloud platforms with compliance certifications
* Geographic distribution across multiple secure data centers
* Physical security with biometric access controls
* Environmental monitoring and disaster protection
* 99.9% uptime SLA with redundant systems
**Backup & Recovery:**
* Regular encrypted backups with secure retention policies
* Geographic backup distribution for disaster recovery
* Point-in-time recovery capabilities
* Automated backup testing and validation
**Zero Trust Security Model**
**Network Security:**
* Zero Trust architecture - verify every access request
* Network segmentation with isolated environments
* Virtual Private Cloud (VPC) with security groups
* Intrusion detection and prevention systems
* 24/7 security monitoring and incident response
**Access Control:**
* VPN access for authorized personnel only
* Multi-factor authentication for all administrative access
* Privileged access management (PAM) systems
* Regular access reviews and permission audits
***
## ๐ Data Protection Practices
### Privacy by Design
**Fundamental Privacy Principles**
**Data Minimization:**
* Collect only necessary data for specified purposes
* Purpose limitation - data used only for legitimate business needs
* Automatic data retention and deletion policies
* User consent management and preference controls
**User Rights Support:**
* Data subject access requests (GDPR Article 15)
* Right to rectification and data portability
* Right to erasure (right to be forgotten)
* Data processing transparency and reporting
### Access Management
**Comprehensive Access Control**
**Access Principles:**
* Principle of least privilege - minimum necessary access
* Role-based access control with granular permissions
* Regular access reviews and recertification
* Automated provisioning and deprovisioning
**Authentication Requirements:**
* Multi-factor authentication (MFA) for all users
* Strong password policies and rotation
* Single Sign-On (SSO) integration support
* Biometric authentication for critical systems
**Elevated Access Security**
**Administrative Controls:**
* Privileged access management (PAM) systems
* Just-in-time access for administrative tasks
* Session recording and monitoring for privileged users
* Emergency access procedures with full audit trails
**Security Monitoring:**
* Real-time monitoring of privileged account activities
* Automated alerts for suspicious administrative actions
* Regular privilege escalation reviews
* Segregation of duties for critical operations
***
## ๐ Monitoring & Incident Response
### Real-Time Security Monitoring
**24/7 Security Monitoring**
**Continuous Monitoring:**
* Security Information and Event Management (SIEM) systems
* AI-powered threat detection and analysis
* Real-time anomaly detection and alerting
* Behavioral analysis for insider threat detection
**Threat Intelligence:**
* Integration with global threat intelligence feeds
* Proactive threat hunting and investigation
* Vulnerability scanning and assessment
* Security metrics and KPI tracking
**Structured Security Response**
**Response Capabilities:**
* 24/7 incident response team availability
* Documented incident response procedures
* Forensic analysis and investigation tools
* Communication protocols for stakeholder notification
**Recovery Procedures:**
* Business continuity and disaster recovery plans
* Automated failover and recovery systems
* Regular disaster recovery testing and validation
* Post-incident analysis and improvement processes
***
## ๐ฏ Industry-Specific Security
### Healthcare Compliance (HIPAA)
**Healthcare Data Protection**
**HIPAA Safeguards:**
* Administrative safeguards with workforce training
* Physical safeguards for data center and equipment security
* Technical safeguards including access controls and audit logs
* Business Associate Agreements (BAA) for healthcare clients
**PHI Protection:**
* Comprehensive audit trails for all PHI access
* Data minimization for healthcare information processing
* Secure PHI transmission and storage
* Proper PHI disposal and destruction procedures
### Enterprise Security (SOC 2)
**Enterprise Security Standards**
**Control Implementation:**
* Comprehensive security control frameworks
* Regular independent third-party audits
* Continuous monitoring and compliance validation
* Risk assessment and mitigation strategies
**Vendor Management:**
* Secure evaluation of third-party services
* Ongoing monitoring of vendor security practices
* Contractual security requirements for suppliers
* Supply chain risk management
***
## ๐ Continuous Security Improvement
### Security Development Lifecycle
**Continuous Improvement Process**
**Regular Updates:**
* Timely application of security patches and updates
* Regular technology upgrades and modernization
* Proactive vulnerability management
* Security architecture reviews and improvements
**Training & Awareness:**
* Ongoing security awareness training for all personnel
* Regular security simulations and testing
* Security best practices documentation and updates
* Industry conference participation and knowledge sharing
**Regulatory Compliance Management**
**Audit & Assessment:**
* Scheduled compliance assessments and certifications
* Gap analysis and remediation planning
* Internal and external security audits
* Compliance reporting and documentation
**Stakeholder Communication:**
* Regular security posture reporting
* Transparency in security practices and improvements
* Customer security questionnaire support
* Security incident communication protocols
***
## ๐ Security Compliance Summary
### Certifications Achieved
| Certification | Description | Scope |
| ----------------- | ------------------------------- | ----------------------------------------------------------- |
| **HIPAA** | Healthcare data protection | PHI confidentiality and security |
| **SOC 2 Type II** | Trust service principles | Security, availability, integrity, confidentiality, privacy |
| **ISO 27001** | Information security management | Comprehensive ISMS framework |
### Encryption Standards
| Data State | Encryption Method | Key Details |
| ---------------------- | ----------------- | ----------------------------------------------------- |
| **Data at Rest** | AES-256 | Military-grade encryption with automatic key rotation |
| **Data in Transit** | TLS 1.3 | Perfect Forward Secrecy with certificate pinning |
| **API Communications** | HTTPS/TLS | End-to-end encryption for all API calls |
### Security Monitoring
| Component | Coverage | Response Time |
| --------------------- | --------------------- | --------------------------- |
| **SOC Monitoring** | 24/7 real-time | Immediate alert response |
| **Threat Detection** | AI-powered analysis | Automated threat mitigation |
| **Incident Response** | Structured procedures | 1 hour initial response |
***
## ๐ค Trust & Transparency
### Security Partnerships
**Security Ecosystem Participation**
Vodex actively participates in the security community through:
* Industry security forums and working groups
* Threat intelligence sharing initiatives
* Security research and best practice development
* Collaboration with security vendors and partners
### Customer Security Support
**Dedicated Security Support**
**Available Services:**
* Security questionnaire completion assistance
* Compliance documentation and certificates
* Security architecture reviews and consultations
* Custom security requirement discussions
**Contact Information:**
* **Security Team:** [support@vodex.ai](mailto:support@vodex.ai)
* **Compliance Queries:** [support@vodex.ai](mailto:support@vodex.ai)
* **Emergency Security:** 24/7 incident response hotline
**Transparency & Documentation**
**Available Reports:**
* SOC 2 Type II reports for enterprise customers
* Security compliance certificates and attestations
* Third-party penetration testing summaries
* Security posture and improvement reports
**Regular Updates:**
* Quarterly security newsletter
* Annual security and compliance report
* Incident transparency reports (when applicable)
* Security feature updates and enhancements
***
**Enterprise-Grade Security Guaranteed:** Vodex's comprehensive security framework ensures that your sensitive data and AI communications are protected by the highest industry standards, from military-grade encryption to continuous compliance monitoring.
***
**Security Questions?** Contact our security team at [security@vodex.ai](mailto:security@vodex.ai) for detailed security documentation, compliance certificates, or to discuss specific security requirements for your implementation.
# ๐ ๏ธ Troubleshooting Guide
Source: https://docs.vodex.ai/troubleshooting/common-issues
Common issues and solutions when using Vodex AI calling platform
**Quick Help:** Find solutions to the most common issues encountered while using Vodex AI calling platform. Each issue includes the cause and step-by-step resolution.
## Common Issues and Solutions
### 1. Something Went Wrong While Triggering Calls
**Error Message:** "Something went wrong while triggering calls"
#### **Root Cause**
This error occurs when the `time_zone` field is not properly formatted or contains invalid timezone information.
#### **Solution**
Ensure your `time_zone` field uses one of these valid formats:
| โ
**Correct Format** | โ **Incorrect Format** |
| -------------------- | ---------------------- |
| `Asia/Kolkata` | `IST` |
| `America/New_York` | `EST` |
| `+05:30` | `+5:30` |
| `-08:00` | `PST` |
#### **How to Fix**
1. **Check your time zone format** in the custom fields
2. **Use IANA timezone names** like `Asia/Kolkata` or `America/New_York`
3. **Use UTC offset format** like `+05:30` or `-08:00`
4. **Avoid abbreviations** like IST, EST, PST
```json Correct Time Zone Examples theme={null}
{
"time_zone": "Asia/Kolkata"
}
```
```json Alternative UTC Format theme={null}
{
"time_zone": "+05:30"
}
```
***
### 2. Missing Custom Field Error
**Error Message:** "Missing custom field but no custom field is showing"
#### **Root Cause**
This error occurs when custom field names contain spaces, which breaks the field recognition system.
#### **The Problem**
Custom fields with spaces in their names cannot be processed by the system:
```
โ Wrong: {First Name}
โ Wrong: {Account Number}
โ Wrong: {Payment Amount}
```
#### **The Solution**
Replace spaces with underscores in all custom field names:
```
โ
Correct: {FirstName}
โ
Correct: {Account_Number}
โ
Correct: {Payment_Amount}
```
#### **Step-by-Step Fix**
1. **Identify fields with spaces** in your prompt
2. **Replace all spaces with underscores**
3. **Update your data source** to match the new field names
4. **Test the updated prompt** before going live
**Pro Tip:** Use `PascalCase` (`{FirstName}`) throughout your system to avoid confusion.
***
### 3. Call Limit Exceeded Error
**Error Message:** "Call Limit exceeded, please upgrade"
#### **Root Cause**
Free-tier customers have a limited number of calls available when using Vodex's default Twilio integration.
#### **Available Solutions**
**Option 1: Upgrade Your Plan**
Contact our support team to discuss upgrading your plan for higher call limits:
* **Email:** [support@vodex.ai](mailto:support@vodex.ai)
* **Subject:** "Call Limit Upgrade Request"
* **Include:** Your account details and expected call volume
**Option 2: Use Your Own Twilio Account**
Integrate your own Twilio account to remove call limits:
1. **Get Twilio credentials** from your Twilio dashboard
2. **Navigate to Settings** in your Vodex dashboard
3. **Add Twilio integration** with your credentials
4. **Test the connection** before running campaigns
#### **Prevention Tips**
* **Monitor your usage** regularly in the dashboard
* **Plan campaigns** according to your call limits
* **Consider upgrading** before reaching limits during important campaigns
***
### 4. Bot Not Speaking Customer Names
**Issue:** "Bot is not speaking the name of the customer in the call, but I have uploaded FirstName correctly"
#### **Root Cause**
The customer name data may not be properly uploaded or formatted in your audience list.
#### **Troubleshooting Steps**
1. **Open your audience list** in the Vodex dashboard
2. **Check the FirstName column** for the specific contacts
3. **Look for empty cells** or formatting issues
4. **Verify data is visible** in the preview
1. **Confirm field names match** between your prompt and audience data
2. **Ensure no extra spaces** in field names
3. **Verify case sensitivity** (FirstName vs firstname)
1. **Create a test contact** with a simple name
2. **Run a test call** to verify the field works
3. **Compare working vs non-working entries**
If the issue persists after verification:
* **Email:** [support@vodex.ai](mailto:support@vodex.ai)
* **Include:** Screenshot of your audience data
* **Provide:** Sample prompt and field names used
#### **Common Data Issues**
| **Problem** | **Solution** |
| --------------------------- | ----------------------------------------------- |
| Empty name fields | Fill in missing data or use fallback text |
| Special characters in names | Remove or replace special characters |
| Inconsistent formatting | Standardize name format across all entries |
| Wrong column mapping | Ensure column headers match field names exactly |
***
## Quick Diagnostic Checklist
Use this checklist to quickly identify and resolve common issues:
* [ ] Time zone format is correct (`Asia/Kolkata` or `+05:30`)
* [ ] No spaces in custom field names
* [ ] All required fields are populated
* [ ] Prompt syntax is correct
* [ ] Account has sufficient call credits
* [ ] Field names use underscores instead of spaces
* [ ] Field names match exactly between prompt and data
* [ ] Data is properly uploaded to audience list
* [ ] No special characters in field names
* [ ] Consistent naming convention used
* [ ] Customer data is properly formatted
* [ ] Field mapping is correct
* [ ] Test calls work with sample data
* [ ] No empty or null values in critical fields
***
## Getting Additional Help
### **Before Contacting Support**
Gather this information to help us assist you faster:
1. **Error message** (exact text or screenshot)
2. **Steps to reproduce** the issue
3. **Sample data** that's causing problems
4. **Prompt content** you're using
5. **Account information** and project details
### **Contact Information**
**Email:** [support@vodex.ai](mailto:support@vodex.ai)
**Response Time:** Within 24 hours during business days
**Include in your message:**
* Clear description of the issue
* Screenshots or error messages
* Steps you've already tried
### **Community Resources**
* **Documentation:** Browse our complete guides and API reference
* **Best Practices:** Learn from our recommended approaches
* **Updates:** Stay informed about new features and fixes
***
## Prevention Best Practices
### **Avoid Common Mistakes**
**Field Naming:** Always use underscores instead of spaces in custom field names from the start.
**Time Zones:** Use standard IANA timezone names or proper UTC offset formats.
**Data Quality:** Regularly audit your audience data for completeness and accuracy.
**Testing:** Always test with sample data before running full campaigns.
### **Regular Maintenance**
* **Review error logs** weekly to catch recurring issues
* **Update field mappings** when changing data sources
* **Monitor call limits** and upgrade proactively
* **Keep audience data** clean and up-to-date
**Issue Resolved?** Most common issues can be resolved by following the solutions above. If you're still experiencing problems, don't hesitate to contact our support team for personalized assistance.
***
**Need more help with custom fields?** Check out our [Custom Fields Introduction](/custom-fields/introduction) and [Best Practices](/custom-fields/best-practices) guides for comprehensive information.
# Business Verification
Source: https://docs.vodex.ai/twilio-verification/business-verification
Learn how to verify your business with Twilio in simple, easy-to-understand terms
## What is Business Verification?
Business Verification is like getting a "phone license" for your company. Just like you need a driver's license to drive a car, your business needs to be verified to use Twilio's phone services.
**Simple explanation:** It's Twilio's way of checking that your business is real and legitimate before letting you make calls or send messages.
## Why Do You Need It?
### ๐ก๏ธ It's Required by Law
Many countries have rules that say businesses must prove who they are before using phone services. This helps prevent scams and fraud.
### ๐ Better Call Success
When your business is verified, people are more likely to answer your calls because they know you're a real company.
### ๐ซ Avoid Getting Blocked
Unverified businesses often get their calls blocked or marked as spam. Verification helps prevent this.
## How Does It Work?
Think of it like applying for a credit card:
1. **You fill out forms** with your business information
2. **Twilio checks** that everything is correct and legitimate
3. **You get approved** and can use their services
4. **You get a badge** that shows you're verified
## What Information Do You Need?
### Basic Business Info
* **Business Name:** What your company is called
* **Business Address:** Where your company is located
* **Phone Number:** A working phone number for your business
* **Email Address:** A business email address
### Legal Information
* **Business Type:** Are you a corporation, LLC, partnership, etc.?
* **Tax ID Number:** Your government-issued business tax number
* **Registration Number:** Your business registration number (if required)
### Contact Person
* **Authorized Representative:** Someone who can make decisions for the company
* **Their Contact Info:** Phone and email for this person
## Step-by-Step Process
### Step 1: Create Your Account
1. Go to [Twilio Console](https://console.twilio.com)
2. Sign up or log in to your account
3. Navigate to the "Trust Hub" section
### Step 2: Start Your Profile
1. Click "Create Primary Customer Profile"
2. Choose "Business/Organization Profile" (not Individual)
3. Fill in all the required information carefully
### Step 3: Submit for Review
1. Double-check all your information
2. Submit your profile for Twilio's review
3. Wait for approval (usually takes 24-48 hours)
### Step 4: Get Approved
1. You'll receive an email when approved
2. If there are issues, you'll get instructions on how to fix them
3. Once approved, you can start using Twilio's services
## Common Mistakes to Avoid
### โ Wrong Information
* Make sure all details match your official business documents
* Don't use personal information instead of business information
### โ Incomplete Applications
* Fill out every required field
* Don't leave anything blank
### โ Using Personal Accounts
* Use your business email, not personal email
* Use business phone numbers, not personal ones
## What Happens After Verification?
### โ
You Can Make Calls
* Your business can now use Twilio's phone services
* You can make outbound calls to customers
* You can receive calls from customers
### โ
Better Deliverability
* Your calls are less likely to be blocked
* Your messages are less likely to be marked as spam
* Higher success rates for your campaigns
### โ
Professional Appearance
* Your business appears more trustworthy
* Customers are more likely to answer your calls
* You can display your business name on caller ID
## Troubleshooting
### My Application Was Rejected
**Common reasons:**
* Information doesn't match official documents
* Missing required information
* Using personal instead of business information
**What to do:**
* Check the rejection email for specific reasons
* Update your information to match official documents
* Resubmit your application
### It's Taking Too Long
**Normal timeline:** 24-48 hours
**If longer than 5 days:**
* Check your email for any requests for more information
* Contact Twilio support
* Make sure you haven't missed any required steps
### I Need to Update My Information
* Go to your Trust Hub profile
* Edit the information that needs updating
* Resubmit for review if required
## Tips for Success
### ๐ Before You Start
* Gather all your business documents
* Make sure your business is properly registered
* Have all required information ready
### โ๏ธ While Filling Out Forms
* Double-check every detail
* Use official business information only
* Be consistent with spelling and formatting
### โฐ After Submission
* Be patient - it takes time to review
* Check your email regularly
* Respond quickly to any requests for more information
## Need Help?
If you run into any problems:
1. **Check the FAQ** - Many common questions are answered there
2. **Contact Support** - Twilio has helpful support staff
3. **Read the Documentation** - Twilio provides detailed guides
Remember: Business verification might seem complicated, but it's just Twilio's way of making sure everyone using their services is legitimate. Once you're verified, you'll have access to powerful tools to help your business communicate with customers!
# CNAM (Caller Name)
Source: https://docs.vodex.ai/twilio-verification/cnam
Learn about CNAM - how caller names work and how to set up your business name to display when you call customers
## What is CNAM?
CNAM stands for **Caller Name**. It's the system that shows the name of the person or business calling you, instead of just showing their phone number.
**Simple explanation:** When someone calls you, instead of seeing "555-123-4567", you see "John's Pizza" or "Amazon Customer Service".
## How Does CNAM Work?
Think of CNAM like a phone book, but in reverse:
### The Old Way (Phone Book)
1. You know someone's name
2. You look up their phone number
3. You call them
### CNAM (Reverse Phone Book)
1. Someone calls you
2. You see their phone number
3. CNAM looks up their name
4. You see "John's Pizza" instead of "555-123-4567"
## Why is CNAM Important?
### For Businesses
* **Higher Answer Rates:** People are more likely to answer "ABC Company" than "555-123-4567"
* **Professional Image:** Your business looks more legitimate
* **Brand Recognition:** Customers recognize your business name
### For Customers
* **Know Who's Calling:** You can see if it's your bank, doctor, or a friend
* **Avoid Scams:** Real businesses show their real names
* **Better Experience:** You know who to call back
## How CNAM Actually Works
### Step 1: Call is Made
When someone calls you:
1. Their phone number is sent to your phone company
2. Your phone company receives the number: "555-123-4567"
### Step 2: CNAM Lookup
Your phone company then:
1. Checks a CNAM database (like a big phone book)
2. Looks up what name is associated with "555-123-4567"
3. Finds "John's Pizza" in the database
### Step 3: Display the Name
Your phone shows:
* **Caller ID:** John's Pizza
* **Number:** 555-123-4567
## Types of CNAM Information
### Business Names
* "ABC Company"
* "XYZ Restaurant"
* "City Bank"
* "Dr. Smith's Office"
### Personal Names
* "John Smith"
* "Mary Johnson"
* "The Smith Family"
### Generic Names
* "Unknown Caller"
* "Private Number"
* "Restricted"
## Setting Up CNAM for Your Business
### Step 1: Choose Your Display Name
Pick a name that:
* **Is clear and recognizable**
* **Matches your business name**
* **Is easy to read**
* **Is professional**
**Good examples:**
* "ABC Company"
* "John's Pizza"
* "City Medical Center"
**Bad examples:**
* "ABC Company LLC Inc. Corp."
* "John's Pizza & Restaurant & Bar & Grill"
* "The Best Pizza Place in Town Since 1985"
### Step 2: Register with CNAM Databases
You need to register your business name with CNAM databases:
1. **Contact your phone company** - They can help you register
2. **Use CNAM services** - There are companies that specialize in CNAM registration
3. **Work with Twilio** - They can help you set up CNAM for your business
### Step 3: Wait for Updates
* CNAM updates can take 24-48 hours
* Some databases update faster than others
* It may take a few days to see your name everywhere
## CNAM vs. Caller ID
### Caller ID
* Shows the phone number calling you
* Always works (if the number is available)
* Basic information
### CNAM
* Shows the name associated with that number
* Only works if the name is registered
* More detailed information
**Example:**
* **Caller ID only:** "555-123-4567"
* **Caller ID + CNAM:** "John's Pizza - 555-123-4567"
## Common CNAM Issues
### My Business Name Isn't Showing
**Possible reasons:**
* Name isn't registered in CNAM databases
* Registration is still processing
* Different databases show different names
* Your phone company doesn't support CNAM
**What to do:**
* Contact your phone company
* Check if CNAM is enabled
* Wait a few days for updates
* Consider using a CNAM service
### Wrong Name is Showing
**Possible reasons:**
* Previous owner of the number registered a different name
* Multiple names are registered for the same number
* Database hasn't been updated
**What to do:**
* Contact the CNAM database provider
* Update your registration
* Wait for the changes to propagate
### No Name Shows at All
**Possible reasons:**
* Number isn't registered in any CNAM database
* Your phone company doesn't support CNAM
* CNAM service is disabled
**What to do:**
* Check with your phone company
* Enable CNAM service if available
* Register your number in CNAM databases
## CNAM for Different Types of Businesses
### Small Businesses
* **Use your business name** as it appears on your business license
* **Keep it simple** and easy to recognize
* **Be consistent** across all your phone numbers
### Large Companies
* **Use your official company name**
* **Consider department names** for different numbers
* **Maintain a consistent brand** across all communications
### Personal Numbers
* **Use your real name** or family name
* **Avoid nicknames** that might confuse people
* **Keep it professional** if used for business
## CNAM Best Practices
### Do's โ
* **Use your real business name**
* **Keep it short and clear**
* **Be consistent across all numbers**
* **Update when you change your business name**
* **Test with different phone companies**
### Don'ts โ
* **Don't use misleading names**
* **Don't use all caps** (unless it's your official name)
* **Don't include special characters** that might not display properly
* **Don't use names that are too long**
* **Don't forget to update when you change numbers**
## Testing Your CNAM
### How to Test
1. **Call yourself** from a different phone
2. **Ask friends and family** what they see when you call
3. **Use different phone companies** to test
4. **Check online CNAM lookup tools**
### What to Look For
* **Correct business name** is displayed
* **Name is clear** and easy to read
* **Consistent** across different phones
* **Professional** appearance
## CNAM and Compliance
### Legal Requirements
* **Don't use misleading names** - You must use your real business name
* **Don't impersonate others** - You can't use someone else's business name
* **Follow local laws** - Some areas have specific CNAM requirements
### Best Practices
* **Be honest** about who you are
* **Use official business names** only
* **Update information** when it changes
* **Respect others' trademarks**
## Troubleshooting CNAM Issues
### Problem: Name shows as "Unknown"
**Solution:** Register your number in CNAM databases
### Problem: Wrong name is showing
**Solution:** Contact CNAM database providers to update
### Problem: Name shows on some phones but not others
**Solution:** Different phone companies use different databases
### Problem: Name changes randomly
**Solution:** Check for multiple registrations and clean them up
## The Future of CNAM
### New Technologies
* **Better databases** with more accurate information
* **Real-time updates** instead of waiting days
* **International CNAM** for global businesses
* **Enhanced caller ID** with more information
### Integration with Other Systems
* **SHAKEN/STIR integration** for better call verification
* **AI-powered name recognition** for better accuracy
* **Social media integration** for more detailed caller information
## How to Set Up CNAM with Twilio
Now that you understand what CNAM is, let's walk through how to actually set it up for your business through Twilio.
### Prerequisites
Before you can set up CNAM, you need:
* A verified Twilio account
* A verified Business Profile (see our [Business Verification guide](/twilio-verification/business-verification))
* Phone numbers that you want to use for outbound calls
* A display name for your business (up to 15 characters)
### Step-by-Step Setup Process
#### Step 1: Create Your Primary Business Profile
1. **Log in to Twilio Console**
* Go to [console.twilio.com](https://console.twilio.com)
* Sign in with your Twilio account
2. **Navigate to Trust Hub**
* In the left sidebar, click on "Trust Hub"
* Click on "Customer Profiles"
3. **Create Business Profile**
* Click "Create Primary Business Profile"
* Choose "Business/Organization Profile" (not Individual)
* Fill in all your business details:
* Business name
* Business address
* Phone number
* Email address
* Business type (Corporation, LLC, etc.)
* Tax ID number
* Registration number (if required)
* Submit for verification
4. **Wait for Approval**
* Approval typically takes 24-48 hours
* You'll receive an email notification when approved
* If rejected, you'll get instructions on what to fix
#### Step 2: Create CNAM Trust Product
1. **Navigate to CNAM Section**
* In Twilio Console, go to Trust Hub > CNAM
* Click "Register for CNAM"
2. **Configure Your CNAM Display Name**
* **CNAM Display Name:** Enter your desired business name (up to 15 characters)
* **Business Profile:** Select your approved Business Profile from the dropdown
* **Important:** The display name must:
* Be unique (not already taken by another business)
* Begin with a letter
* Only contain letters, numbers, periods, commas, and spaces
* Be 15 characters or less
3. **Choose Your Display Name Carefully**
* **Good examples:** "ABC Company", "John's Pizza", "City Bank"
* **Bad examples:** "ABC Company LLC Inc Corp" (too long), "123 Business" (starts with number)
* **Tips:**
* Keep it short and clear
* Use your official business name
* Make it easy to recognize
* Avoid special characters
#### Step 3: Assign Phone Numbers
1. **Select Phone Numbers**
* Choose the phone numbers you want to register for CNAM
* These should be the same numbers you use for outbound calls
* Only US standard long code numbers are eligible for CNAM
2. **Review Your Selection**
* Make sure all selected numbers are correct
* Verify that you have the right to use these numbers
* Double-check that the numbers are associated with your Business Profile
#### Step 4: Submit for Review
1. **Certify Your Information**
* Check the box certifying that your Business Profile is the originator of the phone calls
* Confirm that the display name accurately represents your business
* Review all information for accuracy
2. **Submit Your Application**
* Click "Submit for Review"
* Wait for approval (typically 48-72 hours)
* You'll receive email notifications about the status
#### Step 5: Verification and Activation
1. **Check Your Email**
* Look for approval notification from Twilio
* If approved, your CNAM is now active
* If rejected, follow the instructions to fix any issues
2. **Test Your Setup**
* Make a test call from your registered number
* Check if your business name appears on the recipient's caller ID
* Ask friends or family to call you and see what they see
### What Happens After Setup
#### โ
Your Business Name Now Appears
* When you call someone, they'll see your business name instead of just your phone number
* Your calls look more professional and trustworthy
* People are more likely to answer calls from recognized business names
#### โ
Better Call Success Rates
* Higher answer rates because people recognize your business
* Reduced chance of calls being blocked or marked as spam
* Improved customer experience and trust
#### โ
Professional Branding
* Consistent branding across all your phone communications
* Better brand recognition for your business
* Enhanced credibility in customer interactions
### Troubleshooting CNAM Setup
#### My Business Profile Was Rejected
**Common reasons:**
* Information doesn't match official business documents
* Missing required information
* Using personal instead of business information
**What to do:**
* Check the rejection email for specific reasons
* Update your information to match official documents
* Resubmit your Business Profile
#### My CNAM Registration Was Rejected
**Common reasons:**
* Display name is already taken by another business
* Display name doesn't meet requirements (starts with number, too long, etc.)
* Business Profile not properly verified
* Phone numbers not properly assigned
**What to do:**
* Try a different display name that meets all requirements
* Ensure your Business Profile is fully approved
* Verify all phone numbers are assigned to your Business Profile
* Double-check all information for accuracy
* Resubmit your CNAM registration
#### My Display Name Isn't Showing
**Possible reasons:**
* CNAM registration is still processing (can take 48-72 hours)
* Different phone companies use different databases
* Your phone company doesn't support CNAM
* The name hasn't propagated to all databases yet
**What to do:**
* Wait a few more days for full propagation
* Test with different phone companies
* Contact your phone company about CNAM support
* Check if CNAM is enabled on your account
#### It's Taking Too Long
**Normal timeline:** 48-72 hours for CNAM approval
**If longer than 5 days:**
* Check your email for any requests for more information
* Contact Twilio support
* Verify you haven't missed any required steps
### Important Notes
#### Display Name Requirements
* **Length:** Maximum 15 characters
* **Format:** Must begin with a letter
* **Characters:** Only letters, numbers, periods, commas, and spaces allowed
* **Uniqueness:** Must be unique across all CNAM databases
* **Accuracy:** Must accurately represent your business
#### Phone Number Eligibility
* **US Standard Long Code:** โ
Eligible for CNAM
* **Toll-free Numbers:** โ ๏ธ May require additional steps
* **International Numbers:** โ Not eligible for CNAM
* **Short Codes:** โ Not eligible for CNAM
#### Ongoing Maintenance
* Keep your Business Profile information up to date
* Notify Twilio if you change your business name
* Regularly test your CNAM to ensure it's working
* Update your display name if your business name changes
#### Cost Considerations
* CNAM setup is typically free
* There may be ongoing costs for phone number usage
* Check Twilio's pricing for current rates
### Testing Your CNAM
#### How to Test
1. **Call Yourself**
* Use a different phone to call your registered number
* Check what name appears on the caller ID
2. **Ask Others to Test**
* Have friends or family call you
* Ask them what name they see when you call them
3. **Use Different Phone Companies**
* Test with different carriers (Verizon, AT\&T, T-Mobile, etc.)
* Some carriers may show different information
4. **Check Online Tools**
* Use online CNAM lookup tools
* Search for your phone number to see what name is registered
#### What to Look For
* **Correct business name** is displayed
* **Name is clear** and easy to read
* **Consistent** across different phones and carriers
* **Professional** appearance
## Summary
CNAM is like having a name tag for your phone number. When you call someone, instead of just seeing your number, they see your business name. This makes your calls more professional and more likely to be answered.
**Key points to remember:**
* CNAM shows your business name instead of just your phone number
* You need to register your name in CNAM databases
* It can take a few days for changes to show up everywhere
* Always use your real business name
* Test your CNAM to make sure it's working correctly
**The bottom line:** CNAM helps your business look more professional and trustworthy when making calls, which means more people will answer your phone calls!
# Twilio Verification Overview
Source: https://docs.vodex.ai/twilio-verification/overview
Learn about Twilio's verification systems including Business Verification, SHAKEN/STIR, and CNAM
Welcome to the world of Twilio Verification! This section will help you understand the different ways Twilio helps verify and authenticate phone communications to make them safer and more trustworthy.
## What is Twilio Verification?
Think of Twilio Verification as a security system for phone calls and messages. Just like how you need to show your ID to enter a building, phone numbers and businesses need to prove they are who they say they are when making calls or sending messages.
## Why is Verification Important?
Imagine you're at home and your phone rings. You look at the caller ID and see "Unknown Number" or "Scam Likely." You probably won't answer, right? But what if it showed "Your Bank" or "Amazon Customer Service"? You'd be more likely to answer.
That's exactly what Twilio Verification does - it helps make phone calls and messages more trustworthy so people know who's really calling them.
## The Three Main Types of Verification
### 1. ๐ข Business Verification
This is like getting a business license. It proves that a company is real and legitimate before they can use Twilio's services.
**Think of it like:** Getting a driver's license for your business to use the phone system.
### 2. ๐ SHAKEN/STIR
This is like a digital fingerprint for phone calls. It helps prevent fake calls and ensures the caller ID you see is actually who's calling.
**Think of it like:** A security seal on a package that shows it hasn't been tampered with.
### 3. ๐ CNAM (Caller Name)
This shows the actual name of the business or person calling you, not just their phone number.
**Think of it like:** Having a name tag that shows your real name instead of just a number.
## How This Helps You
* **For Businesses:** Your calls are more likely to be answered because people trust you
* **For Customers:** You can see who's really calling and avoid scams
* **For Everyone:** The phone system becomes safer and more reliable
## What's Next?
Ready to learn more? Check out our detailed guides:
* [Business Verification](/twilio-verification/business-verification) - Learn how to verify your business
* [SHAKEN/STIR](/twilio-verification/shaken-stir) - Understand call authentication
* [CNAM](/twilio-verification/cnam) - Set up caller name display
Each guide is written in simple terms that anyone can understand, even if you're completely new to phone systems!
# SHAKEN/STIR
Source: https://docs.vodex.ai/twilio-verification/shaken-stir
Understand SHAKEN/STIR call authentication in simple terms - learn how it prevents fake calls and protects you from scams
# SHAKEN/STIR: Call Authentication
## What is SHAKEN/STIR?
SHAKEN/STIR is like a security system for phone calls. It helps make sure that when someone calls you, they are really who they say they are.
**Think of it like:** A security guard at a building who checks everyone's ID before letting them in.
## Breaking Down the Names
### SHAKEN
**Stands for:** Signature-based Handling of Asserted information using toKENs
**What it means:** A system that puts a digital signature on phone calls to prove they're real
### STIR
**Stands for:** Secure Telephony Identity Revisited\
**What it means:** A set of rules for making phone calls secure and trustworthy
**Together:** They work like a team to prevent fake calls and caller ID spoofing.
## The Problem SHAKEN/STIR Solves
### Before SHAKEN/STIR
* Scammers could fake caller ID numbers
* You'd see "Your Bank" calling, but it was actually a scammer
* Millions of fake calls every day
* People lost money to phone scams
### After SHAKEN/STIR
* Every call gets a digital "fingerprint"
* You can see if a call is really from who it says it is
* Scammers can't easily fake caller ID anymore
* Much safer phone system
## How Does It Work?
### Step 1: Making a Call
When someone makes a call:
1. Their phone company checks: "Is this person allowed to use this number?"
2. If yes, they add a digital signature to the call
3. This signature is like a seal that proves the call is legitimate
### Step 2: The Call Travels
As the call goes through different phone companies:
1. Each company checks the signature
2. They make sure it hasn't been tampered with
3. If the signature is valid, they pass the call along
### Step 3: You Receive the Call
When the call reaches you:
1. Your phone company checks the signature one last time
2. If it's valid, the call comes through normally
3. If it's fake or tampered with, the call might be blocked or flagged
## Understanding Attestation Levels
Think of attestation levels like different types of ID verification:
### Level A - Full Attestation (Best)
**What it means:** The phone company knows the caller AND confirms they have the right to use that number
**Like having:** A driver's license with your photo and address
**You can trust:** This call is definitely from who it says it is
### Level B - Partial Attestation (Good)
**What it means:** The phone company knows the caller, but can't confirm they have the right to use that number
**Like having:** A student ID that shows your name but not your address
**You can trust:** The caller is known, but be a little more careful
### Level C - Gateway Attestation (Caution)
**What it means:** The phone company doesn't know who the caller is or if they have the right to use that number
**Like having:** A visitor's badge with just a number
**You should:** Be extra careful with these calls
## What You'll See on Your Phone
### โ
Verified Calls
* Your phone might show a checkmark or "Verified" label
* The caller ID will be more trustworthy
* You'll know the call is really from who it says
### โ ๏ธ Unverified Calls
* Your phone might show a warning
* The caller ID might be marked as "Unknown" or "Suspicious"
* You should be more careful about answering
### ๐ซ Blocked Calls
* Some fake calls will be blocked completely
* You won't even see them in your call log
* This protects you from scams
## Benefits for Everyone
### For You (The Caller)
* **Higher Answer Rates:** People are more likely to answer verified calls
* **Better Reputation:** Your business looks more trustworthy
* **Less Spam:** Your legitimate calls won't be confused with spam
### For You (The Receiver)
* **Safer Calls:** You can see which calls are verified
* **Fewer Scams:** Fake calls are much harder to make
* **Better Caller ID:** You know who's really calling
### For Phone Companies
* **Less Spam:** They can block fake calls more easily
* **Better Service:** Customers trust the phone system more
* **Compliance:** They meet government requirements
## Common Questions
### Q: Do I need to do anything special?
**A:** No! SHAKEN/STIR works automatically in the background. You don't need to install anything or change your phone settings.
### Q: Will this stop all spam calls?
**A:** It will stop most fake calls, but some spam might still get through. It's still important to be careful with unknown numbers.
### Q: Does this work on all phones?
**A:** Yes! It works on all types of phones - smartphones, landlines, and even old phones.
### Q: What if I'm calling from a different country?
**A:** SHAKEN/STIR works internationally, but the level of verification might be different depending on the country.
## How to Tell if a Call is Verified
### On Smartphones
* Look for a checkmark or "Verified" label next to the caller ID
* Some phones show a green checkmark
* Others might show "Verified Caller" text
### On Landlines
* The caller ID might show additional information
* Some systems display verification status
* Ask your phone company about verification features
## What to Do with Unverified Calls
### If You're Not Sure
1. **Don't answer** if you don't recognize the number
2. **Let it go to voicemail** and listen to the message
3. **Check online** if the number is associated with scams
4. **Call back** using the official number from their website
### Red Flags to Watch For
* Calls asking for personal information
* Calls asking for money or gift cards
* Calls claiming to be from government agencies
* Calls with threats or urgent demands
## The Future of Phone Security
SHAKEN/STIR is just the beginning! Phone companies are constantly working on new ways to make calls safer:
* **Better AI detection** of scam calls
* **More verification methods** for businesses
* **International cooperation** to stop global scams
* **User reporting systems** to catch new scam patterns
## How to Set Up SHAKEN/STIR with Twilio
Now that you understand what SHAKEN/STIR is, let's walk through how to actually set it up for your business through Twilio.
### Prerequisites
Before you can set up SHAKEN/STIR, you need:
* A verified Twilio account
* A verified Business Profile (see our [Business Verification guide](/twilio-verification/business-verification))
* Phone numbers that you want to use for outbound calls
### Step-by-Step Setup Process
#### Step 1: Create Your Primary Business Profile
1. **Log in to Twilio Console**
* Go to [console.twilio.com](https://console.twilio.com)
* Sign in with your Twilio account
2. **Navigate to Trust Hub**
* In the left sidebar, click on "Trust Hub"
* Click on "Customer Profiles"
3. **Create Business Profile**
* Click "Create Primary Business Profile"
* Choose "Business/Organization Profile" (not Individual)
* Fill in all your business details:
* Business name
* Business address
* Phone number
* Email address
* Business type (Corporation, LLC, etc.)
* Tax ID number
* Registration number (if required)
* Submit for verification
4. **Wait for Approval**
* Approval typically takes 24-48 hours
* You'll receive an email notification when approved
* If rejected, you'll get instructions on what to fix
#### Step 2: Assign Phone Numbers to Your Business Profile
1. **Go to Your Approved Profile**
* In Trust Hub > Customer Profiles
* Click on your approved Business Profile
2. **Assign Phone Numbers**
* Click "Assign Phone Numbers"
* Select the phone numbers you want to use for outbound calls
* These numbers will be associated with your business
#### Step 3: Create SHAKEN/STIR Trust Product
1. **Navigate to SHAKEN/STIR Section**
* In Twilio Console, go to Trust Hub > SHAKEN/STIR Calling
* Click "New SHAKEN/STIR Registration"
2. **Configure Your Trust Product**
* **Friendly Name:** Give your Trust Product a name (e.g., "My Business SHAKEN/STIR")
* **Business Profile:** Select your approved Business Profile from the dropdown
* **Phone Numbers:** Assign the phone numbers associated with your Business Profile
3. **Certify Your Information**
* Check the box certifying that your Business Profile is the originator of the phone calls
* Confirm that the display name accurately represents your business
* Review all information for accuracy
4. **Submit for Review**
* Click "Submit for Review"
* Wait for approval (typically 24-48 hours)
* You'll receive email notifications about the status
#### Step 4: Verification and Activation
1. **Check Your Email**
* Look for approval notification from Twilio
* If approved, your SHAKEN/STIR is now active
* If rejected, follow the instructions to fix any issues
2. **Test Your Setup**
* Make a test call from your registered number
* Check if the call shows as verified on the recipient's phone
* Verify that your business name appears correctly
### What Happens After Setup
#### โ
Your Calls Are Now Authenticated
* All outbound calls from your registered numbers will have SHAKEN/STIR authentication
* Recipients will see verification indicators on their phones
* Your calls are less likely to be blocked or marked as spam
#### โ
Better Call Success Rates
* People are more likely to answer verified calls
* Your business appears more trustworthy
* Higher success rates for your calling campaigns
#### โ
Compliance Benefits
* You meet regulatory requirements for call authentication
* Your business is protected from being flagged as spam
* You maintain a good reputation in the phone system
### Troubleshooting SHAKEN/STIR Setup
#### My Business Profile Was Rejected
**Common reasons:**
* Information doesn't match official business documents
* Missing required information
* Using personal instead of business information
**What to do:**
* Check the rejection email for specific reasons
* Update your information to match official documents
* Resubmit your Business Profile
#### My SHAKEN/STIR Registration Was Rejected
**Common reasons:**
* Business Profile not properly verified
* Phone numbers not properly assigned
* Incomplete or incorrect information
**What to do:**
* Ensure your Business Profile is fully approved
* Verify all phone numbers are assigned to your Business Profile
* Double-check all information for accuracy
* Resubmit your SHAKEN/STIR registration
#### It's Taking Too Long
**Normal timeline:** 24-48 hours for each step
**If longer than 5 days:**
* Check your email for any requests for more information
* Contact Twilio support
* Verify you haven't missed any required steps
### Important Notes
#### Phone Number Requirements
* Only certain types of phone numbers are eligible for SHAKEN/STIR
* US standard long code numbers work best
* Toll-free numbers may have different requirements
#### Ongoing Maintenance
* Keep your Business Profile information up to date
* Notify Twilio if you change your business information
* Regularly check that your SHAKEN/STIR is still active
#### Cost Considerations
* SHAKEN/STIR setup is typically free
* There may be ongoing costs for phone number usage
* Check Twilio's pricing for current rates
## Summary
SHAKEN/STIR is like having a security guard for every phone call. It helps make sure that when someone calls you, they're really who they say they are. While it won't stop all spam calls, it makes the phone system much safer and more trustworthy for everyone.
**Remember:** Even with SHAKEN/STIR, always be careful with unknown callers and never give out personal information over the phone unless you're absolutely sure who you're talking to!