Eventos

Emite eventos que activan automatizaciones; el payload se vuelve las variables (`publiq.events`).

El recurso events es el puente entre tu sistema y las Automatizaciones: emites un evento de aplicación (ej.: user.signed_up) y Publiq inicia (o retoma) cualquier automatización enabled cuyo triggerEvent coincida con ese nombre, para el contacto-objetivo del evento.

Referencia de métodos

`events.emit`

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

Registra un evento de aplicación para el contacto-objetivo (por contactId o email). Devuelve 202 de inmediato: inicia automatizaciones enabled cuyo triggerEvent coincide con event, y retoma runs waiting que esperaban ese evento.

Parámetros

Parámetro	Tipo	Descripción
`event`Obligatorio	`string`	Nombre del evento (máx. 200 caracteres), ej.: `user.signed_up`. Es contra este nombre que se compara el `triggerEvent` de las Automatizaciones.
`contactId`Opcional	`string`	ID del contacto-objetivo del evento. Alternativa a `email`.
`email`Opcional	`string`	Correo del contacto-objetivo (máx. 320 caracteres) — resuelve el contacto existente por correo. Alternativa a `contactId`.
`payload`Opcional	`object`	Datos libres del evento. Quedan disponibles para los steps de la automatización y se combinan con las Variables de plantilla al enviar.

Devuelve: El resultado del disparo — { object: "event_dispatch", accepted: true, started, resumed }, donde started es cuántas runs se iniciaron y resumed cuántas runs se retomaron.

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

Provee contactId o email — sin un sujeto para el evento, no se resuelve ningún contacto y no se inicia ninguna automatización (started y resumed vuelven 0, incluso con 202).

El payload (combinado con los attributes del contacto) llena las variables de plantilla en el step de envío: payload: { first_name: "Ana", plan: "Pro" } se vuelve {{ first_name }} y {{ plan }} en el correo. Ver Cómo funciona y Variables.

Para que una automatización realmente se ejecute, primero crea y activa una Automatización con el triggerEvent correspondiente — solo entonces events.emit de ese evento la dispara. En el ejemplo anterior, una automatización con triggerEvent: "user.signed_up" reaccionaría al disparo, iniciando una run para ana@example.com con el payload disponible para sus steps.

`events.emitBatch`

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

Emite un lote de eventos (hasta 500) en una sola llamada — la forma eficiente de iniciar una automatización para muchos contactos a la vez, en lugar de un emit por contacto. Cada ítem es un evento independiente, con el mismo shape que emit.

Parámetros

Parámetro	Tipo	Descripción
`events`Obligatorio	`DispatchEvent[]`	Array de eventos (mín. 1, máx. 500). Cada ítem acepta los mismos campos que `emit`: `event` (obligatorio), `contactId`/`email` y `payload`.

Devuelve: { object: "event_batch", accepted, failed, results }. Cada ítem de results tiene { index, status: "accepted" | "failed", started?, resumed?, error? } — el index coincide con la posición 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: un ítem inválido no derriba el lote — vuelve con status: "failed" y un error, y el resto continúa. Inspecciona siempre results para tratar las fallas. Las mismas garantías de emit aplican por ítem (dedup de run activa y límite de runs por ciclo).

Para enrolar una audiencia entera, pagina con `contacts.list(audienceId)` y envía los correos en lotes de hasta 500. Para un envío único a una lista (no una automatización), prefiere un broadcast.

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.