Make Campaign Call

Initiate a call as part of a specific campaign. This endpoint allows you to manually trigger calls within a campaign context.

Overview

The Make Campaign Call endpoint allows you to initiate individual calls within an existing campaign. This endpoint leverages the campaign’s configuration and settings to ensure calls follow the established campaign rules and parameters.

Campaign Calls vs Individual Agent Calls

Campaign Calls - Strategic, Automated Outreach

Campaign calls are designed for systematic, large-scale customer engagement with advanced automation features:

Campaign-Specific Settings: Each call inherits the campaign’s configuration (agent, retry logic, cooldown periods, call hours)
Advanced Scheduling: Calls automatically respect business hours, timezone settings, and day-of-week restrictions
Retry Logic: Built-in retry mechanisms with configurable cooldown periods between attempts
Call Flow Management: Consistent call flows and messaging across all campaign calls
Performance Analytics: Comprehensive tracking and reporting at the campaign level
Compliance Features: Do-not-call list management and regulatory compliance tools
Batch Processing: Handle thousands of calls with intelligent queuing and rate limiting

Best for: Customer outreach campaigns, lead nurturing, appointment reminders, market research, and any scenario requiring consistent, automated calling with sophisticated rules.

Individual Agent Calls - Immediate, Personalized Interaction

Individual agent calls are perfect for instant, one-off interactions that require immediate attention:

Instant Execution: Calls are made immediately without waiting for campaign scheduling
Real-Time Context: Perfect for immediate follow-ups after form submissions or customer actions
Flexible Parameters: Customize call parameters on-the-fly for specific situations
Direct Control: Immediate control over call timing and execution
Personal Touch: Ideal for high-value interactions requiring immediate human attention

Best for: Form follow-ups, immediate customer service, urgent scheduling, high-priority leads, and any situation requiring instant response.

When to Use Each Approach

Scenario	Use Campaign Call	Use Individual Agent Call
Customer fills out contact form	❌	✅ Immediate follow-up
Lead nurturing over time	✅ Automated sequence	❌
Appointment reminders	✅ Scheduled outreach	❌
Urgent customer issue	❌	✅ Instant response
Market research survey	✅ Large-scale calling	❌
Sales follow-up after demo	❌	✅ Quick conversion
Customer satisfaction calls	✅ Systematic outreach	❌

Endpoint

POST /api/v1/campaigns/{campaign_id}/call

Path Parameters

campaign

string

required

The unique identifier of the campaign. You can find this in your dashboard under Campaigns.

Request Headers

Authorization

string

required

Bearer token for authentication. Format: Bearer talq_your_environment_token_here

Content-Type

string

required

Application JSON. Format: application/json

Request Body

string

required

Phone number to call in E.164 format (e.g., “+1234567890”).

payload

object

Replacement variables for the campaign agent prompt. Use this to personalize the conversation with dynamic data. Keys should match placeholders in your agent’s prompt.

context

object

Custom data to be sent back to your client via webhooks. This data is not used in the conversation but will be included in all webhook events related to this call, allowing you to track and associate calls with your internal records.

is_testing

boolean

Whether this is a test call. Test calls do not consume billing credits and are excluded from analytics aggregates. Default: false.

allow_duplicates

boolean

Whether to allow placing this call even if the same to number already has an active or queued call within the campaign. When false (default), the request returns 409 Conflict with the existing call’s details so you can avoid duplicate outreach. Default: false.

Example Requests

# Request 1: Make a regular campaign call
curl -X POST "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/call" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890"
  }'

# Request 2: Make a test campaign call
curl -X POST "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/call" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890",
    "is_testing": true
  }'

# Request 3: Make campaign call with payload and context
curl -X POST "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/call" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1987654321",
    "payload": {
      "customer_name": "John Doe",
      "order_id": "12345",
      "product_name": "Premium Plan"
    },
    "context": {
      "user_id": "user_123",
      "source": "web_app",
      "campaign_batch": "2024_Q1"
    }
  }'

Response

Success Response (201 Created)

{
  "campaign_call": {
    "id": "call-uuid-1",
    "campaign_id": "campaign-uuid-1",
    "to": "+1234567890",
    "status": "queued",
    "scheduled_at": "2024-01-15T10:30:00Z",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "campaign": {
    "id": "campaign-uuid-1",
    "name": "Q1 Outreach",
    "status": "active"
  }
}

Response Fields

campaign_call

object

required

Details of the queued campaign call.

Show Campaign Call Object

string

required

Unique identifier for the campaign call. Use this to track status and correlate with webhook events.

campaign_id

string

required

The campaign this call belongs to.

string

required

The phone number that will be called.

status

string

required

Initial status of the campaign call. Possible values:

queued — call accepted and waiting for dispatch
scheduled — call scheduled to be placed at a future time within campaign hours

scheduled_at

string

ISO 8601 timestamp when the call is expected to be placed.

created_at

string

required

ISO 8601 timestamp when the campaign call was created.

campaign

object

required

Summary of the parent campaign at the time the call was queued.

Error Responses

409 Conflict — Duplicate Call

Returned when a call to the same to number is already active or queued in this campaign and allow_duplicates is false.

{
  "success": false,
  "message": "A call to this number already exists in this campaign",
  "existing_call": {
    "id": "call-uuid-existing",
    "campaign_id": "campaign-uuid-1",
    "to": "+1234567890",
    "status": "queued",
    "created_at": "2024-01-15T09:50:00Z"
  }
}

To override this behavior intentionally (e.g., a follow-up call), pass "allow_duplicates": true in the request body.

404 Not Found

{
  "success": false,
  "message": "Campaign not found"
}

422 Validation Error

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "to": [
      "The to field is required."
    ],
    "to": [
      "The to must be a valid phone number."
    ]
  }
}

400 Bad Request

{
  "success": false,
  "message": "Campaign is not active"
}

401 Unauthorized

{
  "success": false,
  "message": "Unauthorized"
}

403 Forbidden

{
  "success": false,
  "message": "Cannot make calls for this campaign"
}

429 Too Many Requests

{
  "success": false,
  "message": "Rate limit exceeded"
}

500 Server Error

{
  "success": false,
  "message": "Internal server error."
}

Error Codes

Code	Description	HTTP Status
`CAMPAIGN_NOT_FOUND`	Specified campaign does not exist	404
`VALIDATION_ERROR`	Request validation failed	422
`CAMPAIGN_NOT_ACTIVE`	Campaign is not in active status	400
`DUPLICATE_CALL`	An existing call to the same number is queued or active	409
`INVALID_TOKEN`	Authentication token is invalid or missing	401
`FORBIDDEN`	Cannot make calls for this campaign	403
`RATE_LIMIT_EXCEEDED`	Rate limit exceeded	429
`SERVER_ERROR`	Internal server error occurred	500

Campaign Status Requirements

Campaign Status	Can Make Calls	Notes
`draft`	❌ No	Campaign must be active
`active`	✅ Yes	Calls can be made
`paused`	❌ No	Campaign is paused
`completed`	❌ No	Campaign has finished
`cancelled`	❌ No	Campaign was cancelled

Important Notes

Campaign context. Calls made through this endpoint are associated with the specific campaign.

Campaign settings. The call will follow the campaign’s configuration (agent, retry logic, etc.).

Test calls. Use is_testing: true for test calls that don’t count toward billing.

Active campaigns only. Calls can only be made for campaigns in “active” status.

Rate limits. Be aware of rate limits when making multiple calls.

Best Practices

Check campaign status - Verify the campaign is active before making calls
Use test calls - Test your integration with is_testing: true first
Handle rate limits - Implement proper rate limiting in your application
Validate phone numbers - Ensure phone numbers are in E.164 format
Monitor call status - Track call status using the returned call_id

Get Campaign: GET /api/v1/campaigns/{campaign_id}
Update Campaign Status: PATCH /api/v1/campaigns/{campaign_id}/status
Make a Call: POST /api/v1/calls
List Calls: GET /api/v1/calls
Get Agent Calls: GET /api/v1/agents/{agent_id}/calls

Get Started

Concepts

API Reference

Guides

Make Campaign Call

Make Campaign Call

Overview

Campaign Calls vs Individual Agent Calls

Campaign Calls - Strategic, Automated Outreach

Individual Agent Calls - Immediate, Personalized Interaction

When to Use Each Approach

Endpoint

Path Parameters

Request Headers

Request Body

Example Requests

Response

Success Response (201 Created)

Response Fields

Error Responses

409 Conflict — Duplicate Call

404 Not Found

422 Validation Error

400 Bad Request

401 Unauthorized

403 Forbidden

429 Too Many Requests

500 Server Error

Error Codes

Campaign Status Requirements

Important Notes

Best Practices

Get Started

Concepts

API Reference

Guides

Documentation Index

​Make Campaign Call

​Overview

​Campaign Calls vs Individual Agent Calls

​Campaign Calls - Strategic, Automated Outreach

​Individual Agent Calls - Immediate, Personalized Interaction

​When to Use Each Approach

​Endpoint

​Path Parameters

​Request Headers

​Request Body

​Example Requests

​Response

​Success Response (201 Created)

​Response Fields

​Error Responses

​409 Conflict — Duplicate Call

​404 Not Found

​422 Validation Error

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​429 Too Many Requests

​500 Server Error

​Error Codes

​Campaign Status Requirements

​Important Notes

​Best Practices

​Related Endpoints

Make Campaign Call

Overview

Campaign Calls vs Individual Agent Calls

Campaign Calls - Strategic, Automated Outreach

Individual Agent Calls - Immediate, Personalized Interaction

When to Use Each Approach

Endpoint

Path Parameters

Request Headers

Request Body

Example Requests

Response

Success Response (201 Created)

Response Fields

Error Responses

409 Conflict — Duplicate Call

404 Not Found

422 Validation Error

400 Bad Request

401 Unauthorized

403 Forbidden

429 Too Many Requests

500 Server Error

Error Codes

Campaign Status Requirements

Important Notes

Best Practices

Related Endpoints