Skip to main content
GET
/
api
/
audio-campaign
/
{campaign_id}
Start Campaign
curl --request GET \
  --url https://api.example.com/api/audio-campaign/{campaign_id}
{
  "success": "<string>",
  "error": "<string>",
  "warning": "<string>"
}

​
Endpoint

GET /api/audio-campaign/{campaign_id}

​
Authentication

This endpoint requires WordPress Integration Token authentication.

​
Parameters

​
campaign_id
integer
required
Unique identifier of the campaign to start
​
user_token
string
required
WordPress integration token for authenticating the user

​
Request

curl -X GET "https://your-domain.com/api/audio-campaign/1?user_token=YOUR_USER_TOKEN" \
  -H "Accept: application/json"

​
Response

​
Success Response

​
success
string
Success message indicating the campaign has been started
{
  "success": "Campaign Started successfully"
}

​
Campaign Validation Process

When you start a campaign, the API performs the following validation checks in order:
1

Balance Verification

Checks if the user has sufficient balance to execute the campaign.Error: Insufficient balance (401)
2

Configuration Check

Validates that the campaign has both group_id and provider configured.Error: Campaign has no group or provider (401)
3

Hourly Quota Check

Verifies that the hourly quota for the provider hasn’t been exceeded.Warning: Hourly quota crossed (400)
4

Twilio Connection

Tests the Twilio provider connection to ensure it’s active.Error: Connection Failed. Please check your with administrator (401)
5

Schedule Creation

Creates a campaign schedule record with status PENDING.

​
Campaign Schedule Record

When a campaign is successfully started, a CampaignSchedule record is created with the following data: 
{
  "user_id": 123,
  "campaign_id": 1,
  "group_id": 5,
  "provider": "twilio_primary",
  "say": "Hello! We have a special offer for you.",
  "audio": "https://your-domain.com/storage/campaigns/audio1.mp3",
  "xml": null,
  "start_at": "2026-03-04T15:30:00.000000Z",
  "status": "PENDING"
}

​
Error Responses

​
error
string
Error message describing what went wrong
​
warning
string
Warning message for non-critical issues
Status CodeResponse KeyDescription
200successCampaign started successfully
400warningHourly quota exceeded
401errorUnauthorized - Invalid user_token
401errorInsufficient account balance
401errorCampaign missing group or provider
401errorTwilio connection failed

​
Notes

Starting a campaign creates a schedule but doesn’t immediately execute it. The campaign will be processed by the system’s queue worker.
  • Campaign execution respects hourly quota limits per provider
  • Twilio connection is validated before scheduling
  • Account balance is checked before proceeding
  • Campaign must have both group_id and provider configured

​
Example Use Cases

​
Start Campaign from WordPress Admin

<?php
// WordPress AJAX handler to start a campaign
add_action('wp_ajax_start_campaign', 'handle_start_campaign');

function handle_start_campaign() {
    check_ajax_referer('start_campaign_nonce', 'nonce');
    
    $campaign_id = intval($_POST['campaign_id']);
    $user_token = get_user_meta(get_current_user_id(), 'teleman_user_token', true);
    
    $response = wp_remote_get(
        "https://your-domain.com/api/audio-campaign/{$campaign_id}?user_token={$user_token}"
    );
    
    if (is_wp_error($response)) {
        wp_send_json_error(['message' => 'Failed to start campaign']);
    }
    
    $result = json_decode(wp_remote_retrieve_body($response), true);
    
    if (isset($result['success'])) {
        wp_send_json_success(['message' => $result['success']]);
    } else {
        wp_send_json_error(['message' => $result['error'] ?? 'Unknown error']);
    }
}

​
Start Campaign with Error Handling

async function startCampaign(campaignId, userToken) {
  try {
    const response = await fetch(
      `https://your-domain.com/api/audio-campaign/${campaignId}?user_token=${userToken}`
    );
    
    const result = await response.json();
    
    if (response.ok && result.success) {
      console.log('✓ Campaign started successfully');
      return { success: true, message: result.success };
    } else if (response.status === 400 && result.warning) {
      console.warn('⚠ Warning:', result.warning);
      return { success: false, warning: result.warning };
    } else {
      console.error('✗ Error:', result.error);
      return { success: false, error: result.error };
    }
  } catch (error) {
    console.error('✗ Network error:', error);
    return { success: false, error: 'Network error occurred' };
  }
}

// Usage
const result = await startCampaign(1, 'YOUR_USER_TOKEN');
if (result.success) {
  alert('Campaign started!');
} else if (result.warning) {
  alert(`Warning: ${result.warning}`);
} else {
  alert(`Error: ${result.error}`);
}

List Campaigns

Get all campaigns for authenticated user

Authentication

Learn about authentication methods

Build docs developers (and LLMs) love

Get started for freeTalk to us