Filtros: gateway, categoria, status, delay
Os filtros (também chamados de "parâmetros do gatilho") refinam quando uma mensagem deve disparar dentro do evento escolhido.
Sem filtros, uma mensagem cadastrada no gatilho "Novo pedido" dispara em todo novo pedido — Pix, boleto, cartão, qualquer categoria de produto, qualquer valor. Com filtros, você restringe: "só pra Pix", "só pra produtos da categoria Eletrônicos", "30 minutos depois do evento".
Esse artigo cobre os 5 filtros disponíveis no formulário de mensagem.
Onde ficam
No formulário de criar/editar mensagem, role até a seção Filtros (também chamada de Parâmetros do gatilho ou hook_params dependendo da versão). Cada filtro tem campo próprio na interface.
Delay (atraso)
Adia o envio em minutos. Mensagem só vai depois desse tempo passar contado a partir do evento.
| Cenário | Delay sugerido |
|---|---|
| Lembrete de Pix (gerado, não pago) | 30-60 minutos |
| Lembrete de boleto | 1-2 dias (em minutos: 1440 ou 2880) |
| NPS pós-entrega | 7-14 dias |
| Agradecimento pós-entrega | 30 minutos depois do "Concluído" |
Mensagens com delay sempre passam pelo agendamento, mesmo se o campo "envio assíncrono" estiver como Não. Veja Mensagens agendadas e fila assíncrona.
Quando combinado com status (próximo filtro), o delay funciona como gatilho condicional: "espera 30 minutos e, se ainda estiver pendente, dispara". Padrão básico de lembrete de pagamento.
Status do pedido
Restringe a quais status o pedido precisa ter pra mensagem disparar. Aceita múltiplos.
Útil principalmente em combinação com delay ou com o gatilho "Novo pedido":
Gatilho: Novo pedido
Delay: 30 minutos
Status: [Pendente, Aguardando]
→ Dispara 30 minutos após a criação só se o pedido ainda estiver em Pendente ou Aguardando. Se foi pago no meio tempo, não dispara.
Esse é o padrão pra lembretes de pagamento. Veja Lembretes de Pix e boleto.
Esse filtro não substitui o gatilho "Status processando" / "Status concluído" etc. A diferença é semântica:
- Gatilho "Status X" dispara quando o pedido entra em X.
- Filtro Status valida que o pedido está em X no momento do disparo (geralmente combinado com delay).
Gateway (forma de pagamento)
Restringe a quais métodos de pagamento a mensagem se aplica. Aceita múltiplos.
Casos comuns:
| Mensagem | Filtro |
|---|---|
Lembrete Pix com {{pix_code}} |
Gateways Pix (Click2pay, Efi, Mercado Pago Pix, etc) |
Lembrete boleto com {{direct_payment_url}} |
Gateways de boleto |
| Confirmação para cartão | Gateways de cartão (Stripe, MP cartão, etc) |
| Genérica (qualquer pagamento) | Vazio (sem filtro) |
A lista de gateways disponíveis é montada dinamicamente a partir do que está ativo no WooCommerce → Configurações → Pagamentos. Se você habilitar um gateway novo, ele aparece como opção automaticamente.
Gerencianet/Efi tem dois itens na lista — um pra Pix, outro pra Boleto — porque o mesmo gateway oferece os dois métodos. Se você usa essa gateway, escolha o item correto pra cada mensagem.
Categoria do produto (obrigatória)
Restringe a pedidos que tenham pelo menos um produto das categorias selecionadas. Aceita múltiplas.
Exemplos:
- "Manual de instalação" só pra pedidos de Eletrônicos
- "Aviso de prazo de fabricação" só pra pedidos de Sob Encomenda
- "Cuidados especiais" só pra Frágeis
Se o pedido tiver itens de várias categorias, basta um estar na lista pra mensagem disparar.
Categoria do produto (excluída)
O inverso da anterior — restringe a pedidos que não tenham itens das categorias listadas.
Exemplo: mensagem padrão de "Pagamento aprovado" pra todo pedido exceto os da categoria Digital (que talvez tenham outra mensagem específica).
Cuidado com a sobreposição. Se você usa categoria obrigatória + excluída ao mesmo tempo, o pedido precisa atender as duas regras. É um filtro AND, não OR. Cuide pra que não fiquem contraditórios.
Combinando filtros
Os filtros são todos AND — todos precisam ser satisfeitos pra mensagem disparar.
Exemplo de combinação real:
Gatilho: Novo pedido
Delay: 60 minutos
Status: [Pendente, Aguardando]
Gateway: [Click2pay Pix]
Categoria obrigatória: (nenhuma)
Categoria excluída: [Digital]
→ Dispara 60 minutos depois da criação, se o pedido ainda for Pendente/Aguardando, foi pago via Pix Click2pay, e nenhum item é da categoria Digital.
Isso é específico, mas todos esses filtros foram pensados pra isso: criar a mensagem certa, no momento certo, pro cliente certo.
Combinações comuns
Algumas receitas que cobrem 80% dos casos:
| Caso de uso | Gatilho | Delay | Status | Gateway |
|---|---|---|---|---|
| Confirmação imediata de Pix gerado | Novo pedido | 0 | (vazio) | Pix |
| Lembrete Pix 30min | Novo pedido | 30 | Pendente, Aguardando | Pix |
| Lembrete boleto 1 dia | Novo pedido | 1440 | Pendente, Aguardando | Boleto |
| Pagamento aprovado | Status processando | 0 | (vazio) | (vazio) |
| NPS pós-entrega | Status concluído | 10080 (7 dias) | (vazio) | (vazio) |
Próximos passos
- Lembretes de Pix e boleto — caso de uso completo
- Mensagens agendadas e fila assíncrona — onde mensagens com delay ficam
- Gatilhos: a lista completa de eventos