Customização via código

O plugin é extensível por filtros e actions do WordPress. Você pode adicionar gatilhos próprios, registrar variáveis novas, alterar comportamento, integrar com plugins não suportados nativamente — sem tocar no código do plugin.

Esse artigo é uma referência pra desenvolvedores que precisam ir além do que o painel oferece.

Onde colocar o código

As snippets desse artigo vão num plugin custom da sua loja ou no functions.php do tema filho. O ideal é plugin próprio — sobrevive a troca de tema e fica isolado.

Estrutura mínima:

<?php
/**
 * Plugin Name: Customizações Loja XYZ - WhatsApp
 */

if ( ! defined( 'ABSPATH' ) ) {
  exit;
}

// suas customizações abaixo

Registrar gatilho customizado

Caso de uso: você tem um plugin custom que dispara do_action( 'minha_loja_assinatura_renovada', $assinatura_id ). Quer mandar WhatsApp quando isso acontece.

add_filter( 'automation_for_whatsapp_hooks', function ( $hooks ) {
  $hooks['minha_loja'] = [
    'name'  => 'Minha Loja - Eventos custom',
    'hooks' => [
      'minha_loja_assinatura_renovada' => 'Assinatura renovada',
    ],
  ];

  return $hooks;
} );

add_filter( 'automation_for_whatsapp_custom_hooks', function ( $hooks ) {
  $hooks[] = 'minha_loja_assinatura_renovada';
  return $hooks;
} );

Pronto: o gatilho aparece no painel WhatsApp e o lojista pode cadastrar mensagem associada.

Adicionar variáveis específicas pro gatilho

Se você quer expor variáveis que só fazem sentido nesse gatilho específico:

add_filter( 'automation_for_whatsapp_hook_placeholders', function ( $placeholders, $hook, $hook_args ) {
  if ( 'minha_loja_assinatura_renovada' !== $hook ) {
    return $placeholders;
  }

  $assinatura_id = $hook_args[0];
  // ... busque dados da assinatura ...

  $placeholders['{{first_name}}']        = 'Nome do cliente';
  $placeholders['{{phone_number}}']      = '5511999998888';
  $placeholders['{{assinatura_id}}']     = $assinatura_id;
  $placeholders['{{proximo_pagamento}}'] = '15/01/2026';

  return $placeholders;
}, 200, 3 );

E pra registrar essas variáveis na tabela do painel (pra aparecerem no autocomplete):

add_filter( 'automation_for_whatsapp_placeholders', function ( $placeholders ) {
  $placeholders['minha_loja'] = [
    'label'        => 'Minha Loja',
    'placeholders' => [
      '{{assinatura_id}}'     => 'ID da assinatura',
      '{{proximo_pagamento}}' => 'Data do próximo pagamento (DD/MM/AAAA)',
    ],
  ];

  return $placeholders;
} );

Filtros pra customizar coleta de telefone

Caso de uso: o telefone do cliente está num campo customizado, não no campo padrão do WooCommerce.

add_filter( 'automation_for_whatsapp_get_order_phone', function ( $phone, $order ) {
  if ( empty( $phone ) ) {
    $phone = $order->get_meta( '_meu_campo_phone' );
  }

  return $phone;
}, 10, 2 );

Pra usuário (não pedido):

add_filter( 'automation_for_whatsapp_user_phone', function ( $phone, $user ) {
  if ( empty( $phone ) ) {
    $phone = get_user_meta( $user->ID, 'meu_campo_phone', true );
  }

  return $phone;
}, 10, 2 );

Adicionar variáveis genéricas (qualquer gatilho de pedido)

Se você quer uma variável que valha pra todos os gatilhos de pedido:

add_filter( 'automation_for_whatsapp_order_placeholders', function ( $placeholders, $order ) {
  $placeholders['{{cpf}}']      = $order->get_meta( '_billing_cpf' );
  $placeholders['{{empresa}}']  = $order->get_billing_company();

  return $placeholders;
}, 10, 2 );

E a versão pra produtos:

add_filter( 'automation_for_whatsapp_product_placeholders', function ( $placeholders, $product ) {
  $placeholders['{{categoria_principal}}'] = wp_get_post_terms( $product->get_id(), 'product_cat' )[0]->name ?? '';

  return $placeholders;
}, 10, 2 );

Adicionar plugin de rastreio customizado

Se sua transportadora (ou plugin) não está na lista oficial:

add_filter( 'automation_for_whatsapp_tracking_hooks', function ( $tracking ) {
  $tracking['minha_transportadora'] = 'Minha Transportadora';
  return $tracking;
} );

add_filter( 'automation_for_whatsapp_custom_hooks', function ( $hooks ) {
  $hooks[] = 'automation_for_whatsapp_tracking_minha_transportadora';
  return $hooks;
} );

// Quando o código de rastreio for adicionado, dispare o gatilho:
add_action( 'minha_transportadora_tracking_added', function ( $tracking_code, $order ) {
  if ( ! $order ) return;

  $order->update_meta_data( 'automation_for_whatsapp_tracking_code', $tracking_code );
  $order->save();

  do_action( 'automation_for_whatsapp_tracking_minha_transportadora', $order );
}, 100, 2 );

A variável {{tracking_code}} fica disponível automaticamente.

Modificar a mensagem antes do envio

Caso de uso: você quer adicionar prefixo, substituir palavras, ou aplicar regras finais antes da mensagem sair.

add_filter( 'automation_for_whatsapp_format_string', function ( $text, $connector ) {
  // adicionar prefixo padrão
  $text = "[Loja XYZ]\n\n" . $text;

  // substituir certas palavras
  $text = str_replace( 'pedido', 'compra', $text );

  return $text;
}, 10, 2 );

Bloquear envio condicionalmente

Caso de uso: nunca mandar mensagem em domingo, ou nunca pra clientes flaggeados como "não-receber".

add_filter( 'automation_for_whatsapp_disable_messages', function ( $disable, $db_message, $settings ) {
  // bloqueia em domingo
  if ( date( 'w' ) === '0' ) {
    return true;
  }

  return $disable;
}, 10, 3 );

Hooks de ciclo de vida

Pra reagir a eventos do plugin:

// quando uma nova mensagem é cadastrada
add_action( 'automation_for_whatsapp_message_created', function ( $message_id, $values ) {
  // ex: notificar admin que mensagem nova foi criada
}, 10, 2 );

// quando uma mensagem é atualizada
add_action( 'automation_for_whatsapp_message_updated', function ( $message_id, $values ) {
  // ex: invalidar cache custom
}, 10, 2 );

// quando o queue dispara (mensagem efetivamente sendo enviada)
add_action( 'automation_for_whatsapp_queue', function ( $body, $db_message ) {
  // ex: log custom adicional
}, 10, 2 );

Restringir quem acessa as configurações

Por padrão, apenas usuários com manage_options (administradores) acessam o painel. Pra abrir pra outros papéis:

add_filter( 'automation_for_whatsapp_capability', function () {
  return 'manage_woocommerce'; // ou outra capability
} );

Disparar mensagem programaticamente

Sem cadastrar nada no painel, só código:

automation_for_whatsapp_send_message(
  'Olá! Mensagem direta enviada via código.',
  '5511999998888',
  'meu_trigger_custom'
);

Útil em hooks específicos onde você não quer passar pelo sistema de mensagens cadastradas.

Funções auxiliares

Disponíveis pra uso em qualquer lugar:

// pegar conector ativo
$connector = automation_for_whatsapp_get_connector();

// pegar telefone do pedido (com filters aplicados)
$phone = automation_for_whatsapp_get_order_phone( $order );

// pegar telefone do usuário
$phone = afw_get_user_phone( $user );

// pegar todos os hooks/gatilhos disponíveis
$hooks = automation_for_whatsapp_get_hooks();

// pegar status válidos do WooCommerce
$statuses = automation_for_whatsapp_get_order_statuses();

// pegar gateways disponíveis
$gateways = automation_for_whatsapp_get_available_payment_gateways();

// pegar lista completa de placeholders (para autocompletes etc)
$placeholders = automation_for_whatsapp_get_order_placeholders_list();

Acesso direto ao banco

A classe Database expõe operações nas mensagens cadastradas:

$database = new \Automation_For_WhatsApp\Database();

// listar todas
$messages = $database->get_messages();

// buscar uma específica
$message = $database->get_message( $message_id );

// buscar por hook
$messages = $database->get_messages_by_hook( 'minha_loja_assinatura_renovada', 'active' );

// adicionar nova
$id = $database->add_message( [
  'hook'         => 'woocommerce_new_order',
  'message_name' => 'Mensagem via código',
  'message'      => 'Olá {{first_name}}!',
  'status'       => 'active',
  'receiver'     => '{{phone_number}}',
  'hook_params'  => [ 'delay' => 5 ],
] );

// atualizar
$database->update_message( $message_id, [ 'status' => 'inactive' ] );

// deletar
$database->delete_message( $message_id );

Criar handler ou conector customizado

Pra casos avançados — adicionar lógica que afeta como mensagens são processadas.

Handler customizado

use Automation_For_WhatsApp\Hooks\Handler;

class Meu_Handler extends Handler {
  public $hooks = [ 'meu_hook_complexo' ];

  public function get_messages( $args ) {
    // lógica para decidir quais mensagens disparar
    return $this->database->get_messages_by_hook( 'meu_hook_complexo' );
  }
}

new Meu_Handler();

Útil quando o gatilho original tem lógica complexa que precisa transformar $args antes de buscar mensagens.

Conector customizado

Pra substituir o canal de envio (ex: enviar pra outra API que não Rishi):

use Automation_For_WhatsApp\Connectors\Abstracts\Abstract_Connector_API;

class Meu_Connector extends Abstract_Connector_API {
  public $id = 'meu_connector';

  public function send_message( $message, $placeholders, $hook_args, $db_message, $trigger ) {
    // sua lógica de envio
  }

  public function send_messages( $messages, $placeholders, $hook_args, $db_message, $hook ) {
    // multi-mensagem
  }
}

Você precisaria ainda fazer o plugin escolher esse conector, o que envolve modificar automation_for_whatsapp_get_api() ou adicionar filtros — depende da versão do plugin. Esse caso é raro: em 99% dos cenários, o conector Rishi serve.

Lista resumida de filters e actions

Pra referência rápida:

Próximos passos

• Mensagens não entregues — diagnóstico — investigação quando algo não funciona
• Variáveis de mensagem — pra entender quais já existem antes de criar custom