Skip to main content

​
Contact Structure

Each contact in your batch must include a phone number and can optionally include additional information: 
{
  "phoneNumber": "+15551234567",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "company": "Acme Corp",
  "metadata": {
    "lead_score": 80,
    "account_id": "A123",
    "last_contact": "2025-01-15"
  }
}

​
Required Fields

​
Phone Number

  • Field: phoneNumber
  • Format: E.164 (e.g., +15551234567)
  • Required: Yes
Phone numbers must include the country code and be in E.164 format. Invalid formats will be rejected.

​
Optional Fields

​
Name

  • Field: name
  • Type: String
  • Default: “Unknown”
{
  "name": "Jane Doe"
}

​
Email

  • Field: email
  • Type: String (valid email format)
  • Default: null
{
  "email": "jane@example.com"
}

​
Company

  • Field: company
  • Type: String
  • Default: null
{
  "company": "Acme Corp"
}

​
Custom Metadata

Use the metadata field to pass custom variables to your agent: 
{
  "metadata": {
    "lead_score": 80,
    "account_id": "A123",
    "product_interest": "Enterprise Plan",
    "last_contact_date": "2025-01-15",
    "timezone": "America/New_York"
  }
}

​
Using Metadata in Agent Prompts

Reference metadata variables using curly braces: 
Hello {name}! I'm calling from Acme Corp regarding your interest in our {product_interest}.

I see you're in the {timezone} timezone, so I wanted to reach out at a convenient time.

Your account ID is {account_id} for reference.
Metadata is perfect for personalizing conversations and passing context-specific information to your agent.

​
Contact Deduplication

Dialgen automatically handles duplicate contacts:

​
By Contact ID

If you provide an existing id, the contact is reused: 
{
  "id": "contact_existing_123",
  "phoneNumber": "+15551234567",
  "name": "Jane Doe"
}

​
By Phone Number

Contacts with matching phone numbers are identified and reused: 
{
  "phoneNumber": "+15551234567"
}

​
Benefits

  • Preserves call history across campaigns
  • Prevents duplicates in your database
  • Resets attempt counts for new campaigns
  • Maintains contact data integrity

​
Example: Complete Contact List

{
  "contacts": [
    {
      "phoneNumber": "+15551234567",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "company": "Acme Corp",
      "metadata": {
        "lead_score": 80,
        "account_id": "A123"
      }
    },
    {
      "id": "contact_existing_456",
      "phoneNumber": "+15557654321",
      "name": "John Smith",
      "metadata": {
        "lead_score": 90,
        "follow_up": true
      }
    },
    {
      "phoneNumber": "+15559876543",
      "name": "Alice Johnson"
    }
  ]
}

​
Best Practices

​
Validate Phone Numbers

  • Ensure all numbers are in E.164 format
  • Verify country codes are correct
  • Remove invalid or disconnected numbers

​
Enrich Contact Data

  • Include names for personalization
  • Add email for follow-up communications
  • Use metadata for context-specific information

​
Organize Metadata

  • Use consistent key names across contacts
  • Keep metadata relevant to the conversation
  • Avoid sensitive information in metadata

​
Reuse Contact IDs

  • Provide existing contact IDs when available
  • Preserve call history across campaigns
  • Track contact interactions over time

​
Next Steps

Configuration Options

Configure batch settings and options

Create Batch API

Complete API reference