Automatizaciones

Flujos activados por eventos, con ejecuciones (runs) cancelables (`publiq.automations`).

El recurso automations modela un flujo como un grafo de steps: un evento (triggerEvent) dispara la automatización, que avanza por steps de espera, condición y acciones (enviar correo, actualizar contacto, webhook, etc.) hasta un exit. Cada disparo genera una run rastreable y cancelable.

Iniciar una automatización

Las automatizaciones son por contacto y activadas por evento — no "ejecutas" una automatización directamente. Para iniciarla para alguien, emite el triggerEvent de la automatización para ese contacto (por email o contactId) con events.emit. El payload del evento se vuelve las variables usadas en los correos del flujo. Recuerda: la automatización debe estar activada (enable).

// Start the 'user.signed_up' automation for ONE contact
await publiq.events.emit({
  event: 'user.signed_up',           // must match the automation's triggerEvent
  email: 'ana@example.com',          // or contactId: 'ct_123'
  payload: { first_name: 'Ana', plan: 'Pro' },
});

Contacto vs. segmento/audiencia: para iniciar la automatización para varios contactos a la vez, usa events.emitBatch (lote de hasta 500 eventos) — ej.: paginando contacts.list(audienceId). Para un envío único a una lista entera, usa un broadcast (broadcasts.create con audienceId/segmentId) — es el recurso hecho para eso. Regla práctica: automatización = por contacto, orientada a evento; broadcast = disparo único a una lista.

Referencia de métodos

`automations.create`

automations.create(params) → Promise<Automation>

Crea una automatización a partir de un grafo de steps. El primer elemento del array debe ser el step trigger; el resto se conecta por next (lineal) u onTrue/onFalse (desde una condition). La automatización nace desactivada — usa automations.enable.

Parámetros

Parámetro	Tipo	Descripción
`name`Obligatorio	`string`	Nombre de la automatización.
`triggerEvent`Obligatorio	`string`	Nombre del evento que dispara el flujo (ej.: `user.signed_up`). Lo emites con `events.emit`.
`fromEmail`Opcional	`string`	Remitente usado por los steps `send_email` del flujo.
`steps`Obligatorio	`Step[]`	El grafo. Cada step: `ref` (clave local, obligatoria), `type` (obligatorio — uno de 13: `trigger`, `send_email`, `delay`, `wait_for_event`, `condition`, `contact_update`, `contact_delete`, `add_to_segment`, `remove_from_segment`, `split`, `wait_until`, `webhook`, `exit`), `config` (opcional — ajustes del step, ej.: `templateId`, `durationMs`, `rule`), `next` (opcional — edge lineal a otro `ref`), `onTrue`/`onFalse` (opcional — ramas de una `condition`), `position` (opcional).

Devuelve: La automatización creada, desactivada (enabled: false).

const automation = await publiq.automations.create({
name: 'Welcome flow',
triggerEvent: 'user.signed_up',
fromEmail: 'you@yourdomain.com',
steps: [
  { ref: 'trigger', type: 'trigger', next: 'wait' },
  { ref: 'wait', type: 'delay', config: { durationMs: 3600000 }, next: 'send' },
  { ref: 'send', type: 'send_email', config: { templateKey: 'welcome-email' } },
],
});
console.log(automation.id, automation.enabled); // "aut_...", false

La automatización solo reacciona cuando se dispara su triggerEvent (vía `events.emit` — ver Eventos) y solo mientras esté activada. Recién creada, nace desactivada.

`automations.get`

automations.get(id) → Promise<Automation>

Obtiene una automatización por id, incluyendo su grafo de steps completo.

Parámetros

Parámetro	Tipo	Descripción
`id`Obligatorio	`string`	ID de la automatización.

Devuelve: La automatización con su grafo de steps. 404 si no existe en la organización.

const automation = await publiq.automations.get('aut_123');
console.log(automation.steps.length);

`automations.list`

automations.list({ limit?, after? }) → Promise<AutomationList>

Lista las automatizaciones de la organización, paginado por cursor.

Parámetros

Parámetro	Tipo	Descripción
`limit`Opcional	`number`	Ítems por página (por defecto 20, máx. 100).
`after`Opcional	`string`	Cursor: `id` del último ítem de la página anterior.

Devuelve: Envoltura de lista { object: "list", data: Automation[] }.

const { data } = await publiq.automations.list({ limit: 50 });

`automations.enable`

automations.enable(id) → Promise<Automation>

Activa la automatización — a partir de ahí reacciona a su triggerEvent.

Parámetros

Parámetro	Tipo	Descripción
`id`Obligatorio	`string`	ID de la automatización a activar.

Devuelve: La automatización con enabled: true.

await publiq.automations.enable('aut_123');

Una automatización recién creada debe activarse para funcionar — automations.create la deja desactivada por defecto.

`automations.disable`

automations.disable(id) → Promise<Automation>

Pausa la automatización — deja de reaccionar a nuevos disparos del triggerEvent. Las runs ya en curso no se ven afectadas.

Parámetros

Parámetro	Tipo	Descripción
`id`Obligatorio	`string`	ID de la automatización a pausar.

Devuelve: La automatización con enabled: false.

await publiq.automations.disable('aut_123');

`automations.runs`

automations.runs(id, { limit?, after? }) → Promise<AutomationRunList>

Lista las ejecuciones (runs) de una automatización, de la más reciente a la más antigua, paginado por cursor. Cada run tiene un state: running, waiting, completed, failed o canceled.

Parámetros

Parámetro	Tipo	Descripción
`id`Obligatorio	`string`	ID de la automatización.
`limit`Opcional	`number`	Ítems por página (por defecto 20, máx. 100).
`after`Opcional	`string`	Cursor: `id` del último ítem de la página anterior.

Devuelve: Envoltura de lista { object: "list", data: AutomationRun[] }.

const { data } = await publiq.automations.runs('aut_123', { limit: 50 });

`automations.cancelRun`

automations.cancelRun(id, runId) → Promise<AutomationRun>

Cancela una run en curso (running/waiting) — por ejemplo, para sacar a un contacto de un flujo de nutrición a medio camino.

Parámetros

Parámetro	Tipo	Descripción
`id`Obligatorio	`string`	ID de la automatización (path).
`runId`Obligatorio	`string`	ID de la run a cancelar (path).

Devuelve: La run con state: "canceled".

await publiq.automations.cancelRun('aut_123', 'run_456');

`automations.chat`

automations.chat(params) → Promise<{ reply, draft? }>

Builder conversacional por IA: describe el flujo deseado en lenguaje natural y recibe una respuesta y, opcionalmente, un draft — un grafo de automatización propuesto que puedes revisar y pasar a automations.create. Requiere la función de plan ai_builder.

Parámetros

Parámetro	Tipo	Descripción
`threadId`Obligatorio	`string`	ID de la conversación — mantiene el contexto entre mensajes sucesivos.
`message`Obligatorio	`string`	El pedido del usuario o un refinamiento sobre la respuesta anterior.

Devuelve: { reply, draft? } — reply es la respuesta en texto; draft, cuando está presente, es un grafo de automatización listo para automations.create.

const { reply, draft } = await publiq.automations.chat({
threadId: 'thr_123',
message: 'Send a welcome email 1 hour after signup',
});
if (draft) {
await publiq.automations.create(draft);
}

Disponible solo en planes con la función ai_builder. Sin ella, la llamada devuelve 403 feature_not_available.

Los ejemplos muestran Node, Python y PHP. En Python los métodos son snake_case (ej.: cancel_run, from_spec) y reciben un dict; en PHP son camelCase y reciben un array asociativo. Las claves del cuerpo siempre son camelCase (templateKey, firstName, scheduledAt) — las respuestas de la API vienen en snake_case.