Filtros

Restrinja conversations às threads que interessam com o argumento filter — uma consulta booleana sobre os tag-links de classificação de cada thread, avaliada no servidor para você não paginar tudo e filtrar no cliente.

Uma cláusula de filtro

A unidade de um filtro é um TagMatch: { value, reference }. Uma cláusula corresponde a uma thread quando essa thread tem um tag-link cujo valor é igual a value e — se reference for informado — cuja referência de tag é igual a reference. Ela verifica todo o histórico de links da thread, não apenas o estado mais recente. value é obrigatório; reference é opcional (omita para corresponder ao valor sob qualquer referência).

must / should

Combine cláusulas com uma consulta booleana no estilo Elasticsearch. Uma thread corresponde ao filter quando satisfaz:

• todas as cláusulas must (E), e
• ao menos uma cláusula should (OU) — exigido apenas quando should não está vazio.

A API retorna somente as threads correspondentes: uma conversa aparece apenas quando tem ao menos uma thread correspondente, e suas threads não correspondentes são removidas do resultado. Um filter vazio ou ausente não aplica filtragem.

Referências comuns

Os campos de classificação projetados mapeiam para estas references de tag. Use uma para escopar a correspondência, ou omita reference para corresponder a qualquer uma.

classifier_state e chat_state são conjuntos fixos, definidos pelo sistema — um valor de filtro fora do conjunto de uma referência é sintaticamente válido, mas não corresponde a nenhuma thread. Referências livres (classified_category e outras tags por organização) aceitam qualquer valor.

Filtrar por classifier state

Escope uma cláusula com reference para mirar um campo. Isto retorna conversas que têm uma thread que chegou a resolved, apenas com essas threads:

query Resolved {
  conversations(
    first: 10
    filter: { must: [{ reference: "classifier_state", value: "resolved" }] }
  ) {
    edges {
      node {
        conversationId
        threads {
          threadId
          classifierState { value linkedAt }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Corresponder a qualquer referência

Omita reference para corresponder a um valor independentemente da tag a que pertence — um filtro genérico de tag-link:

query AnyReference {
  conversations(
    first: 10
    filter: { must: [{ value: "transfer_request" }] }
  ) {
    edges { node { conversationId threads { threadId } } }
    pageInfo { hasNextPage endCursor }
  }
}

Combinar must e should

Exija uma categoria (must) e, dentre elas, qualquer um de vários chat states (should):

query MustAndShould {
  conversations(
    first: 10
    filter: {
      must: [{ reference: "classified_category", value: "order_cancellation" }]
      should: [
        { reference: "chat_state", value: "transfer_request" }
        { reference: "chat_state", value: "inactive" }
      ]
    }
  ) {
    edges { node { conversationId threads { threadId } } }
    pageInfo { hasNextPage endCursor }
  }
}

Filtrar por período

startDate/endDate restringem quais conversas são selecionadas por quando começaram — os dois limites são inclusivos e independentemente opcionais. Diferente de must/should, isso nunca remove uma thread do payload de uma conversa correspondente. Informe um timestamp completo, não só uma data — a comparação é pelo instante exato.

query LastWeek {
  conversations(
    first: 10
    filter: {
      startDate: "2026-06-01T00:00:00.000Z"
      endDate: "2026-06-07T23:59:59.999Z"
    }
  ) {
    edges { node { conversationId threads { threadId } } }
    pageInfo { hasNextPage endCursor }
  }
}

Combinar um período com um filtro de tag

Conversas iniciadas na janela E que têm uma thread que chegou a resolved — o caso real de "me mostre as conversas resolvidas da semana passada":

query LastWeekResolved {
  conversations(
    first: 10
    filter: {
      startDate: "2026-06-01T00:00:00.000Z"
      endDate: "2026-06-07T23:59:59.999Z"
      must: [{ reference: "classifier_state", value: "resolved" }]
    }
  ) {
    edges { node { conversationId threads { threadId classifierState { value linkedAt } } } }
    pageInfo { hasNextPage endCursor }
  }
}

Observações

• filter se combina com a paginação — as cláusulas são aplicadas antes da paginação, e os limites de first continuam valendo sobre o resultado filtrado.
• A ordenação não muda: as conversas são ordenadas das mais antigas para as mais recentes pela thread correspondente mais antiga, então os cursores permanecem estáveis dentro do conjunto filtrado.
• Veja Paginação para paginar o resultado e a Referência do schema para o formato completo de ConversationFilter / TagMatch.