Campaign Deep Dive

Advanced campaign configuration including modes, channels, caller ID strategy, AMD detection, and stats interpretation.

Master the campaign system — from mode configuration to caller ID rotation to reading real-time stats. Campaigns support two channels: voice and SMS.

Campaign Channels

Set channel when creating a campaign:

Channel	Description	Sending window	Pacing
`voice` (default)	Outbound calling with AMD, VM deposit, AI handoff	8 AM – 9 PM (TCPA)	`calls_per_second` batch rate
`sms`	Human-like bulk SMS	7 AM – 7 PM	~4 msgs/DID/hr, 15-min gaps

Campaign Modes

The mode field is a flexible JSON object. Fields vary by channel.

Voice mode fields

Field	Type	Description
`ai`	boolean	Enable AI agent for live calls
`voicemailAudioUrl`	string	URL of audio to play when voicemail is detected
`calls_per_second`	number	Dialing rate limit
`max_retries`	number	Maximum retry attempts per prospect
`retry_delay`	string	Delay between retries (e.g. `"4h"`, `"30m"`)

SMS mode fields

Field	Type	Description
`message`	string	Required. The SMS body text sent to each prospect

Common Mode Configurations

{
  "channel": "voice",
  "mode": {
    "voicemailAudioUrl": "https://api.trunx.io/audio/aud_001/file",
    "max_retries": 2,
    "retry_delay": "4h"
  }
}

Drop a voicemail on every machine. Retry no-answers up to 2 times.

{
  "channel": "voice",
  "mode": {
    "ai": true,
    "voicemailAudioUrl": "https://api.trunx.io/audio/aud_001/file",
    "calls_per_second": 10,
    "max_retries": 2,
    "retry_delay": "4h"
  }
}

AI agent handles live pickups. Voicemail gets a recording. No-answers retry.

{
  "channel": "voice",
  "mode": {
    "ai": true,
    "calls_per_second": 5
  }
}

Only spend AI minutes on humans who actually pick up. Skip voicemail.

{
  "channel": "sms",
  "mode": {
    "message": "Hi, this is Acme Solar. We have a special offer for homeowners in your area. Reply YES to learn more."
  }
}

Human-like SMS drip. ~4 messages per DID per hour, 15-minute gaps between sends.

AMD Detection

Answering Machine Detection listens to the first few seconds of a call to determine who picked up.

Result	Meaning
`human`	A person answered
`machine`	Voicemail greeting playing (no beep yet)
`machine_end_beep`	Greeting finished, beep detected — safe to play audio
`unknown`	Could not determine — defaults to human behavior

Trunx supports multiple AMD engines optimized for different latency and cost profiles. Self-hosted customers can configure the AMD provider via the ACTIVE_AMD_PROVIDER environment variable.

The machine_end_beep result is critical for voicemail deposits. Your audio starts playing immediately after the beep, so the recipient hears a clean message.

Caller ID Strategy

The callerIdStrategy field controls which DID is used for each dial. It is a flexible JSON object — all fields are optional with sensible defaults.

Example configuration for a 5,000-prospect campaign:

{
  "callerIdStrategy": {
    "selection": "health_score",
    "local_presence": true
  }
}

The callerIdStrategy field uses camelCase (not caller_id_strategy). This applies to the create campaign request body.

Reading Campaign Stats

GET /campaigns/:id/stats

curl https://api.trunx.io/campaigns/camp_abc123/stats \
  -H "Authorization: Bearer $TRUNX_API_KEY"

The response is a flat JSON object with camelCase field names:

{
  "total": 5000,
  "queued": 2100,
  "dialing": 10,
  "completed": 2890,
  "failed": 49,
  "cancelled": 0,
  "noAnswer": 284,
  "busy": 42,
  "voicemail": 2312,
  "humanConnected": 203,
  "sending": 0,
  "sent": 0,
  "delivered": 0,
  "progress": 57
}

Fields explained

Field	Type	Meaning
`total`	number	Total prospects in the campaign
`queued`	number	Waiting to be dialed/sent
`dialing`	number	Voice call currently in-progress
`completed`	number	Finished (any terminal outcome including delivered)
`failed`	number	Call/message failed
`cancelled`	number	Cancelled before dialing/sending
`noAnswer`	number	No pickup within ring timeout (voice)
`busy`	number	Line busy (voice)
`voicemail`	number	AMD detected machine, audio deposited (voice)
`humanConnected`	number	Human answered, connected to agent (voice)
`sending`	number	SMS being sent (SMS)
`sent`	number	SMS sent, awaiting delivery confirmation (SMS)
`delivered`	number	SMS delivered to recipient (SMS)
`progress`	number	Completion percentage (0-100)

Campaign Lifecycle

Campaigns follow a strict status flow.

created → dialing → completed
              ↓
          paused → dialing (resume)
              ↓
         cancelled

Actions by Status

Status	Allowed Actions
`created`	Start, cancel
`dialing`	Pause, cancel
`paused`	Resume, cancel
`completed`	None (terminal)
`cancelled`	None (terminal)
`failed`	None (terminal)

Lifecycle endpoints

All lifecycle endpoints return { id, name, status, channel }:

Endpoint	Required Status
`POST /campaigns/:id/start`	`created`
`POST /campaigns/:id/pause`	`dialing`
`POST /campaigns/:id/resume`	`paused`
`POST /campaigns/:id/cancel`	Any non-terminal

When a campaign is cancelled, all remaining queued prospects are automatically marked as cancelled.

Adding Prospects

Prospects are added separately from campaign creation using POST /campaigns/:id/prospects.

The request body takes a phones array of E.164 numbers (1 to 10,000 per request):

curl -X POST https://api.trunx.io/campaigns/camp_abc123/prospects \
  -H "Authorization: Bearer $TRUNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phones": ["+17145551001", "+16195551002", "+18185551003"]
  }'

Response:

{
  "added": 3
}

You can only add prospects when the campaign is in created or paused status.

Campaign Deep Dive

On this page