Publiq

Segmentos

Subconjuntos de uma audiência definidos por regras (`publiq.segments`).

O recurso segments representa um subconjunto de uma audiência, definido por uma árvore de regras (rules) avaliada contra os contatos. Crie, liste, atualize e remova segmentos para depois usá-los como alvo de um broadcast.

Referência de métodos

segments.create

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

Cria um segmento dentro de uma audiência, definido por uma árvore de regras (rules) que determina quais contatos pertencem a ele.

Parâmetros
ParâmetroTipoDescrição
audienceIdObrigatóriostringID da audiência onde o segmento será criado (parte da URL).
nameObrigatóriostringNome do segmento (1 a 200 caracteres).
rulesObrigatórioobjectA árvore de regras que define o segmento. Veja a estrutura abaixo.

Retorna: O segmento criado — { 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 é uma árvore: uma folha é { field, cmp, value } e um nó é { op, children }, onde op é and ou or e children é uma lista de folhas e/ou nós — permitindo combinar condições em qualquer profundidade. Comparadores (cmp) disponíveis: eq, neq, gt, gte, lt, lte, in, contains, exists. O field é validado contra uma lista de campos permitidos — subscribed é sempre válido; campos de atributo arbitrários podem ser restritos.
Um segmento é o subconjunto de audiência que você mira em um Broadcasts — em vez de enviar para toda a Audiências, envie apenas para quem casa com as regras.

segments.list

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

Lista os segmentos de uma audiência, com paginação por cursor.

Parâmetros
ParâmetroTipoDescrição
audienceIdObrigatóriostringID da audiência cujos segmentos serão listados (parte da URL).
limitOpcionalnumberItens por página (padrão 20, máx. 100).
afterOpcionalstringCursor: id do último item da página anterior.

Retorna: Envelope de lista { object: "list", data: Segment[] }. Use o id do último item como after na próxima chamada.

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 });
A listagem é paginada por cursor: itere passando o id do último item em after até data vir vazio. Veja Erros & paginação.

segments.update

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

Atualiza o nome e/ou a árvore de regras de um segmento existente.

Parâmetros
ParâmetroTipoDescrição
audienceIdObrigatóriostringID da audiência dona do segmento (parte da URL).
segmentIdObrigatóriostringID do segmento a atualizar (parte da URL).
nameOpcionalstringNovo nome do segmento.
rulesOpcionalobjectNova árvore de regras — substitui a anterior por completo (não faz merge).

Retorna: O segmento atualizado.

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>

Remove um segmento permanentemente. Não afeta os contatos da audiência, apenas a definição do segmento.

Parâmetros
ParâmetroTipoDescrição
audienceIdObrigatóriostringID da audiência dona do segmento (parte da URL).
segmentIdObrigatóriostringID do segmento a remover (parte da URL).

Retorna: Nenhum conteúdo (204).

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

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.

Segmentos — Publiq Docs