Base de Conhecimento

Este tutorial explica como utilizar um hook do WHMCS para organizar automaticamente os clientes em grupos, de acordo com o status da conta (Ativo ou Inativo).

O processo é executado automaticamente pelo cron diário do WHMCS, sem necessidade de ação manual.

O que este hook faz

O hook executa as seguintes ações:

• Clientes com status Ativo (Active) são movidos para o grupo Ativos
• Clientes com status Inativo (Inactive) são movidos para o grupo Inativos
• O processo roda automaticamente uma vez por dia

Se o cliente já estiver no grupo correto, nenhuma alteração é feita.

Pré-requisitos

• WHMCS instalado e funcionando
• Acesso ao servidor (FTP ou Gerenciador de Arquivos)
• Grupos de clientes já criados no WHMCS

Importante: Anote o ID de cada grupo antes de continuar.

Passo 1 – Criar os grupos de clientes

1. Acesse o painel administrativo do WHMCS.
2. Vá em Configurações > Clientes > Grupos de Clientes.
3. Crie os grupos desejados, por exemplo:
   • Clientes Ativos
   • Clientes Inativos
4. Anote o ID de cada grupo.

Passo 2 – Criar o arquivo do hook

1. Acesse os arquivos do WHMCS via FTP ou Gerenciador de Arquivos.
2. Entre no diretório: /includes/hooks/
3. Crie um novo arquivo, por exemplo: clientes_grupo_por_status.php

Passo 3 – Inserir o código do hook

Abra o arquivo criado e cole o código abaixo:

<?php

use WHMCS\Database\Capsule;

add_hook('DailyCronJob', 1, function () {

    // Grupos
    $grupoAtivo   = 7;
    $grupoInativo = 12;

    // -------------------------------------------------
    // 1) CLIENTES ATIVOS
    // -------------------------------------------------
    Capsule::table('tblclients')
        ->where('status', 'Active')
        ->where('groupid', '!=', $grupoAtivo)
        ->update(['groupid' => $grupoAtivo]);

    // -------------------------------------------------
    // 2) CLIENTES INATIVOS
    // -------------------------------------------------
    Capsule::table('tblclients')
        ->where('status', 'Inactive')
        ->where('groupid', '!=', $grupoInativo)
        ->update(['groupid' => $grupoInativo]);

});

Atenção: Altere os valores 7 e 12 para os IDs reais dos grupos existentes no seu WHMCS.

Passo 4 – Funcionamento do hook

Este hook é executado automaticamente pelo evento:

• DailyCronJob

Ou seja, ele roda sempre que o cron diário do WHMCS é executado, normalmente uma vez por dia.

Durante a execução:

• Clientes ativos são movidos para o grupo correto
• Clientes inativos são movidos para o grupo correto
• Não há impacto no painel do cliente

Resultado esperado

Após o cron diário rodar:

• Clientes ativos estarão sempre no grupo configurado
• Clientes inativos estarão sempre no grupo configurado
• Não será mais necessário ajustar grupos manualmente

Observações importantes

• O hook altera apenas o campo groupid da tabela tblclients.
• Clientes com outros status (Suspended, Closed, etc.) não são afetados.
• Recomenda-se testar em ambiente de homologação antes de usar em produção.