Skip to main content
POST
/
api
/
v1
/
campaigns
# Basic sales campaign — weekdays 09:00–17:00 New York
curl -X POST "https://app.talkover.ai/api/v1/campaigns" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Campaign Q1",
    "description": "Outbound sales campaign for Q1",
    "campaign_type": "sales",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "09:00", "end": "17:00"}
    ],
    "timezone": "America/New_York"
  }'

{
  "success": true,
  "data": {
    "id": "campaign-uuid-1",
    "name": "Sales Campaign Q1",
    "description": "Outbound sales campaign for Q1",
    "campaign_type": "sales",
    "status": "draft",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "end_date": null,
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "09:00", "end": "17:00"}
    ],
    "timezone": "America/New_York",
    "max_retries": 3,
    "retry_cooldown_hours": 24,
    "do_not_call_enabled": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Create Campaign

Create a new campaign with scheduling, retry policy, cooldowns, and do-not-call rules. Campaigns are created in draft status — call Update Campaign Status with "status": "active" to start dispatching calls.

​
Endpoint

POST /api/v1/campaigns

​
Request Headers

​
Authorization
string
required
Bearer token for authentication. Format: Bearer talq_your_environment_token_here
​
Content-Type
string
required
Must be set to application/json

​
Request Body

​
Identification

​
name
string
required
Campaign name. Max 255 characters.
​
description
string
Free-form description of the campaign.
​
campaign_type
string
required
Campaign category. Options: sales, follow_up, reminder, custom.
​
agent_id
string
required
UUID of the agent assigned to the campaign. The agent must exist in your environment.

​
Schedule

​
start_date
string
required
Date the campaign becomes eligible to dispatch calls. Format: YYYY-MM-DD.
​
end_date
string
Optional end date. Must be after start_date. Format: YYYY-MM-DD.
​
days_of_week
array
required
Array of weekday numbers when calls can be placed. 1 = Monday, 7 = Sunday. At least one value required.
​
call_time_ranges
array
required
Time windows (per day) during which calls can be dispatched. Array of objects with start and end in HH:MM format (24h). At least one window required. Each window’s end must be after its start.Example: [{"start": "09:00", "end": "12:00"}, {"start": "14:00", "end": "17:00"}]
​
timezone
string
required
IANA timezone for call_time_ranges (e.g., America/New_York, America/Sao_Paulo, Europe/London). Max 50 characters.

​
Retry & Cooldown

​
initial_call_delay
integer
Initial delay (in seconds) before the first call attempt. Default: 0.
​
max_retries
integer
Maximum retry attempts per contact. Range: 0–10. Default: 3.
​
retry_cooldown_hours
integer
Hours to wait between retry attempts. Range: 1–168. Default: 24.
​
auto_complete
boolean
When true, the campaign automatically transitions to completed once all contacts have been processed.
​
retry_on_no_conversion
boolean
When true, calls that completed but didn’t convert are retried after the cooldown.
​
enable_post_completion_cooldown
boolean
When true, applies a cooldown to all contacts after the campaign completes (prevents immediate re-engagement by another campaign).
​
post_completion_cooldown_hours
integer
Hours of cooldown applied to contacts after campaign completion. Range: 1–168. Default: 168.

​
Per-status cooldowns

These optional fields override retry_cooldown_hours for specific call outcomes. All in range 1–168 hours.
​
success_cooldown_hours
integer
Cooldown after a successful call.
​
voicemail_cooldown_hours
integer
Cooldown after reaching voicemail.
​
no_answer_cooldown_hours
integer
Cooldown after no-answer.
​
busy_cooldown_hours
integer
Cooldown after busy signal.
​
failed_cooldown_hours
integer
Cooldown after a failed call.

​
Do-Not-Call (DNC)

​
do_not_call_enabled
boolean
When true, contacts are checked against a DNC list before dispatching. Default: false.
​
do_not_call_list_source
string
Source of the DNC list. Options:
  • environment — DNC list shared across all campaigns in this environment
  • global — platform-wide DNC list
  • custom — campaign-specific list provided in do_not_call_custom_list
​
do_not_call_custom_list
array
Array of phone numbers (E.164) blocked for this campaign. Used only when do_not_call_list_source is custom.
​
auto_add_to_dnc_enabled
boolean
When true, contacts that match auto_dnc_trigger_statuses or auto_dnc_trigger_errors are automatically added to the DNC list.
​
auto_dnc_trigger_statuses
array
Call statuses that trigger auto-add to DNC. Example: ["completed", "voicemail"].
​
auto_dnc_trigger_errors
array
Call errors that trigger auto-add to DNC. Example: ["invalid_number", "disconnected"].

​
Examples

# Basic sales campaign — weekdays 09:00–17:00 New York
curl -X POST "https://app.talkover.ai/api/v1/campaigns" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Campaign Q1",
    "description": "Outbound sales campaign for Q1",
    "campaign_type": "sales",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "09:00", "end": "17:00"}
    ],
    "timezone": "America/New_York"
  }'

# Campaign with split call windows + custom DNC + per-status cooldowns
curl -X POST "https://app.talkover.ai/api/v1/campaigns" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Follow-up Campaign",
    "campaign_type": "follow_up",
    "agent_id": "agent-uuid-2",
    "start_date": "2024-01-15",
    "end_date": "2024-03-31",
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "10:00", "end": "12:00"},
      {"start": "14:00", "end": "17:00"}
    ],
    "timezone": "America/Sao_Paulo",
    "max_retries": 5,
    "retry_cooldown_hours": 48,
    "success_cooldown_hours": 168,
    "voicemail_cooldown_hours": 24,
    "no_answer_cooldown_hours": 12,
    "busy_cooldown_hours": 6,
    "failed_cooldown_hours": 72,
    "do_not_call_enabled": true,
    "do_not_call_list_source": "custom",
    "do_not_call_custom_list": ["+15551234567", "+15559876543"],
    "auto_add_to_dnc_enabled": true,
    "auto_dnc_trigger_statuses": ["completed"],
    "auto_dnc_trigger_errors": ["invalid_number"]
  }'

​
Response

​
Success Response (201 Created)

{
  "success": true,
  "data": {
    "id": "campaign-uuid-1",
    "name": "Sales Campaign Q1",
    "description": "Outbound sales campaign for Q1",
    "campaign_type": "sales",
    "status": "draft",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "end_date": null,
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "09:00", "end": "17:00"}
    ],
    "timezone": "America/New_York",
    "max_retries": 3,
    "retry_cooldown_hours": 24,
    "do_not_call_enabled": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

​
Response Fields

​
success
boolean
required
Indicates if the campaign was created successfully.
​
data
object
required
The created campaign object. New campaigns start in status: "draft". Use Update Campaign Status to activate.

​
Error Responses

​
422 Validation Error

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "agent_id": ["The selected agent id is invalid."],
    "call_time_ranges": ["The call time ranges field is required."],
    "call_time_ranges.0.end": ["The call time ranges.0.end must be a date after call time ranges.0.start."],
    "days_of_week.0": ["The days of week.0 must be between 1 and 7."]
  }
}

​
401 Unauthorized

{
  "message": "Missing Bearer Token"
}

​
403 Forbidden — Plan Limit Reached

{
  "success": false,
  "message": "Your plan does not allow creating more campaigns",
  "code": "CAMPAIGN_LIMIT_REACHED"
}

​
Notes

  • The campaign agent must already exist. Create it via Create Agent.
  • call_time_ranges replaces the older earliest_call_time/latest_call_time fields. Multiple windows let you skip lunch hours or split between morning and afternoon.
  • All *_cooldown_hours fields default to 24 if not provided. Use them to fine-tune retry behavior per call outcome.
  • Time windows are evaluated in the campaign’s timezone, not the caller’s local time.