Skip to content
revox
Get started
API Reference
Campaigns

Create a campaign

campaigns.create(CampaignCreateParams**kwargs) -> CampaignCreateResponse
POST/campaigns

Create a new outbound calling campaign and launch it immediately. If scheduled_at is set, all calls will be queued until the specified time instead of starting right away.

ParametersExpand Collapse
assistant_id: str

The ID of the assistant to use

contacts: Iterable[Contact]

The list of contacts to call

prompt_variables: Dict[str, str]
to_phone_number: str
name: str

The name of the campaign

minLength1
call_retry_config: Optional[CallRetryConfig]

Override retry configuration for calls in this campaign. If not provided, uses the assistant's retry config.

calling_windows: Iterable[CallRetryConfigCallingWindow]
calling_window_end_time: str

End time for the calling window in the recipient's timezone (or timezone_override if provided). Format: 'HH:mm' (24-hour) or 'H:mma' (12-hour). Examples: '17:00', '6pm'. Default: '18:00'.

calling_window_start_time: str

Start time for the calling window in the recipient's timezone (or timezone_override if provided). Format: 'HH:mm' (24-hour) or 'H:mma' (12-hour). Examples: '09:00', '10am'. Default: '10:00'.

retry_delay_seconds: int

Delay between retry attempts in seconds. Default: 7200 (2 hours).

exclusiveMinimum0
maximum9007199254740991
max_retry_attempts: int

Maximum number of call retry attempts. Default: 3.

exclusiveMinimum0
maximum9007199254740991
timezone: Optional[str]

Optional IANA timezone identifier to override the automatic timezone detection from phone number. If not provided, timezone is determined from the recipient's phone number country code. Examples: 'America/New_York', 'Europe/Paris'.

from_phone_number: Optional[str]

The phone number to use for outbound calls (E.164 format, e.g., +1234567890)

max_concurrent_calls: Optional[float]

Maximum number of concurrent calls allowed for this campaign

minimum1
scheduled_at: Optional[Union[Union[str, datetime], object]]

Schedule all calls in this campaign to start at a specific date and time (ISO 8601 format)

One of the following:
Union[str, datetime]
object
ReturnsExpand Collapse
class CampaignCreateResponse: …
campaign: Campaign
id: str
assistant_id: str
created_at: object
is_cancelled: bool
name: str
organization_id: str
status: Literal["draft", "running", "paused", "completed"]
One of the following:
"draft"
"running"
"paused"
"completed"
updated_at: object
assistant: Optional[CampaignAssistant]
id: str
background_sound: Optional[Literal["audio/office.ogg"]]

The background sound to play during the call. Useful to give the impression that your AI agent is in an office.

calendly: Optional[CampaignAssistantCalendly]
connection_id: str

The connection ID representing the link between your Calendly account and Revox.

event_type_id: str

The event type ID representing the event type to schedule. (eg: https://api.calendly.com/event_types/b2330295-2a91-4a1d-bb73-99e7707663d5)

call_retry_config: Optional[CampaignAssistantCallRetryConfig]

Configuration for call retry behavior including time windows, delays, and max iterations. If not provided, defaults will be used.

calling_windows: List[CampaignAssistantCallRetryConfigCallingWindow]
calling_window_end_time: str

End time for the calling window in the recipient's timezone (or timezone_override if provided). Format: 'HH:mm' (24-hour) or 'H:mma' (12-hour). Examples: '17:00', '6pm'. Default: '18:00'.

calling_window_start_time: str

Start time for the calling window in the recipient's timezone (or timezone_override if provided). Format: 'HH:mm' (24-hour) or 'H:mma' (12-hour). Examples: '09:00', '10am'. Default: '10:00'.

retry_delay_seconds: int

Delay between retry attempts in seconds. Default: 7200 (2 hours).

exclusiveMinimum0
maximum9007199254740991
max_retry_attempts: int

Maximum number of call retry attempts. Default: 3.

exclusiveMinimum0
maximum9007199254740991
timezone: Optional[str]

Optional IANA timezone identifier to override the automatic timezone detection from phone number. If not provided, timezone is determined from the recipient's phone number country code. Examples: 'America/New_York', 'Europe/Paris'.

created_at: object
end_of_call_sentence: Optional[str]
first_sentence: Optional[str]
first_sentence_delay_ms: int

Delay in milliseconds before speaking the first sentence. Default: 400.

minimum-9007199254740991
maximum9007199254740991
first_sentence_mode: Literal["generated", "static", "none"]
One of the following:
"generated"
"static"
"none"
ivr_navigation_enabled: bool

Enable IVR navigation tools. When enabled, the assistant can send DTMF tones and skip turns to navigate phone menus.

llm_model: CampaignAssistantLlmModel
One of the following:
class CampaignAssistantLlmModelUnionMember0: …
name: Literal["gpt-4.1", "ministral-3-8b-instruct"]
One of the following:
"gpt-4.1"
"ministral-3-8b-instruct"
type: Literal["dedicated-instance"]
class CampaignAssistantLlmModelUnionMember1: …
openrouter_model_id: str

The model ID to use from OpenRouter. eg: openai/gpt-4.1

openrouter_provider: str

The provider to use from OpenRouter. eg: nebius, openai, azure, etc.

type: Literal["openrouter"]

Use a model from OpenRouter.

max_call_duration_secs: float

The maximum duration of the call in seconds. This is the maximum time the call will be allowed to run.

name: str
organization_id: str
prompt: str
structured_output_config: Optional[List[CampaignAssistantStructuredOutputConfig]]

The structured output config to use for the call. This is used to extract the data from the call (like email, name, company name, etc.).

name: str
minLength1
required: bool
type: Literal["string", "number", "boolean", 3 more]
One of the following:
"string"
"number"
"boolean"
"enum"
"date"
"datetime"
description: Optional[str]
enum_options: Optional[List[str]]
transfer_phone_number: Optional[str]

Phone number to transfer calls to when users request to speak to a human agent.

updated_at: object
voice: Optional[CampaignAssistantVoice]
id: str

The ID of the voice.

minLength1
provider: Literal["cartesia", "elevenlabs"]

The provider of the voice.

One of the following:
"cartesia"
"elevenlabs"
speed: Optional[float]

The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2. Default is 1.0.

minimum0.6
maximum1.5
voicemail_message: Optional[str]

If set, when voicemail is detected the agent will speak this message then hang up; if null, hang up immediately.

webhook_url: Optional[str]

The webhook URL to call when the call is completed.

faq_items: Optional[List[CampaignAssistantFaqItem]]
answer: str
question: str
id: Optional[str]
needs_human_answer: Optional[bool]
source: Optional[Literal["human", "ai"]]
One of the following:
"human"
"ai"
pending_faq_count: Optional[float]
call_retry_config: Optional[CampaignCallRetryConfig]

Configuration for call retry behavior including time windows, delays, and max iterations. If not provided, defaults will be used.

calling_windows: List[CampaignCallRetryConfigCallingWindow]
calling_window_end_time: str

End time for the calling window in the recipient's timezone (or timezone_override if provided). Format: 'HH:mm' (24-hour) or 'H:mma' (12-hour). Examples: '17:00', '6pm'. Default: '18:00'.

calling_window_start_time: str

Start time for the calling window in the recipient's timezone (or timezone_override if provided). Format: 'HH:mm' (24-hour) or 'H:mma' (12-hour). Examples: '09:00', '10am'. Default: '10:00'.

retry_delay_seconds: int

Delay between retry attempts in seconds. Default: 7200 (2 hours).

exclusiveMinimum0
maximum9007199254740991
max_retry_attempts: int

Maximum number of call retry attempts. Default: 3.

exclusiveMinimum0
maximum9007199254740991
timezone: Optional[str]

Optional IANA timezone identifier to override the automatic timezone detection from phone number. If not provided, timezone is determined from the recipient's phone number country code. Examples: 'America/New_York', 'Europe/Paris'.

from_phone_number: Optional[str]
max_concurrent_calls: Optional[float]
row_stats: Optional[CampaignRowStats]
calling: float
completed: float
failed: float
pending: float
retry: float
total: float
scheduled_at: Optional[object]

Create a campaign

import os
from revox import Revox

client = Revox(
    api_key=os.environ.get("REVOX_API_KEY"),  # This is the default and can be omitted
)
campaign = client.campaigns.create(
    assistant_id="assistant_id",
    contacts=[{
        "prompt_variables": {
            "foo": "string"
        },
        "to_phone_number": "to_phone_number",
    }],
    name="x",
)
print(campaign.campaign)
{
  "campaign": {
    "id": "id",
    "assistant_id": "assistant_id",
    "created_at": {},
    "is_cancelled": true,
    "name": "name",
    "organization_id": "organization_id",
    "status": "draft",
    "updated_at": {},
    "assistant": {
      "id": "id",
      "background_sound": "audio/office.ogg",
      "calendly": {
        "connection_id": "connection_id",
        "event_type_id": "event_type_id"
      },
      "call_retry_config": {
        "calling_windows": [
          {
            "calling_window_end_time": "calling_window_end_time",
            "calling_window_start_time": "calling_window_start_time",
            "retry_delay_seconds": 1
          }
        ],
        "max_retry_attempts": 1,
        "timezone": "timezone"
      },
      "created_at": {},
      "end_of_call_sentence": "end_of_call_sentence",
      "first_sentence": "first_sentence",
      "first_sentence_delay_ms": -9007199254740991,
      "first_sentence_mode": "generated",
      "ivr_navigation_enabled": true,
      "llm_model": {
        "name": "gpt-4.1",
        "type": "dedicated-instance"
      },
      "max_call_duration_secs": 0,
      "name": "name",
      "organization_id": "organization_id",
      "prompt": "prompt",
      "structured_output_config": [
        {
          "name": "x",
          "required": true,
          "type": "string",
          "description": "description",
          "enum_options": [
            "string"
          ]
        }
      ],
      "transfer_phone_number": "transfer_phone_number",
      "updated_at": {},
      "voice": {
        "id": "x",
        "provider": "cartesia",
        "speed": 0.6
      },
      "voicemail_message": "voicemail_message",
      "webhook_url": "webhook_url",
      "faq_items": [
        {
          "answer": "answer",
          "question": "question",
          "id": "id",
          "needs_human_answer": true,
          "source": "human"
        }
      ],
      "pending_faq_count": 0
    },
    "call_retry_config": {
      "calling_windows": [
        {
          "calling_window_end_time": "calling_window_end_time",
          "calling_window_start_time": "calling_window_start_time",
          "retry_delay_seconds": 1
        }
      ],
      "max_retry_attempts": 1,
      "timezone": "timezone"
    },
    "from_phone_number": "from_phone_number",
    "max_concurrent_calls": 0,
    "row_stats": {
      "calling": 0,
      "completed": 0,
      "failed": 0,
      "pending": 0,
      "retry": 0,
      "total": 0
    },
    "scheduled_at": {}
  }
}
Returns Examples
{
  "campaign": {
    "id": "id",
    "assistant_id": "assistant_id",
    "created_at": {},
    "is_cancelled": true,
    "name": "name",
    "organization_id": "organization_id",
    "status": "draft",
    "updated_at": {},
    "assistant": {
      "id": "id",
      "background_sound": "audio/office.ogg",
      "calendly": {
        "connection_id": "connection_id",
        "event_type_id": "event_type_id"
      },
      "call_retry_config": {
        "calling_windows": [
          {
            "calling_window_end_time": "calling_window_end_time",
            "calling_window_start_time": "calling_window_start_time",
            "retry_delay_seconds": 1
          }
        ],
        "max_retry_attempts": 1,
        "timezone": "timezone"
      },
      "created_at": {},
      "end_of_call_sentence": "end_of_call_sentence",
      "first_sentence": "first_sentence",
      "first_sentence_delay_ms": -9007199254740991,
      "first_sentence_mode": "generated",
      "ivr_navigation_enabled": true,
      "llm_model": {
        "name": "gpt-4.1",
        "type": "dedicated-instance"
      },
      "max_call_duration_secs": 0,
      "name": "name",
      "organization_id": "organization_id",
      "prompt": "prompt",
      "structured_output_config": [
        {
          "name": "x",
          "required": true,
          "type": "string",
          "description": "description",
          "enum_options": [
            "string"
          ]
        }
      ],
      "transfer_phone_number": "transfer_phone_number",
      "updated_at": {},
      "voice": {
        "id": "x",
        "provider": "cartesia",
        "speed": 0.6
      },
      "voicemail_message": "voicemail_message",
      "webhook_url": "webhook_url",
      "faq_items": [
        {
          "answer": "answer",
          "question": "question",
          "id": "id",
          "needs_human_answer": true,
          "source": "human"
        }
      ],
      "pending_faq_count": 0
    },
    "call_retry_config": {
      "calling_windows": [
        {
          "calling_window_end_time": "calling_window_end_time",
          "calling_window_start_time": "calling_window_start_time",
          "retry_delay_seconds": 1
        }
      ],
      "max_retry_attempts": 1,
      "timezone": "timezone"
    },
    "from_phone_number": "from_phone_number",
    "max_concurrent_calls": 0,
    "row_stats": {
      "calling": 0,
      "completed": 0,
      "failed": 0,
      "pending": 0,
      "retry": 0,
      "total": 0
    },
    "scheduled_at": {}
  }
}