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:
| Campo | Onde | O que é |
|---|---|---|
groups | filtro | Lista de grupos. Os grupos sempre se combinam com E: o registro precisa atender a todos. |
conjunction | grupo | and (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). |
predicates | grupo | Lista de condições. Um grupo sem predicados é ignorado. |
field | predicado | O campo testado, como stage, created_at ou custom. |
key | predicado | Complemento do campo: a chave do campo personalizado em custom e o modo da área em area. Os demais campos não usam. |
operator | predicado | A comparação, como in, between ou is_set. Cada campo aceita só alguns operadores. |
values | predicado | Os 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):
| Registro | Recursos |
|---|---|
| Conversas (CRM) | GET /crm/board, GET /crm/entries, POST /crm/bulk e POST /crm/bulk/count, visões salvas com objectType conversation. |
| Negociações | GET /opportunities/board, GET /opportunities/list, visões salvas com objectType opportunity. |
| Leads | GET /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
filter da URLAs 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
| Recurso | Onde 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 leads | filter 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:
| Campo | O que é |
|---|---|
mode | ids, all_matching, first_n ou everyone. |
ids | Os leads escolhidos um a um, no modo ids. Até 5.000. |
filter | O filtro, nos modos all_matching e first_n. Precisa ter pelo menos um predicado, e todo grupo com predicados precisa declarar conjunction. |
sort | A ordem do modo first_n: lista de {"field", "key"?, "desc"?}. |
limit | Quantos leads entram no modo first_n: de 1 a 200.000. |
excludeIds | Leads tirados da seleção. Até 5.000. |
includeIds | Leads somados à seleção. Até 5.000. |
expectedCount | Quantos leads a contagem mostrou. |
fingerprint | A impressão digital da contagem, devolvida por ela. |
| Modo | Quem entra | Regras |
|---|---|---|
ids | Os leads de ids. | Não aceita filter, limit, excludeIds nem includeIds. |
all_matching | Todos os leads que atendem ao filtro. | Exige um filtro não vazio; não aceita ids nem limit. |
first_n | Os primeiros limit leads que atendem ao filtro, na ordem de sort. | Exige um filtro não vazio e limit; não aceita ids. |
everyone | Todos 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:
- Conte. Envie a seleção sem
expectedCountefingerprintà rota de contagem do recurso:POST /leads/actions/previewnas ações sobre leads,POST /campaign-audience/{channel}/countnos públicos de campanha,POST /crm/bulk/countnas conversas do CRM. A resposta traz a contagem e ofingerprint. - Confirme. Envie a mesma seleção com
expectedCountigual à contagem mostrada e ofingerprintrecebido.
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:
fieldnã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_trueeis_falsenão precisam); betweennão tem exatamente dois valores;- um número não é decimal com ponto (
1,5é recusado; use1.5); - uma data não é
AAAA-MM-DDnem RFC 3339 (01/10/2026é recusado); customvem semkey, ouareavem com umakeydiferente de vazia e deexact_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,sentimentegeo_placement(por exemplo,statecomSão Pauloem vez deSP, oucitycomCampinasem vez desp:campinas); - um predicado passa do limite de valores do campo (200 em
zipedistrict, 20 emareaearea_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
| Recurso | Resposta |
|---|---|
| Leads, mapa e seções | 400 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 CRM | 400 para um filtro ilegível ou inválido; 400 conversation_origin_invalid para uma origem desconhecida em origin. |
| Campanhas de e-mail | 400 email_recipient_filter_invalid. |
O formato de todas as respostas de erro está em Erros.
Veja também
- Campos do filtro: cada campo, com operadores, valores e limites.
- Na Referência da API: Leads, CRM, Negociações, Visões salvas, Público de campanhas e Anúncios.