Filtros de leads e conversas

A linguagem de filtro estruturado usada por leads, CRM, negociações, visões salvas, públicos de campanha, anúncios e Elo, e como enviá-la.

Leads, o quadro do CRM, as negociações, as visões salvas, os públicos de campanha, os públicos de anúncios e o Elo usam a mesma linguagem para escolher registros: o filtro estruturado. Ele é um objeto JSON com grupos de condições, validado pelas mesmas regras em todos esses recursos.

Os campos que cada filtro aceita, com os operadores, o formato do valor e os limites de cada um, estão em Campos do filtro, página gerada a partir do registro que a API usa para validar.

Estrutura

Um filtro tem uma lista de grupos (groups). Cada grupo tem uma lista de predicados (predicates) e diz como eles se combinam em conjunction:

CampoOndeO que é
groupsfiltroLista de grupos. Os grupos sempre se combinam com E: o registro precisa atender a todos.
conjunctiongrupoand (todos os predicados do grupo) ou or (qualquer um deles). Sem o campo, o grupo vale como or; numa seleção de registros o campo é obrigatório (veja Seleção de leads).
predicatesgrupoLista de condições. Um grupo sem predicados é ignorado.
fieldpredicadoO campo testado, como stage, created_at ou custom.
keypredicadoComplemento do campo: a chave do campo personalizado em custom e o modo da área em area. Os demais campos não usam.
operatorpredicadoA comparação, como in, between ou is_set. Cada campo aceita só alguns operadores.
valuespredicadoOs valores, sempre como texto, mesmo números e datas. Valores vazios são ignorados.

Um filtro sem grupos, ou só com grupos vazios, não filtra nada.

Este filtro, sobre leads, pede quem é de SP, foi criado a partir de 1º de janeiro de 2026 e não saiu do WhatsApp, e tem uma certa etiqueta ou está numa certa etapa:

{
  "groups": [
    {
      "conjunction": "and",
      "predicates": [
        { "field": "state", "operator": "in", "values": ["SP"] },
        { "field": "created_at", "operator": "gte", "values": ["2026-01-01"] },
        { "field": "opted_out", "operator": "is_false" }
      ]
    },
    {
      "conjunction": "or",
      "predicates": [
        { "field": "label", "operator": "in", "values": ["6f1c2a9e-3b4d-4e5f-8a7b-9c0d1e2f3a4b"] },
        { "field": "stage", "operator": "in", "values": ["0b9e8d7c-6a5f-4e3d-2c1b-0a9f8e7d6c5b"] }
      ]
    }
  ]
}

Mais exemplos, cada um para o recurso indicado:

{
  "groups": [
    {
      "conjunction": "and",
      "predicates": [
        { "field": "origin", "operator": "in", "values": ["receptive"] },
        { "field": "unread", "operator": "is_true" },
        { "field": "last_activity_at", "operator": "after", "values": ["2026-10-01T00:00:00-03:00"] }
      ]
    }
  ]
}

Conversas do CRM que começaram pelo contato, com mensagens não lidas e atividade depois de 1º de outubro.

{
  "groups": [
    {
      "conjunction": "and",
      "predicates": [
        { "field": "status", "operator": "eq", "values": ["open"] },
        { "field": "value", "operator": "between", "values": ["100000", "500000"] },
        { "field": "custom", "key": "plano", "operator": "eq", "values": ["ouro"] }
      ]
    }
  ]
}

Negociações abertas entre R$ 1.000,00 e R$ 5.000,00 (o valor é comparado em centavos) com o campo personalizado plano igual a ouro.

{
  "groups": [
    {
      "conjunction": "and",
      "predicates": [
        { "field": "district", "operator": "in", "values": ["sp:sao paulo/jardim paulista"] },
        { "field": "birthday", "operator": "in", "values": ["this_week"] },
        { "field": "phone_any", "operator": "in", "values": ["(11) 98765-4321"] }
      ]
    }
  ]
}

Leads do bairro Jardim Paulista, em São Paulo, que fazem aniversário nesta semana e têm o telefone informado, em qualquer formato.

Onde o filtro vale

Nem todo campo existe em todo recurso. O filtro é aplicado a um de três tipos de registro, e cada um aceita um conjunto de campos (a coluna "Onde vale" de Campos do filtro):

RegistroRecursos
Conversas (CRM)GET /crm/board, GET /crm/entries, POST /crm/bulk e POST /crm/bulk/count, visões salvas com objectType conversation.
NegociaçõesGET /opportunities/board, GET /opportunities/list, visões salvas com objectType opportunity.
LeadsGET /leads, GET /leads/sections/summary, GET /leads/sections/facets, GET /leads/sections/places, as rotas do mapa (GET /leads/map/summary, GET /leads/map/tiles/{z}/{x}/{y}, GET /leads/map/districts, GET /leads/map/viewport, GET /leads/map/point, GET /leads/map/left-out), as ações em massa (POST /leads/actions/preview e POST /leads/actions), os públicos de campanha de WhatsApp, WhatsApp não oficial, e-mail e RCS e SMS, as listas de clientes de anúncios (POST /ads/audiences/customer-list), visões salvas com objectType lead e o contexto da tela de Leads enviado ao Elo.

Um campo que existe na linguagem mas não no tipo de registro recusa o filtro. Nos leads, os campos de endereço zip, geo_precision, geo_status, geo_placement, area e area_approximate exigem a permissão de ler endereços completos, e filtrar por um campo personalizado sensível exige a permissão de ler dados sensíveis.

Como enviar

No parâmetro filter da URL

As rotas de leitura (GET) recebem o filtro no parâmetro filter, de duas formas:

  • o JSON do filtro, codificado para URL;
  • o JSON do filtro em base64, no alfabeto padrão ou no seguro para URL.

O servidor tenta ler o valor como base64 e, se não conseguir, como JSON. As duas chamadas abaixo pedem o mesmo filtro:

curl -G "https://api.vozkoia.com/crm/entries" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "X-Workspace-ID: SEU_WORKSPACE_ID" \
  --data-urlencode 'filter={"groups":[{"conjunction":"and","predicates":[{"field":"stage","operator":"in","values":["0b9e8d7c-6a5f-4e3d-2c1b-0a9f8e7d6c5b"]}]}]}'
curl -G "https://api.vozkoia.com/crm/entries" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "X-Workspace-ID: SEU_WORKSPACE_ID" \
  --data-urlencode 'filter=eyJncm91cHMiOlt7ImNvbmp1bmN0aW9uIjoiYW5kIiwicHJlZGljYXRlcyI6W3siZmllbGQiOiJzdGFnZSIsIm9wZXJhdG9yIjoiaW4iLCJ2YWx1ZXMiOlsiMGI5ZThkN2MtNmE1Zi00ZTNkLTJjMWItMGE5ZjhlN2Q2YzViIl19XX1dfQ=='

Em GET /leads, os filtros simples da URL (q, name, number, createdFrom, stageId e os demais) viram grupos extras e se somam ao filter com E.

No corpo da requisição

RecursoOnde vai o filtro
Visões salvas (POST /saved-views, PUT /saved-views/{id})filter, junto com objectType, que diz a qual tipo de registro o filtro se aplica.
Ação em massa no CRM (POST /crm/bulk/count, POST /crm/bulk)filter, com mode, expectedCount e fingerprint (veja Contagem confirmada).
Lista de clientes de anúncios (POST /ads/audiences/customer-list)crmFilter, com source igual a crm. Um filtro em campo personalizado sensível responde 422 audience_sensitive_filter.
Elo (POST /chat/threads/{id}/messages)view.leadFilter, com view.surface igual a leads: o filtro da tela de Leads, até 16 KiB, validado como um filtro de leads. As ferramentas de leads do Elo podem partir dele.
Seleções de leadsfilter dentro da seleção, descrita a seguir.

Seleção de leads

Ações em massa e públicos de campanha não recebem só um filtro: recebem uma seleção, que diz quais leads entram e confirma quantos eram quando a pessoa conferiu. A seleção tem estes campos:

CampoO que é
modeids, all_matching, first_n ou everyone.
idsOs leads escolhidos um a um, no modo ids. Até 5.000.
filterO filtro, nos modos all_matching e first_n. Precisa ter pelo menos um predicado, e todo grupo com predicados precisa declarar conjunction.
sortA ordem do modo first_n: lista de {"field", "key"?, "desc"?}.
limitQuantos leads entram no modo first_n: de 1 a 200.000.
excludeIdsLeads tirados da seleção. Até 5.000.
includeIdsLeads somados à seleção. Até 5.000.
expectedCountQuantos leads a contagem mostrou.
fingerprintA impressão digital da contagem, devolvida por ela.
ModoQuem entraRegras
idsOs leads de ids.Não aceita filter, limit, excludeIds nem includeIds.
all_matchingTodos os leads que atendem ao filtro.Exige um filtro não vazio; não aceita ids nem limit.
first_nOs primeiros limit leads que atendem ao filtro, na ordem de sort.Exige um filtro não vazio e limit; não aceita ids.
everyoneTodos os leads do workspace ao alcance de quem pede.Não aceita ids, limit nem filtro com predicados; sempre exige a contagem confirmada.

A seleção vai em selection nas ações em massa (POST /leads/actions/preview e POST /leads/actions) e nos públicos de campanha que partem de leads: em POST /campaign-audience/{channel}/count, com source igual a leads; em recipients de POST /whatsapp/campaigns e de POST /unofficial-whatsapp/campaigns; e em audience de POST /carrier/campaigns.

{
  "mode": "all_matching",
  "filter": {
    "groups": [
      {
        "conjunction": "and",
        "predicates": [
          { "field": "city", "operator": "in", "values": ["sp:campinas"] },
          { "field": "opted_out", "operator": "is_false" }
        ]
      }
    ]
  },
  "excludeIds": ["9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"],
  "expectedCount": 340,
  "fingerprint": "FINGERPRINT_DA_CONTAGEM"
}

As campanhas de e-mail (POST /email/campaigns, PATCH /email/campaigns/{campaignId}) recebem a seleção em selection, com os mesmos modos e regras, mas com as chaves exclude_ids e include_ids e sem expectedCount e fingerprint. Um filtro inválido nelas responde 400 email_recipient_filter_invalid.

Contagem confirmada

Para que uma ação nunca alcance mais gente do que a pessoa viu, os modos por filtro e everyone são confirmados em dois passos:

  1. Conte. Envie a seleção sem expectedCount e fingerprint à rota de contagem do recurso: POST /leads/actions/preview nas ações sobre leads, POST /campaign-audience/{channel}/count nos públicos de campanha, POST /crm/bulk/count nas conversas do CRM. A resposta traz a contagem e o fingerprint.
  2. Confirme. Envie a mesma seleção com expectedCount igual à contagem mostrada e o fingerprint recebido.

O fingerprint é calculado a partir do filtro efetivo (e de includeIds), então mudar o filtro depois da contagem recusa a confirmação com selection_fingerprint_mismatch. Se a contagem agora é outra, a recusa é selection_changed: nas ações sobre leads e na ação em massa do CRM, com status 409, a contagem esperada em expected e a atual em matched. Conte de novo e confirme. Fora do modo ids, confirmar sem expectedCount é recusado com selection_count_required. As campanhas de RCS e SMS respondem à falta de confirmação e à impressão digital diferente com 409 carrier_campaign_audience_unconfirmed.

Na ação em massa do CRM (POST /crm/bulk), o pedido usa os mesmos nomes no próprio corpo (filter, mode, expectedCount, fingerprint, excludeIds), com os modos ids (as conversas de targets), all_matching e everyone.

Validação

Toda requisição com filtro passa pela mesma validação. Um filtro é recusado quando:

  • field não é um campo da linguagem;
  • o operador não é aceito pelo campo;
  • falta valor num operador que precisa de valor (is_set, is_empty, is_true e is_false não precisam);
  • between não tem exatamente dois valores;
  • um número não é decimal com ponto (1,5 é recusado; use 1.5);
  • uma data não é AAAA-MM-DD nem RFC 3339 (01/10/2026 é recusado);
  • custom vem sem key, ou area vem com uma key diferente de vazia e de exact_only;
  • um valor não tem o formato do campo, nos campos com formato próprio, como id, city, district, state, zip, phone_any, birthday, sentiment e geo_placement (por exemplo, state com São Paulo em vez de SP, ou city com Campinas em vez de sp:campinas);
  • um predicado passa do limite de valores do campo (200 em zip e district, 20 em area e area_approximate);
  • numa seleção, um grupo com predicados não declara conjunction.

Os leads conferem ainda os valores de owner, source, geo_status, geo_precision, relation_kind e opt_out_source, os campos personalizados contra a definição de cada um e a busca de query.

Erros

RecursoResposta
Leads, mapa e seções400 lead_filter_invalid; 400 lead_search_too_short quando a busca não tem palavra de 2 caracteres ou mais; 400 custom_field_filter_unknown_key, custom_field_filter_operator ou custom_field_filter_value num campo personalizado; 400 area_not_found ou area_too_many em áreas; 403 lead_filter_address_forbidden e 403 custom_field_filter_sensitive_forbidden sem a permissão.
Seleções (ações em massa, públicos de campanha, ação em massa do CRM)400 invalid_filter para um filtro inválido ou que não se aplica ao tipo de registro (nas ações sobre leads, também os códigos da linha anterior), e os códigos selection_* para a seleção.
Quadro e lista do CRM400 para um filtro ilegível ou inválido; 400 conversation_origin_invalid para uma origem desconhecida em origin.
Campanhas de e-mail400 email_recipient_filter_invalid.

O formato de todas as respostas de erro está em Erros.

Veja também