> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create campaign

> Create a draft call, WhatsApp, or SMS campaign in Famulor via API. Add leads, then start with Update campaign status.

Create a new campaign. Campaigns start in `draft` — add leads, then start with [Update campaign status](/en/api-reference/campaigns/update-status).

Supported channels:

* **`call`** (default) — outbound voice with an OUTBOUND assistant
* **`whatsapp`** — approved WhatsApp template via one of your senders
* **`sms`** — SMS body from an SMS-capable number (may be temporarily unavailable on the platform)

### Request body

#### Shared

<ParamField body="name" type="string" required>
  Campaign name. Maximum 255 characters.
</ParamField>

<ParamField body="channel" type="string" default="call">
  `call`, `whatsapp`, or `sms`.
</ParamField>

<ParamField body="timezone" type="string">
  IANA timezone for the send/call window (e.g. `America/New_York`). Defaults to the assistant timezone for call campaigns, otherwise your account timezone.
</ParamField>

<ParamField body="schedule_windows" type="array">
  Preferred schedule: one or more daily windows as objects with `start` and `end` in `HH:MM`. Overnight windows are supported when `end` is earlier than `start` (e.g. `16:00` → `02:00`).
</ParamField>

<ParamField body="allowed_hours_start_time" type="string" default="00:00">
  Legacy single-window start (`HH:MM`). Used if `schedule_windows` is omitted.
</ParamField>

<ParamField body="allowed_hours_end_time" type="string" default="23:59">
  Legacy single-window end (`HH:MM`). Overnight when `end` \< `start`.
</ParamField>

<ParamField body="scheduled_start_at" type="string">
  Optional ISO datetime. When set, the campaign can be scheduled to auto-start at that time.
</ParamField>

<ParamField body="allowed_days" type="array" default="all 7 days">
  Weekdays: `monday` … `sunday`.
</ParamField>

<ParamField body="max_retries" type="integer" default="3">
  Max retry attempts per lead. Range: 1–5.
</ParamField>

<ParamField body="retry_interval" type="integer" default="60">
  Minutes between retries. Range: 10–4320.
</ParamField>

<ParamField body="mark_complete_when_no_leads" type="boolean" default="true">
  Automatically mark the campaign complete when no remaining work is left.
</ParamField>

#### Call campaigns

<ParamField body="assistant_id" type="integer">
  Required for `channel=call`. Must be an OUTBOUND assistant you own.
</ParamField>

<ParamField body="max_calls_in_parallel" type="integer" default="3">
  Concurrent calls (plan-bounded, max 10).
</ParamField>

<ParamField body="phone_number_ids" type="array">
  Outbound from-number IDs available to your account.
</ParamField>

<ParamField body="retry_on_voicemail" type="boolean">
  Retry when a call hits voicemail.
</ParamField>

<ParamField body="retry_on_goal_incomplete" type="boolean">
  Keep retrying until a boolean post-call goal variable is true.
</ParamField>

<ParamField body="goal_completion_variable" type="string">
  Boolean post-call schema variable name used with `retry_on_goal_incomplete`.
</ParamField>

<ParamField body="fallback_channel" type="string">
  Optional call→text follow-up after max call retries: `whatsapp` or `sms`.
</ParamField>

<ParamField body="fallback_whatsapp_sender_id" type="integer">
  Required when `fallback_channel=whatsapp`.
</ParamField>

<ParamField body="fallback_whatsapp_template_id" type="integer">
  Required when `fallback_channel=whatsapp`. Must be an approved template on that sender.
</ParamField>

<ParamField body="fallback_sms_from_phone_number_id" type="integer">
  Required when `fallback_channel=sms`.
</ParamField>

<ParamField body="fallback_sms_body" type="string">
  Required when `fallback_channel=sms`. Supports `{{variable}}` placeholders.
</ParamField>

<ParamField body="fallback_variable_mapping" type="object">
  Maps WhatsApp template placeholders (e.g. `"1"`) to lead variable keys for the fallback send.
</ParamField>

#### WhatsApp campaigns

<ParamField body="whatsapp_sender_id" type="integer">
  Required for `channel=whatsapp`. Sender you own.
</ParamField>

<ParamField body="whatsapp_template_id" type="integer">
  Required for `channel=whatsapp`. Approved template on that sender.
</ParamField>

<ParamField body="text_variable_mapping" type="object">
  Maps template placeholders (e.g. `"1"`) to lead variable keys.
</ParamField>

<ParamField body="messages_per_minute" type="integer">
  Per-campaign send rate (1–10). WhatsApp campaigns also share a user-wide pool of 10 in-flight sends across all your active WhatsApp campaigns.
</ParamField>

#### SMS campaigns

<ParamField body="sms_from_phone_number_id" type="integer">
  Required for `channel=sms`. Must be SMS-capable and available to you.
</ParamField>

<ParamField body="sms_body" type="string">
  Required for `channel=sms`. Max 1600 characters. Supports `{{variable}}` placeholders.
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  Created campaign (same shape as [Get campaign](/en/api-reference/campaigns/get)), including channel, schedule, text config, and fallback fields.
</ResponseField>

### Error responses

<ResponseField name="422 Unprocessable Entity">
  Plan limit, invalid assistant/sender/template, disabled channel, or validation errors.
</ResponseField>

<ResponseExample>
  ```json 201 Created theme={null} theme={null}
  {
    "message": "Campaign created successfully",
    "data": {
      "id": 1,
      "name": "Product Demo Campaign",
      "channel": "call",
      "status": "draft",
      "assistant_id": 42,
      "timezone": "Europe/Berlin",
      "max_calls_in_parallel": 3,
      "messages_per_minute": null,
      "schedule_windows": [
        { "start": "09:00", "end": "17:00" }
      ],
      "scheduled_start_at": null,
      "allowed_hours_start_time": "09:00",
      "allowed_hours_end_time": "17:00",
      "allowed_days": [
        "monday",
        "tuesday",
        "wednesday",
        "thursday",
        "friday"
      ],
      "max_retries": 3,
      "retry_interval": 60,
      "retry_on_voicemail": false,
      "retry_on_goal_incomplete": false,
      "goal_completion_variable": null,
      "mark_complete_when_no_leads": true,
      "phone_number_ids": [101],
      "whatsapp_sender_id": null,
      "whatsapp_template_id": null,
      "sms_from_phone_number_id": null,
      "sms_body": null,
      "text_variable_mapping": null,
      "fallback_channel": null,
      "fallback_whatsapp_sender_id": null,
      "fallback_whatsapp_template_id": null,
      "fallback_sms_from_phone_number_id": null,
      "fallback_sms_body": null,
      "fallback_variable_mapping": null,
      "created_at": "2026-02-23T10:00:00.000000Z",
      "updated_at": "2026-02-23T10:00:00.000000Z"
    }
  }
  ```

  ```json 422 Unprocessable Entity theme={null} theme={null}
  {
    "message": "The given data was invalid.",
    "errors": {
      "name": [
        "The name field is required."
      ],
      "assistant_id": [
        "The assistant id field is required."
      ]
    }
  }
  ```
</ResponseExample>

<Tip>
  Related pages: [Introduction](/en/api-reference/introduction) and [Authentication Guide](/en/developers/authentication-guide), and [API Integration Examples](/en/developers/api-integration-examples).
</Tip>