Skip to main content

Contact Structure

Each contact in your batch must include a phone number and can optionally include additional information:

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”

Email

  • Field: email
  • Type: String (valid email format)
  • Default: null

Company

  • Field: company
  • Type: String
  • Default: null

Custom Metadata

Use the metadata field to pass custom variables to your agent:

Using Metadata in Agent Prompts

Reference metadata variables using curly braces:
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:

By Phone Number

Contacts with matching phone numbers are identified and reused:

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


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