---
title: "Crear Campaign programada"
method: POST
path: "/campaigns"
tags: ["Campaigns"]
---

# Crear Campaign programada

`POST /campaigns`

## Request

- Base URL: `https://api.trytoku.com`
- URL: `https://api.trytoku.com/campaigns`
- Auth: API key in header `x-api-key`

Crea una campaña y agenda un envío por cada fecha indicada en `outbound_dates`.

Se usa para programar el contacto masivo de una cobranza. La campaña queda vacía: las deudas (Invoices) a contactar se asocian después con `POST /campaigns/invoices`.

De cada fecha solo se toma el día; la hora de envío la fija Toku según el país de la organización, y las fechas que quedan repetidas tras ese ajuste se descartan. Si una fecha es hoy y su hora de envío ya pasó o queda dentro de `todays_outbound_delay_in_minutes`, el envío se agenda ese margen de minutos más adelante, o al día siguiente si con eso se alcanza la hora de corte del país. Cuando una fecha pedida para hoy termina agendada para otro día, la respuesta trae `is_scheduled_for_tomorrow` en `true`.

La campaña se rechaza si alguna fecha ajustada cae en un feriado del país.

## Headers

- `x-account-key` string: Llave de API de una Account, para operar sobre esa Account en lugar de la principal.

## Request body

- Campaign: Objeto Campaign, representa una **campaña**. Esto es una agrupación específica de deudas y deudores a contactar. Cada vez que se genera un contacto masivo se hace a partir de estas campañas, que nos dicen a qué deudas contactar. Las fechas indicadas serán utilizadas para mandar el mensaje correspondiente en cada una de ellas.
  - `intention` string: Identificador público de la Intention que define el mensaje a enviar. Se entrega `intention` o `sequence`, nunca ambos.
  - `is_weekly` boolean: Cuando es `true` se omite el aviso de carga de pagos; en caso contrario se intenta agendar 25 horas antes de cada envío, si ese momento no pasó aún.
  - `name` string, required: Nombre con el que se identifica la campaña dentro de la aplicación.
  - `outbound_dates` string[]: Fechas en las que se envía el contacto masivo. Se aceptan hasta 28 fechas, y cada una debe estar en el futuro y dentro de los próximos 56 días.
  - `sequence` string: Identificador público de la Sequence que define los recordatorios a enviar. Se entrega `intention` o `sequence`, nunca ambos.
  - `todays_outbound_delay_in_minutes` integer: Minutos de espera antes de enviar cuando una de las fechas es hoy y su hora de envío ya pasó o queda dentro de este margen. Si al sumarlos se alcanza la hora de corte del país, el envío se agenda para el día siguiente.

## Response `201`

La campaña fue creada y sus envíos quedaron agendados.

- ScheduledCampaignCreatedMessage: Resultado de crear una campaña programada, con el identificador de la campaña recién creada.
  - `id_campaign` string, required: Identificador público de la campaña creada. Se necesita para asociarle deudas o Customers, y para editarla o archivarla más adelante.
  - `is_scheduled_for_tomorrow` boolean, required: `true` cuando alguna de las fechas pedidas era hoy y, tras aplicar la hora de envío y la hora de corte del país, ninguna quedó agendada para hoy.
  - `message` string, required: Descripción legible del resultado de la operación.

## Other responses

- `400`: Alguna de las fechas de envío, ya ajustada por Toku, cae en un feriado del país de la organización. El cuerpo es un texto con las fechas rechazadas.
- `401`: Faltan las credenciales o son inválidas.
- `403`: No tienes acceso a este recurso.
- `404`: La Intention o la Sequence referenciada no existe en la organización autenticada.
- `422`: La Sequence de la campaña envía por WhatsApp y la organización no está habilitada para hacerlo: le falta configuración de mensajería, o le faltan campos en ella. El detalle indica cuáles.
- `429`: Se superó el límite de peticiones permitidas.

## Changes

- **2026-11-03** `a6ef070075b1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/trytoku/apis/toku-api/changes/campaigns/post.md)

---

[API](https://skmtc.dev/trytoku/apis/toku-api.md) - [All operations](https://skmtc.dev/trytoku/apis/toku-api/llms.txt) - [OpenAPI document](https://skmtc.dev/trytoku/apis/toku-api/revisions/a6ef070075b1?raw)