Segmentos

Subconjuntos de una audiencia definidos por reglas (`publiq.segments`).

El recurso segments representa un subconjunto de una audiencia, definido por un árbol de reglas (rules) evaluado contra los contactos. Crea, lista, actualiza y elimina segmentos para luego usarlos como objetivo de un broadcast.

Referencia de métodos

`segments.create`

segments.create(audienceId, params) → Promise<Segment>

Crea un segmento dentro de una audiencia, definido por un árbol de reglas (rules) que determina qué contactos pertenecen a él.

Parámetros

Parámetro	Tipo	Descripción
`audienceId`Obligatorio	`string`	ID de la audiencia donde se creará el segmento (parte de la URL).
`name`Obligatorio	`string`	Nombre del segmento (1 a 200 caracteres).
`rules`Obligatorio	`object`	El árbol de reglas que define el segmento. Ver la estructura abajo.

Devuelve: El segmento creado — { object: "segment", id, name, rules, ... }.

const segment = await publiq.segments.create('aud_123', {
name: 'Active subscribers',
rules: {
  op: 'and',
  children: [{ field: 'subscribed', cmp: 'eq', value: true }],
},
});
console.log(segment.id, segment.name); // "seg_...", "Active subscribers"

rules es un árbol: una hoja es { field, cmp, value } y un nodo es { op, children }, donde op es and u or y children es una lista de hojas y/o nodos — permitiendo combinar condiciones en cualquier profundidad. Comparadores (cmp) disponibles: eq, neq, gt, gte, lt, lte, in, contains, exists. El field se valida contra una lista de campos permitidos — subscribed siempre es válido; campos de atributo arbitrarios pueden estar restringidos.

Un segmento es el subconjunto de audiencia al que apuntas con un Broadcasts — en vez de enviar a toda la Audiencias, envía solo a quienes cumplan las reglas.

`segments.list`

segments.list(audienceId, { limit?, after? }) → Promise<SegmentList>

Lista los segmentos de una audiencia, paginado por cursor.

Parámetros

Parámetro	Tipo	Descripción
`audienceId`Obligatorio	`string`	ID de la audiencia cuyos segmentos se listarán (parte de la URL).
`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: Segment[] }. Usa el id del último ítem como after en la próxima llamada.

const { data } = await publiq.segments.list('aud_123', { limit: 50 });
// next page:
const next = await publiq.segments.list('aud_123', { after: data[data.length - 1].id });

El listado se pagina por cursor: itera pasando el id del último ítem en after hasta que data venga vacío. Ver Errores & paginación.

`segments.update`

segments.update(audienceId, segmentId, params) → Promise<Segment>

Actualiza el nombre y/o el árbol de reglas de un segmento existente.

Parámetros

Parámetro	Tipo	Descripción
`audienceId`Obligatorio	`string`	ID de la audiencia dueña del segmento (parte de la URL).
`segmentId`Obligatorio	`string`	ID del segmento a actualizar (parte de la URL).
`name`Opcional	`string`	Nuevo nombre del segmento.
`rules`Opcional	`object`	Nuevo árbol de reglas — reemplaza por completo al anterior (sin merge).

Devuelve: El segmento actualizado.

const segment = await publiq.segments.update('aud_123', 'seg_123', {
rules: {
  op: 'or',
  children: [
    { field: 'plan', cmp: 'eq', value: 'pro' },
    { field: 'plan', cmp: 'eq', value: 'enterprise' },
  ],
},
});
console.log(segment.rules);

`segments.delete`

segments.delete(audienceId, segmentId) → Promise<void>

Elimina permanentemente un segmento. No afecta los contactos de la audiencia, solo la definición del segmento.

Parámetros

Parámetro	Tipo	Descripción
`audienceId`Obligatorio	`string`	ID de la audiencia dueña del segmento (parte de la URL).
`segmentId`Obligatorio	`string`	ID del segmento a eliminar (parte de la URL).

Devuelve: Sin contenido (204).

await publiq.segments.delete('aud_123', 'seg_123');

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.