ACH Mail

Как работает плагин

Тема принимает форму как раньше: проверяет поля, показывает ошибки. Когда заявка готова, тема передаёт её в ach_mail_send(). Дальше плагин:

1. проверяет защиту от роботов и лимит заявок с адреса посетителя;
2. записывает заявку в журнал — с этого момента она не потеряется;
3. отправляет письмо через wp_mail() и, если подключён, сообщение в Telegram;
4. если канал не ответил, ставит повтор и доставляет заявку позже сам.

Вызов

if (function_exists('ach_mail_send')) {
    $r = ach_mail_send('cart', [
        'title'  => 'Заказ из корзины',
        'fields' => [
            'Имя'     => $name,
            'Телефон' => $phone,
            'E-mail'  => $email,
        ],
        'cart'   => [
            'items' => [
                ['name' => 'Товар', 'options' => 'Вариант', 'qty' => 2,
                 'price' => '1 500 ₽', 'sum' => '3 000 ₽', 'url' => $productUrl],
            ],
            'total'    => '3 000 ₽',
            'delivery' => 'Самовывоз',
        ],
        'page'   => $pageUrl,
        'source' => $utmSource,
    ]);

    if (empty($r['ok'])) {
        // показать посетителю $r['error']
    }
}

Параметры

• Первый аргумент — код формы: латиница, цифры, _ и -. По нему в настройках задаются свои получатели формы и фильтруется журнал.
• title — заголовок заявки: тема письма ({form} в шаблоне темы) и первая строка сообщения в Telegram.
• fields — поля. Коротко ['Подпись' => 'значение'] или подробно [['label' => …, 'value' => …, 'type' => 'phone']]. Тип phone, email, url, textarea или text; если не указан, плагин определит сам. Пустые значения пропускаются.
• cart — состав заказа: позиции (name, options, qty, price, sum, url), total и delivery. Суммы передаются готовыми строками — как их показывает сайт.
• page — адрес страницы, с которой ушла заявка.
• source — источник рекламы или любая метка кампании.
• files — адреса приложенных файлов.
• recipients — адреса от темы. Используются, только если в настройках плагина получатели не заданы.
• guard — проверять ли защиту от роботов, по умолчанию да. Для заявок, которые создаёт сам сервер, передайте false.

Ответ

• ['ok' => true, 'id' => 15] — заявка принята и сохранена. Доставка могла уйти в повтор — это видно в журнале.
• ['ok' => true, 'duplicate' => true, 'id' => 15] — та же заявка уже пришла недавно, второй раз не отправляется.
• ['ok' => true, 'spam' => true] — заявку отправил робот. Отвечаем «успешно», чтобы робот не подбирал обход, и ничего не сохраняем.
• ['ok' => false, 'error' => '…'] — слишком много заявок с одного адреса. Текст можно показать посетителю.

Защита от роботов

Токен в разметке формы ломается под кэшем страниц: страница живёт в кэше дольше, чем токен, и настоящий посетитель получает отказ. Поэтому плагин опирается на то, что считает браузер.

• ach_t — секунды от загрузки страницы до отправки. Человек тратит на форму больше нескольких секунд, робот отправляет сразу. Добавьте поле при отправке формы:

  formData.append('ach_t', (performance.now() / 1000).toFixed(1));

• ach_hp — поле-ловушка, скрытое от людей. Заполнено — значит, робот.
• Лимит заявок в час с одного адреса — в настройках, по умолчанию 10.

Когда тема присылает ach_t во всех формах, включите в настройках «отклонять заявки без поля ach_t» — так отсекаются роботы, которые шлют запрос в обход страницы. Включайте через сутки после выката: у посетителей с открытой старой страницей поля ещё нет.

Хук для своих интеграций

После сохранения заявки срабатывает действие ach_mail_lead_saved — удобно отправить заявку в CRM или учётную систему.

add_action('ach_mail_lead_saved', function ($id, $form, $data, $args) {
    // $data['fields'], $data['cart'], $data['page']
}, 10, 4);

Фильтр ach_mail_lead_data позволяет поправить данные заявки до сохранения.

Если плагин выключат

Проверка function_exists('ach_mail_send') оставляет теме запасной путь: простое письмо администратору сайта. Заявка не потеряется, а в админке стоит повесить предупреждение «включите ACH Mail».

Требования

• PHP 8.1 или новее, WordPress 6.0 или новее.
• Работающая почта сайта: mail() хостинга или SMTP-сервер (настраивается в плагине).
• WP-Cron или системный крон — через него идут повторы доставки и удаление старых заявок.
• Для Telegram — доступ сервера к api.telegram.org. Если хостинг его не открывает, в настройках есть поле прокси.

Установка

1. Загрузите архив в «Плагины → Добавить новый → Загрузить плагин» и активируйте. Обновления приходят в админку сами.
2. Откройте «Заявки → Почта»: укажите получателей, отправителя на домене сайта и при необходимости SMTP. Отправьте тестовое письмо.
3. Добавьте вызов ach_mail_send() в обработчик форм темы — см. вкладку «Использование».

Подключение Telegram

1. Создайте бота у @BotFather командой /newbot — он пришлёт токен.
2. Введите ключ во вкладке «Лицензия» — модуль Telegram загрузится сам (на вкладке «Telegram» появится «Модуль Telegram: подключён»). Затем введите токен бота.
3. Добавьте бота в группу заявок и напишите в группе /start@имя_бота. Обычные сообщения в группе бот не видит, команду видит всегда.
4. Нажмите «Найти группы», выберите группу и отправьте тестовое сообщение.

Что хранит плагин

Заявки — в своей таблице {prefix}ach_mail_leads, настройки — в опции ach_mail_settings. При выключении плагина ничего не удаляется: включили снова — журнал и настройки на месте.