Automações

Fluxos disparados por eventos, com execuções (runs) canceláveis (`publiq.automations`).

O recurso automations modela um fluxo como um grafo de steps: um evento (triggerEvent) dispara a automação, que então avança por steps de espera, condição e ações (enviar e-mail, atualizar contato, webhook, etc.) até um exit. Cada disparo gera uma run rastreável e cancelável.

Iniciar uma automação

Automações são por contato e disparadas por evento — você não "roda" uma automação diretamente. Para iniciá-la para alguém, emita o triggerEvent da automação para aquele contato (por email ou contactId) com events.emit. O payload do evento vira as variáveis usadas nos e-mails do fluxo. Lembre: a automação precisa estar ativada (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' },
});

Contato vs. segmento/audiência: para iniciar a automação para vários contatos de uma vez, use events.emitBatch (lote de até 500 eventos) — ex.: paginando contacts.list(audienceId). Para um envio único a uma lista inteira, use um broadcast (broadcasts.create com audienceId/segmentId) — é o recurso feito para isso. Regra prática: automação = por contato, orientada a evento; broadcast = disparo único para uma lista.

Referência de métodos

`automations.create`

automations.create(params) → Promise<Automation>

Cria uma automação a partir de um grafo de steps. O primeiro step do array deve ser o trigger; os demais se conectam por next (linear) ou onTrue/onFalse (a partir de uma condition). A automação nasce desativada — use automations.enable.

Parâmetros

Parâmetro	Tipo	Descrição
`name`Obrigatório	`string`	Nome da automação.
`triggerEvent`Obrigatório	`string`	Nome do evento que dispara o fluxo (ex.: `user.signed_up`). Você o emite com `events.emit`.
`fromEmail`Opcional	`string`	Remetente usado pelos steps `send_email` do fluxo.
`steps`Obrigatório	`Step[]`	O grafo. Cada step: `ref` (chave local, obrigatória), `type` (obrigatório — um dos 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 do step, ex.: `templateId`, `durationMs`, `rule`), `next` (opcional — edge linear para outro `ref`), `onTrue`/`onFalse` (opcional — branches de uma `condition`), `position` (opcional).

Retorna: A automação criada, desativada (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

A automação só reage depois de disparado o evento triggerEvent (via `events.emit` — veja Eventos) e só enquanto estiver ativada. Recém-criada, ela nasce desativada.

`automations.get`

automations.get(id) → Promise<Automation>

Busca uma automação pelo id, incluindo o grafo de steps completo.

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID da automação.

Retorna: A automação com o grafo de steps. 404 se não existir na organização.

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

`automations.list`

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

Lista as automações da organização, com paginação por cursor.

Parâmetros

Parâmetro	Tipo	Descrição
`limit`Opcional	`number`	Itens por página (padrão 20, máx. 100).
`after`Opcional	`string`	Cursor: `id` do último item da página anterior.

Retorna: Envelope de lista { object: "list", data: Automation[] }.

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

`automations.enable`

automations.enable(id) → Promise<Automation>

Ativa a automação — a partir daí ela passa a reagir ao seu triggerEvent.

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID da automação a ativar.

Retorna: A automação com enabled: true.

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

Uma automação recém-criada precisa ser ativada para rodar — automations.create a deixa desativada por padrão.

`automations.disable`

automations.disable(id) → Promise<Automation>

Pausa a automação — ela para de reagir a novos disparos do triggerEvent. Runs já em andamento não são afetadas.

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID da automação a pausar.

Retorna: A automação com enabled: false.

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

`automations.runs`

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

Lista as execuções (runs) de uma automação, do mais recente ao mais antigo, com paginação por cursor. Cada run tem um state: running, waiting, completed, failed ou canceled.

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID da automação.
`limit`Opcional	`number`	Itens por página (padrão 20, máx. 100).
`after`Opcional	`string`	Cursor: `id` do último item da página anterior.

Retorna: Envelope 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 uma run em andamento (running/waiting) — por exemplo, para interromper um contato no meio de um fluxo de nutrição.

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID da automação (path).
`runId`Obrigatório	`string`	ID da run a cancelar (path).

Retorna: A run com state: "canceled".

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

`automations.chat`

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

Builder conversacional por IA: descreva o fluxo desejado em linguagem natural e receba de volta uma resposta e, opcionalmente, um draft — um grafo de automação proposto que você pode revisar e passar para automations.create. Requer o recurso de plano ai_builder.

Parâmetros

Parâmetro	Tipo	Descrição
`threadId`Obrigatório	`string`	ID da conversa — mantém o contexto entre mensagens sucessivas.
`message`Obrigatório	`string`	O pedido do usuário ou um refinamento sobre a resposta anterior.

Retorna: { reply, draft? } — reply é a resposta em texto; draft, quando presente, é um grafo de automação pronto 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);
}

Disponível apenas em planos com a feature ai_builder. Sem ela, a chamada retorna 403 feature_not_available.

Os exemplos mostram Node, Python e PHP. No Python os métodos são snake_case (ex.: cancel_run, from_spec) e recebem um dict; no PHP são camelCase e recebem um array associativo. As chaves do corpo são sempre camelCase (templateKey, firstName, scheduledAt) — o retorno da API vem em snake_case.