Auto-Dialer Voice Campaigns

Auto-Dialer Voice Campaigns

Overview

The Auto-Dialer Voice Campaigns endpoint enables automated placement of bulk outbound voice calls to selected contact lists, supporting both AI-powered conversational agents and pre-recorded voice drops. Through a structured configuration interface, users can define campaign parameters such as target groups, call scripts, scheduling windows, and fallback behaviors. The endpoint facilitates scalable voice outreach by handling call queuing, delivery tracking, and engagement logging. Each campaign instance generates detailed execution metrics and outcomes, enabling real-time monitoring and performance analysis. Secure access to campaign operations requires authentication via API key. Below we will cover the endpoints needed to customize, create, and monitor your own voice call campaigns. Note: in this tutorial we are assuming you have configured a phone number, contacts, and AI agents in your workspace.

After reading through this tutorial, try out the endpoints here

Getting Started

Authorization

You must provide your API key in the X-API-KEY header.

To set up your API Key

• Go to Account → API Key tab.
• Refresh the Key if needed
• Copy the key and keep it safe. This key is required in the X-API-KEY header for all requests.

Get Phone Numbers

GET /api/v1/workspace/{workspace_id}/phones

First you must find the available phone numbers. You will need to collect the id of each number you would like to run the campaign from.

Example

Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/seax-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/phones?offset=0&limit=10&is_owned=false&enabled=true&voice_available=true' \
  -H 'accept: application/json' \
  -H 'X-API-Key: <your_api_key>'

Response:

{
  "data": [
    {
      "name": "tech support",
      "enabled": true,
      "phone": "+886912123456",
      "country": "US",
      "whatsapp_device_id": "1234567890:98@s.whatsapp.net",
      "whatsapp_status": "CONNECTING",
      "generic_reply_message": "Welcome! If you want to subscribe daily report, please reply 'DAILY'.",
      "dnc_reply_message": "Ok, we won't send you any other message.",
      "enabled_generic_reply": false,
      "enabled_dnc_reply": false,
      "type": "LOCAL",
      "source": "TWILIO",
      "phone_capability": {
        "voice": true,
        "fax": false,
        "whatsapp": false,
        "whatsapp_business_platform": false
      },
      "is_default": false,
      "enabled_recipient": false,
      "whatsapp_business_account_phone_id": "555555555555",
      "dialpad_available": false,
      "created_time": "2025-07-07T18:12:58.351633",
      "updated_time": "2025-07-07T18:12:58.351649",
      "id": "0354fb10-9e18-4923-a213-6253800f8d01",
      "call_recipient": {
        "id": "0354fb10-9e18-4923-a213-6253800f8d01",
        "type": "PHONE_NUMBER",
        "receiver": "+1234567890"
      },
      "sms_recipient": {
        "id": "0354fb10-9e18-4923-a213-6253800f8d01",
        "type": "PHONE_NUMBER",
        "receiver": "+1234567890"
      },
      "wabp_recipient": {
        "id": "0354fb10-9e18-4923-a213-6253800f8d01",
        "type": "PHONE_NUMBER",
        "receiver": "+1234567890"
      },
      "verified_caller": {
        "created_time": "2025-07-07T18:12:58.351633",
        "updated_time": "2025-07-07T18:12:58.351649",
        "id": "0354fb10-9e18-4923-a213-6253800f8d01",
        "phone_number": "+1234567890",
        "name": "+1234567890",
        "validation_code": "813955",
        "status": "failed",
        "call_id": "CAca1ce90f90c7609477eee1f6bbc75a50"
      },
      "byoc_trunk": {
        "created_time": "2025-07-07T18:12:58.351633",
        "updated_time": "2025-07-07T18:12:58.351649",
        "id": "0354fb10-9e18-4923-a213-6253800f8d01",
        "sip_domain": "string",
        "acl_ip_addresses": [
          {
            "ip_address": "string",
            "port": 0,
            "id": "0354fb10-9e18-4923-a213-6253800f8d01"
          }
        ],
        "sip_auth_username": "string",
        "sip_auth_password": "string"
      },
      "users": [
        {
          "account": "satoshi",
          "first_name": "Satoshi",
          "last_name": "Nakamoto",
          "email": "satoshi@btc.com",
          "phone": "+1230000000",
          "language": "en-US",
          "theme": "dark",
          "date_format": "MM/dd/yyyy",
          "time_format": "HH:mm:ss",
          "created_time": "2009-01-03T18:15:00",
          "email_notification_enabled": false,
          "is_new_user": false,
          "email_notification_only_offline": false,
          "sms_notification_enabled": false,
          "sms_notification_only_offline": false
        }
      ],
      "keywords": [
        {
          "name": "want",
          "reply": "OK, we got it.",
          "enabled_auto_reply": true,
          "enabled_contact_label": true,
          "keep_dnc_label_only": false,
          "id": "11111111-2222-4444-3333-555555555555",
          "phone_id": "11111111-2222-4444-3333-555555555555",
          "priority": 10,
          "contact_labels": [
            {
              "name": "test",
              "color": "#19b9c3",
              "description": "This label is for vip customer",
              "id": "11111111-2222-4444-3333-555555555555",
              "is_system": true,
              "created_time": "2025-07-07T18:13:02.656081",
              "updated_time": "2025-07-07T18:13:02.656093"
            }
          ],
          "created_time": "2025-07-07T18:13:02.665302",
          "updated_time": "2025-07-07T18:13:02.665315"
        }
      ],
      "unread_count": 0
    }
  ],
  "total": 0
}

Get Contacts

GET /api/v1/workspace/{workspace_id}/contacts

Use this endpoint to retrieve the set of contacts you’d like to call during the campaign.

Example

Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/seax-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/contacts?offset=0&limit=10&keyword=%2B18111222333&whatsapp_phone=%2B18111222333&all_contact_label_ids=11111111-2222-4444-3333-555555555555%2C11111111-2222-4444-3333-666666666666&any_contact_label_ids=11111111-2222-4444-3333-555555555555%2C11111111-2222-4444-3333-666666666666&exclude_contact_ids=11111111-2222-4444-3333-555555555555%2C11111111-2222-4444-3333-666666666666&exclude_any_contact_label_ids=11111111-2222-4444-3333-555555555555%2C11111111-2222-4444-3333-666666666666&exclude_all_contact_label_ids=11111111-2222-4444-3333-555555555555%2C11111111-2222-4444-3333-666666666666&addition_contact_ids=11111111-2222-4444-3333-555555555555%2C11111111-2222-4444-3333-666666666666&order_by=phone%3Aasc%2Ccreated_time%3Adesc%2Cname%3Aasc&exclude_labels=DNC%2Cinvalid%20number%2Cunreachable&whatsapp_phone_only=false' \
  -H 'accept: application/json' \
  -H 'X-API-Key: <your_api_key>'

Response:

{
  "data": [
    {
      "name": "Test1",
      "phone": "+12345678900",
      "note": "New contact",
      "whatsapp_phone": "+12345678900",
      "contact_field_data": {
        "field1": 1
      },
      "id": "11111111-2222-4444-3333-555555555555",
      "workspace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "created_time": "2025-07-07T18:13:04.845276",
      "updated_time": "2025-07-07T18:13:04.845287",
      "contact_labels": [
        {
          "name": "test",
          "color": "#19b9c3",
          "description": "This label is for vip customer",
          "id": "11111111-2222-4444-3333-555555555555",
          "is_system": true,
          "created_time": "2025-07-07T18:13:02.656081",
          "updated_time": "2025-07-07T18:13:02.656093"
        }
      ]
    }
  ],
  "total": 0
}

Get Configured AI agents

GET /api/v1/workspace/{workspace_id}/ai_agents

Use this endpoint to get a list of available AI agents to use during the call. You’ll need the conversation_config_id in order to select a particular agent for the campaign creation.

Example

Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/seax-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/ai_agents?limit=10&offset=0&order_by=created_time%3Adesc' \
  -H 'accept: application/json' \
  -H 'X-API-Key: <your_api_key>'

Response:

{
  "data": [
    {
      "id": "0354fb10-9e18-4923-a213-6253800f8d01",
      "name": "",
      "conversation_config_id": "0354fb10-9e18-4923-a213-6253800f8d01",
      "integrations": [
        {
          "inbound_pick_up_message": "Hello, how can I help you?",
          "outbound_starting_message": "Hello, how can I help you?",
          "outbound_voice": "en-US-SteffanNeural",
          "outbound_language": "string",
          "inbound_voice": "en-US-SteffanNeural",
          "inbound_language": "string",
          "type": "SEAX_CALL"
        }
      ]
    }
  ],
  "total": 1
}

Personalizing the Call

The AI agent’s starting message can be personalized with merge fields — placeholders written in single curly braces, e.g. {name}. When a call is placed, every {placeholder} in the message is replaced before the agent speaks.

You do not need to pre-define custom fields anywhere — any key you supply becomes available as {key}.

Two places to supply custom values

You can use either or both. If the same key is set in both places, message_variables wins. {name} / {phone} always come from the contact and can never be overridden.

Reserved keys. name, phone, whatsapp, and labels are reserved and cannot be used as merge variables in message_variables. {name} / {phone} are always taken from the contact; whatsapp / labels are contact / CSV columns, not message placeholders. If you include any of these keys in message_variables, they are ignored (case-insensitively).

⚠️ Outbound only. Merge-field substitution applies to the outbound starting message (the campaign message, or the agent’s outbound_starting_message). The inbound pick-up message (inbound_pick_up_message) is not personalized with contact_field_data — inbound calls are answered with the message exactly as configured.

Substitution rules

• Case-insensitive. {Event_Name}, {event_name}, and {EVENT_NAME} all match a contact_field_data key of event_name.
• Missing values are left as-is. If a placeholder has no matching value for a contact, the literal text (e.g. {event_location}) stays in the message — and the agent will read it aloud. Always provide every placeholder used in your template for every contact you call.
• Values are inserted as plain text.

For the common case — one event reminded to many people — follow Steps 1 → 2 → 3 below. (Per-contact values are an optional add-on, Step 1b.)

Step 1 — Prepare your contacts

Create your contacts with just name and phone. You only store custom values on the contact if they differ per person (see Step 1b).

Single contact:

curl -X POST \
  'https://seax.seasalt.ai/seax-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/contacts' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: <your_api_key>' \
  -d '{ "name": "Mary", "phone": "+6591112222" }'

The response includes the contact id — collect it to target the contact in the campaign via addition_contact_ids.

Bulk (CSV import) — give everyone the same label so you can target them together:

# contacts.csv
name,phone,whatsapp,labels
Mary,+6591112222,,reminders_2026_06
John,+6593334444,,reminders_2026_06

curl -X POST \
  'https://seax.seasalt.ai/seax-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/import_contacts?duplicate_strategy=merge' \
  -H 'X-API-Key: <your_api_key>' \
  -F 'file=@contacts.csv;type=text/csv'

name and labels are required (plus phone for voice). Target imported contacts in the campaign with any_contact_label_ids (the value from the labels column). See Contacts & Labels for the full import reference.

Step 1b (optional) — per-contact values

Only when a value differs per recipient, store it on the contact:

• On POST/PATCH /contacts, add a contact_field_data object, e.g. "contact_field_data": { "first_language": "English" }.
• Or in the CSV, add extra columns — any column beyond name,phone,whatsapp,labels becomes a custom field automatically (with duplicate_strategy=merge, values are merged into existing contacts):

# contacts.csv with a per-contact field
name,phone,whatsapp,labels,first_language
Mary,+6591112222,,reminders_2026_06,English
John,+6593334444,,reminders_2026_06,Malay

Step 2 — Write the message template

Put the placeholders in the campaign message (or configure them once in the agent’s outbound_starting_message):

Good morning {name}, a reminder about {event_name} coming up {event_time} at {event_location}. Will you be attending?

Step 3 — Create the campaign with the event variables

Send the event values once as message_variables on the campaign — they apply to every recipient, and you never touched the contacts. (See Create Campaign for the full request and all fields.)

{
  "name": "Pilates reminder",
  "type": "AI_AGENT",
  "phone_ids": ["<phone_id>"],
  "ai_agent_conversation_config_id": "<conversation_config_id>",
  "message": "Good morning {name}, a reminder about {event_name} coming up {event_time} at {event_location}. Will you be attending?",
  "message_variables": {
    "event_name": "Pilates",
    "event_location": "Main Hall",
    "event_time": "this afternoon at 5 PM"
  },
  "addition_contact_ids": ["<contact_id>"],
  "mode": "WEB",
  "stage": "INSTANCE"
}

Result

Every recipient hears the same event details (from message_variables); only {name} differs per person (from each contact):

If you instead need different values per person, omit message_variables and put the values in each contact’s contact_field_data (Step 1b).

Campaign Management

Create Campaign

Initiate Auto-Dialer Voice Campaign

1. POST /api/v1/workspace/{workspace_id}/auto_dialer_campaigns

Use this endpoint to trigger an outbound auto dialer voice campaign.

Example

Request:

curl -X 'POST' \
  'https://seax.seasalt.ai/seax-api/api/v1/workspace/ffffffff-abcd-4000-0000-000000000000/auto_dialer_campaigns' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: <your_api_key>' \
  -d '{
  "name": "Test",
  "phone_ids": [
    "020086f5-fb0e-4a0c-920a-bbdd04f4381c"
  ],
  "attach_contact_label_ids": [],
  "start_time": "2025-07-08T03:06:09+00:00",
  "is_schedule": false,
  "is_timezone_aware": false,
  "mode": "WEB",
  "stage": "INSTANCE",
  "message": "您好，請問您現在方便講話嗎?",
  "tts_language": "",
  "audio_url": "",
  "type": "AI_AGENT",
  "capture_keypress": true,
  "end_time": "2025-07-08T03:15:00+00:00",
  "ai_agent_conversation_config_id": "221316ae-8a9f-4f39-b7f8-f2e756b80a63",
  "overwrite_phone_recipient": {
    "type": "AI_AGENT",
    "receiver": "221316ae-8a9f-4f39-b7f8-f2e756b80a63"
  },
  "exclude_contact_ids": [
      "4667298e-8d5b-468e-8218-6a47925fe5f2",
      "aa145964-6d17-488d-a9be-09a43191f329"
  ],
  "any_contact_label_ids": [
    "dd20f7cd-03fb-4c79-9f3e-998372d1bec6"
  ],
  "tts_voice": "default",
  "capture_stt": false
}'

overwrite_phone_recipient

This parameter is only required if any of the phone_ids have a default recipient that does not match the campaign recipient. It allows you to explicitly override the default recipient setting for those phone numbers. You must include the type (in this example AI_AGENT) and the receiver (in this example the conversation config of the ai agent)

Format:

"overwrite_phone_recipient": {
  "type": "AI_AGENT",
  "receiver": "221316ae-8a9f-4f39-b7f8-f2e756b80a63"
}

any_contact_label_ids and exclude_contact_ids

By default, the campaign will call every contact that matches the label ids under any_contact_label_ids. To exclude contacts you must include the contact ids in the exclude_contact_ids list.

Format:

  "exclude_contact_ids": [
      "4667298e-8d5b-468e-8218-6a47925fe5f2",
      "aa145964-6d17-488d-a9be-09a43191f329"
  ],

List Campaigns

GET /api/v1/workspace/{workspace_id}/auto_dialer_campaigns

Use this endpoint to gather information about past and current campaigns. Filter on various attributes such as campaign type, status, mode, and date range.

Allowed query parameters.

Example

Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/seax-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/auto_dialer_campaigns?stage=INSTANCE&limit=10&offset=0&order_by=created_time%3Adesc' \
  -H 'accept: application/json' \
  -H 'X-API-Key: <your_api_key>'

Response:

{
  "data": [
    {
      "start_time": "2025-07-08T03:19:39",
      "end_time": "2025-07-08T03:30:00",
      "name": "test",
      "draft_name": null,
      "type": "AI_AGENT",
      "message": "Hello this is a test",
      "tts_language": "en-US",
      "tts_voice": "en-US-default",
      "ai_agent_id": "51fefba9-c3ee-40e8-a392-8bc14c639719",
      "ai_agent_conversation_config_id": "221316ae-8a9f-4f39-b7f8-f2e756b80a63",
      "max_attempts": 1,
      "max_dialers": 20,
      "capture_keypress": true,
      "capture_stt": false,
      "is_timezone_aware": false,
      "is_schedule": false,
      "contact_file_url": null,
      "timezone": null,
      "campaign_metadata": {
        "all_contact_labels": [],
        "any_contact_labels": [
          {
            "id": "7082ae15-43ae-472f-a83c-ee6462a0af83",
            "name": "test group",
            "color": "#0cb3c3"
          }
        ],
        "exclude_contacts": [
          {
            "id": "6e612221-594d-4c22-a305-ffe193b3c51f",
            "name": "Test User 1",
            "phone": "+11234567890"
          },
          {
            "id": "c0c9965b-1809-45e2-bcb6-1e1484a79abb",
            "name": "Test User 2",
            "phone": "+11234567890"
          },
          {
            "id": "a43b4e5d-edc7-4264-be19-2d39ab99d52e",
            "name": "Test User 3",
            "phone": "+11234567890"
          }
        ],
        "addition_contacts": [],
        "exclude_any_contact_labels": [],
        "exclude_all_contact_labels": [],
        "whatsapp_phone_only": false
      },
      "status": "FINISHED",
      "created_time": "2025-07-08T03:19:40.160564",
      "updated_time": "2025-07-08T03:19:40.160564",
      "id": "448ea794-0368-4604-a56f-f2350229d9e5",
      "mode": "WEB",
      "stage": "INSTANCE",
      "audio": null,
      "phones": [
        {
          "name": "dev-number-1",
          "enabled": true,
          "phone": "+19987654321",
          "country": "US",
          "whatsapp_device_id": null,
          "whatsapp_status": null,
          "generic_reply_message": "Welcome!",
          "dnc_reply_message": "Ok, we won't send you any other message.",
          "enabled_generic_reply": false,
          "enabled_dnc_reply": false,
          "type": "LOCAL",
          "source": "TWILIO",
          "phone_capability": {
            "sms": true,
            "mms": true,
            "voice": true,
            "fax": false,
            "whatsapp": false,
            "whatsapp_business_platform": false
          },
          "is_default": false,
          "enabled_recipient": true,
          "whatsapp_business_account_phone_id": null,
          "dialpad_available": false,
          "created_time": "2024-05-14T12:25:05.892618",
          "updated_time": "2025-07-08T03:19:40.160564",
          "id": "020086f5-fb0e-4a0c-920a-bbdd04f4381c",
          "call_recipient": {
            "id": "dde4ffb2-4c8c-412a-a8cf-33b77843cdb0",
            "type": "AI_AGENT",
            "receiver": "221316ae-8a9f-4f39-b7f8-f2e756b80a63"
          },
          "sms_recipient": null,
          "wabp_recipient": null,
          "verified_caller": null,
          "byoc_trunk": null
        }
      ],
      "statistics": {
        "human": 0,
        "machine": 0,
        "unknown": 0,
        "no_answer": 0,
        "total": 1
      },
      "contact_fields": [],
      "relative_time_config": null
    }
  ]
}

Get Campaign Details

GET /api/v1/workspace/{workspace_id}/auto_dialer_campaigns/{auto_dialer_campaign_id}

Get the information of a campaign given the workspace_id and the desired campaign_id

Example

Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/seax-api/api/v1/workspace/ffffffff-abcd-4000-0000-000000000000/auto_dialer_campaigns/448ea794-0368-4604-a56f-f2350229d9e5' \
  -H 'accept: application/json' \
  -H 'X-API-Key: <your_api_key>' \

Response:

{
  "start_time": "2025-07-08T03:19:39",
  "end_time": "2025-07-08T03:30:00",
  "name": "test",
  "draft_name": null,
  "type": "AI_AGENT",
  "message": "Hello this is a test",
  "tts_language": "en-US",
  "tts_voice": "en-US-default",
  "ai_agent_id": "51fefba9-c3ee-40e8-a392-8bc14c639719",
  "ai_agent_conversation_config_id": "221316ae-8a9f-4f39-b7f8-f2e756b80a63",
  "max_attempts": 1,
  "max_dialers": 20,
  "capture_keypress": true,
  "capture_stt": false,
  "is_timezone_aware": false,
  "is_schedule": false,
  "contact_file_url": null,
  "timezone": null,
  "campaign_metadata": {
    "all_contact_labels": [],
    "any_contact_labels": [
      {
        "id": "7082ae15-43ae-472f-a83c-ee6462a0af83",
        "name": "test group",
        "color": "#0cb3c3"
      }
    ],
    "exclude_contacts": [
      {
        "id": "6e612221-594d-4c22-a305-ffe193b3c51f",
        "name": "Test User 1",
        "phone": "+11234567890"
      },
      {
        "id": "c0c9965b-1809-45e2-bcb6-1e1484a79abb",
        "name": "Test User 2",
        "phone": "+11234567890"
      },
      {
        "id": "a43b4e5d-edc7-4264-be19-2d39ab99d52e",
        "name": "Test User 3",
        "phone": "+11234567890"
      }
    ],
    "addition_contacts": [],
    "exclude_any_contact_labels": [],
    "exclude_all_contact_labels": [],
    "whatsapp_phone_only": false
  },
  "status": "FINISHED",
  "created_time": "2025-07-08T03:19:40.160564",
  "updated_time": "2025-07-08T03:19:40.160564",
  "id": "448ea794-0368-4604-a56f-f2350229d9e5",
  "mode": "WEB",
  "stage": "INSTANCE",
  "audio": null,
  "phones": [
    {
      "name": "dev-number-1",
      "enabled": true,
      "phone": "+19987654321",
      "country": "US",
      "whatsapp_device_id": null,
      "whatsapp_status": null,
      "generic_reply_message": "Welcome!",
      "dnc_reply_message": "Ok, we won't send you any other message.",
      "enabled_generic_reply": false,
      "enabled_dnc_reply": false,
      "type": "LOCAL",
      "source": "TWILIO",
      "phone_capability": {
        "sms": true,
        "mms": true,
        "voice": true,
        "fax": false,
        "whatsapp": false,
        "whatsapp_business_platform": false
      },
      "is_default": false,
      "enabled_recipient": true,
      "whatsapp_business_account_phone_id": null,
      "dialpad_available": false,
      "created_time": "2024-05-14T12:25:05.892618",
      "updated_time": "2025-07-08T03:19:40.160564",
      "id": "020086f5-fb0e-4a0c-920a-bbdd04f4381c",
      "call_recipient": {
        "id": "dde4ffb2-4c8c-412a-a8cf-33b77843cdb0",
        "type": "AI_AGENT",
        "receiver": "221316ae-8a9f-4f39-b7f8-f2e756b80a63"
      },
      "sms_recipient": null,
      "wabp_recipient": null,
      "verified_caller": null,
      "byoc_trunk": null
    }
  ],
  "statistics": {
    "human": 0,
    "machine": 0,
    "unknown": 0,
    "no_answer": 0,
    "total": 1
  },
  "contact_fields": [],
  "relative_time_config": null
}