Eventos

Dispare eventos que acionam automações; o payload vira as variáveis (`publiq.events`).

O recurso events é a ponte entre o seu sistema e as Automações: você emite um evento de aplicação (ex.: user.signed_up) e o Publiq inicia (ou retoma) qualquer automação enabled cujo triggerEvent bata com aquele nome, para o contato-alvo do evento.

Referência de métodos

`events.emit`

events.emit(params) → Promise<{ accepted: true, started, resumed }>

Registra um evento de aplicação para o contato-alvo (por contactId ou email). Retorna 202 imediatamente: dispara início de automações enabled com triggerEvent igual a event, e retoma runs waiting que aguardavam esse evento.

Parâmetros

Parâmetro	Tipo	Descrição
`event`Obrigatório	`string`	Nome do evento (máx. 200 caracteres), ex.: `user.signed_up`. É contra esse nome que o `triggerEvent` das Automações é comparado.
`contactId`Opcional	`string`	ID do contato-alvo do evento. Alternativa a `email`.
`email`Opcional	`string`	E-mail do contato-alvo (máx. 320 caracteres) — resolve o contato existente por e-mail. Alternativa a `contactId`.
`payload`Opcional	`object`	Dados livres do evento. Ficam disponíveis para os steps da automação e são mesclados às Variáveis de template no envio.

Retorna: O resultado do disparo — { object: "event_dispatch", accepted: true, started, resumed }, onde started é o número de runs iniciadas e resumed o número de runs retomadas.

const result = await publiq.events.emit({
event: 'user.signed_up',
email: 'ana@example.com',
payload: { first_name: 'Ana', plan: 'Pro' },
});
console.log(result.started, result.resumed); // e.g. 1, 0

Forneça contactId ou email — sem um sujeito para o evento, nenhum contato é resolvido e nenhuma automação é iniciada (started e resumed vêm 0, mesmo com 202).

O payload (mesclado aos attributes do contato) preenche as variáveis do template no step de envio: payload: { first_name: "Ana", plan: "Pro" } vira {{ first_name }} e {{ plan }} no e-mail. Veja Como funciona e Variáveis.

Para uma automação realmente rodar, primeiro crie e ative uma Automação com o triggerEvent correspondente — só então events.emit daquele evento a dispara. No exemplo acima, uma automação com triggerEvent: "user.signed_up" reagiria ao disparo, iniciando uma run para ana@example.com com payload disponível para seus steps.

`events.emitBatch`

events.emitBatch(events) → Promise<{ object: "event_batch", accepted, failed, results }>

Emite um lote de eventos (até 500) numa única chamada — a forma eficiente de iniciar uma automação para muitos contatos de uma vez, em vez de um emit por contato. Cada item é um evento independente, com o mesmo shape de emit.

Parâmetros

Parâmetro	Tipo	Descrição
`events`Obrigatório	`DispatchEvent[]`	Array de eventos (mín. 1, máx. 500). Cada item aceita os mesmos campos de `emit`: `event` (obrigatório), `contactId`/`email` e `payload`.

Retorna: { object: "event_batch", accepted, failed, results }. Cada item de results tem { index, status: "accepted" | "failed", started?, resumed?, error? } — o index casa com a posição enviada.

const batch = await publiq.events.emitBatch([
{ event: 'user.signed_up', email: 'ana@example.com', payload: { first_name: 'Ana' } },
{ event: 'user.signed_up', email: 'bob@example.com', payload: { first_name: 'Bob' } },
]);
console.log(batch.accepted, batch.failed); // e.g. 2, 0
for (const r of batch.results) {
if (r.status === 'failed') console.warn(r.index, r.error);
}

Skip-and-continue: um item inválido não derruba o lote — ele volta com status: "failed" e um error, e os demais seguem. Sempre inspecione results para tratar as falhas. As mesmas garantias do emit valem por item (dedup de run ativo e limite de runs por ciclo).

Para enrolar uma audiência inteira, pagine com `contacts.list(audienceId)` e envie os e-mails em lotes de até 500. Para um envio único a uma lista (não uma automação), prefira um broadcast.

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.