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

# Actualizar Campaña

> Actualización parcial de una Campaña. Los campos inmutables (`agent_id`, `integration_id`, `integration_type`, `cycles.enabled`, `cycles.mode`) no se pueden modificar y devuelven `IMMUTABLE_FIELD`. Las campañas finalizadas son de solo lectura.

<Info>
  **Límite de Tasa:** 12 solicitudes por segundo
</Info>

## Campos Inmutables

Los siguientes campos no pueden modificarse después de la creación. Incluirlos en un PATCH devuelve `400 IMMUTABLE_FIELD` e identifica el campo en conflicto en la llave `field`:

* `agent_id`
* `integration_id`
* `integration_type`
* `cycles.enabled`
* `cycles.mode`

Las campañas finalizadas son de solo lectura y devuelven `409 CAMPAIGN_FINISHED` ante cualquier PATCH.

## Actualizaciones de Ciclo

Los campos de ciclo solo pueden actualizarse en campañas con ciclos habilitados (`400 CYCLES_NOT_ENABLED` en otro caso). `schedule`, `schedule_start_date` y `schedule_end_date` solo son válidos cuando `cycles.mode` es `scheduled` (`400 SCHEDULED_MODE_ONLY` en otro caso).

## Ejemplos

### Renombrar campaña y reducir reintentos

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.altur.io/api/v1.0/campaigns/1234" \
    -H "Authorization: api-key YOUR_API_SECRET_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Reactivación Q2 - ola 2",
      "retries": 2
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.patch(
      "https://api.altur.io/api/v1.0/campaigns/1234",
      headers={"Authorization": "api-key YOUR_API_SECRET_KEY"},
      json={"name": "Reactivación Q2 - ola 2", "retries": 2},
  )
  response.raise_for_status()
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://api.altur.io/api/v1.0/campaigns/1234", {
    method: "PATCH",
    headers: {
      Authorization: "api-key YOUR_API_SECRET_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "Reactivación Q2 - ola 2", retries: 2 }),
  });
  ```
</CodeGroup>

### Cambiar el cooldown del ciclo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.altur.io/api/v1.0/campaigns/1234" \
    -H "Authorization: api-key YOUR_API_SECRET_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "cycles": { "cooldown_minutes": 60 }
    }'
  ```

  ```python Python theme={null}
  requests.patch(
      "https://api.altur.io/api/v1.0/campaigns/1234",
      headers={"Authorization": "api-key YOUR_API_SECRET_KEY"},
      json={"cycles": {"cooldown_minutes": 60}},
  ).raise_for_status()
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://api.altur.io/api/v1.0/campaigns/1234", {
    method: "PATCH",
    headers: {
      Authorization: "api-key YOUR_API_SECRET_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ cycles: { cooldown_minutes: 60 } }),
  });
  ```
</CodeGroup>


## OpenAPI

````yaml PATCH /campaigns/{id}
openapi: 3.0.1
info:
  title: Altur API
  description: >-
    An API aimed to allow third-party developers to interact with the Altur
    platform through a RESTful interface.
  license:
    name: MIT
  version: '1.0'
servers:
  - url: https://api.altur.io/api/v1.0
security:
  - apiKeyAuth: []
paths:
  /campaigns/{id}:
    patch:
      description: >-
        Partial update of a Campaign. Immutable fields (`agent_id`,
        `integration_id`, `integration_type`, `cycles.enabled`, `cycles.mode`)
        cannot be modified after creation and return `IMMUTABLE_FIELD` if
        included. Finished campaigns are read-only.
      parameters:
        - name: id
          in: path
          description: The identifier of the Campaign
          schema:
            type: integer
          required: true
      requestBody:
        description: Partial Campaign update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignUpdate'
      responses:
        '200':
          description: Campaign updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDetailResponse'
        '400':
          description: >-
            Invalid input, immutable field, cycles not enabled, or
            scheduled-mode-only field misuse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Campaign not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignApiError'
        '409':
          description: Campaign is finished
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignApiError'
components:
  schemas:
    CampaignUpdate:
      type: object
      description: >-
        Partial update. Any field may be omitted. Immutable fields (`agent_id`,
        `integration_id`, `integration_type`, `cycles.enabled`, `cycles.mode`)
        cannot be included.
      properties:
        name:
          type: string
          maxLength: 255
        description:
          type: string
        timezone:
          type: string
        retries:
          type: integer
          minimum: 0
          maximum: 5
        message_limit:
          type: integer
          minimum: 1
          maximum: 10000
        scheduling:
          $ref: '#/components/schemas/CampaignSchedule'
        first_message:
          type: string
        template:
          type: string
        template_alt:
          type: string
        cycles:
          $ref: '#/components/schemas/CampaignCyclesConfig'
    CampaignDetailResponse:
      type: object
      properties:
        success:
          type: boolean
        campaign:
          $ref: '#/components/schemas/CampaignDetail'
    CampaignApiError:
      type: object
      description: Standard error envelope returned by the v1.0 campaigns API.
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Stable, UPPER_SNAKE_CASE error key.
          enum:
            - FORBIDDEN
            - NOT_FOUND
            - RATE_LIMITED
            - SERVER_ERROR
            - INVALID_REQUEST
            - INVALID_STATUS
            - IMMUTABLE_FIELD
            - UNKNOWN_ACTION
            - AGENT_NOT_FOUND
            - INTEGRATION_NOT_FOUND
            - INVALID_INTEGRATION_TYPE
            - INVALID_FILTER_TAG
            - INVALID_PHONE_NUMBER
            - MISSING_CONTACT
            - CONTACT_NOT_FOUND
            - CONTACT_NOT_DELETABLE
            - CAMPAIGN_FINISHED
            - CYCLES_NOT_ENABLED
            - SCHEDULED_MODE_ONLY
            - INVALID_STATUS_TRANSITION
            - BILLING_LIMIT_REACHED
        message:
          type: string
        field:
          type: string
          description: >-
            Set when `error` is `IMMUTABLE_FIELD`; identifies the offending
            field path.
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
    CampaignSchedule:
      type: object
      properties:
        mon:
          $ref: '#/components/schemas/CampaignScheduleDay'
          description: Monday
          type: object
        tue:
          $ref: '#/components/schemas/CampaignScheduleDay'
          description: Tuesday
          type: object
        wed:
          $ref: '#/components/schemas/CampaignScheduleDay'
          description: Wednesday
          type: object
        thu:
          $ref: '#/components/schemas/CampaignScheduleDay'
          description: Thursday
          type: object
        fri:
          $ref: '#/components/schemas/CampaignScheduleDay'
          description: Friday
          type: object
        sat:
          $ref: '#/components/schemas/CampaignScheduleDay'
          description: Saturday
          type: object
        sun:
          $ref: '#/components/schemas/CampaignScheduleDay'
          description: Sunday
          type: object
    CampaignCyclesConfig:
      type: object
      description: Cycles configuration block. Phone-call campaigns only.
      properties:
        enabled:
          type: boolean
          description: Whether cycles are enabled. Immutable after creation.
        mode:
          type: string
          enum:
            - cooldown
            - scheduled
          description: Cycle mode. Immutable after creation.
        max_iterations:
          type: integer
          minimum: 2
          maximum: 12
        cooldown_minutes:
          type: integer
          minimum: 0
          maximum: 1440
        filter_statuses:
          type: array
          items:
            type: string
          description: Contact statuses excluded from the next iteration.
        filter_tags:
          type: array
          items:
            type: string
          description: >-
            Thread tag ids whose contacts are excluded from the next iteration.
            Input-only — not returned on the detail response.
        schedule:
          $ref: '#/components/schemas/CampaignSchedule'
          description: Per-day schedule. Only used when `mode` = `scheduled`.
        schedule_start_date:
          type: string
          format: date
          nullable: true
          description: Only used when `mode` = `scheduled`.
        schedule_end_date:
          type: string
          format: date
          nullable: true
          description: Only used when `mode` = `scheduled`.
    CampaignDetail:
      type: object
      description: >-
        Single Campaign detail with nested agent, integration and cycles config.
        The `analytics` field is included only when a snapshot is available for
        the campaign.
      properties:
        id:
          description: Unique identifier for the Campaign
          type: integer
        name:
          description: Name of the Campaign
          type: string
        status:
          description: Current status of the Campaign
          type: string
          enum:
            - pending
            - ready
            - active
            - inactive
            - cooldown
            - finished
        integration:
          description: Nested {id, type} of the integration the Campaign was created on
          type: object
          nullable: true
          properties:
            id:
              type: string
            type:
              type: string
              enum:
                - phone_call
                - whatsapp
        agent:
          type: object
          properties:
            id:
              type: string
              format: uuid4
            name:
              type: string
        created_at:
          type: string
          format: date-time
        scheduling:
          $ref: '#/components/schemas/CampaignSchedule'
        cycles:
          $ref: '#/components/schemas/CampaignCyclesConfig'
        analytics:
          description: >-
            Analytics snapshot for the Campaign. Shape depends on
            `integration.type` — see `CampaignAnalyticsPhoneCall` and
            `CampaignAnalyticsWhatsApp`.
          type: object
    CampaignScheduleDay:
      type: object
      properties:
        startTime:
          description: Start time of the Campaign on Monday
          type: string
        stopTime:
          description: End time of the Campaign on Monday
          type: string
        active:
          description: Boolean describing if the Campaign is active on Monday
          type: boolean
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Add `api-key YOUR_API_SECRET_KEY` as the value of the `Authorization`
        header.

````