Автоматические уведомления клиентам в WhatsApp через API

Какие уведомления работают

Хорошее уведомление — то, которого человек ждёт, потому что сам что-то начал: купил, записался, оплатил.

• Заказ: принят, собран, готов к выдаче, отменён. Подробно — для интернет-магазинов.
• Оплата и счета: счёт выставлен, оплата получена. Счёт можно приложить PDF-файлом — см. отправку файлов.
• Доставка: передан курьеру, курьер приедет с 14 до 16 — см. сценарий доставки.
• Запись: напоминание за сутки и за пару часов, подтверждение ответом.
• Документы готовы: справка, договор, результаты — «можно забрать» или файл в чат.
• Команде: новая заявка с сайта — менеджеру в личный WhatsApp. Отправки в группы через API нет, поэтому пишите сотрудникам в личные чаты. Сообщения в чат с самим собой в лимит новых контактов не идут.

Что не работает

Реклама незнакомым людям. Купленная база, «акция для всех, кто когда-то звонил», одинаковый текст сотне новых номеров. Массовые сообщения незнакомым — главная причина блокировок номеров в WhatsApp, поэтому у сервиса есть своя защита: если один и тот же текст за час ушёл 25+ новым людям или за час появилось 40+ новых контактов, первые сообщения новым людям приостанавливаются на 24 часа. Подробнее — в гайде как снизить риск блокировки.

Массовые рассылки незнакомым мы не делаем и не помогаем их делать. Если нужен маркетинг на большую базу, смотрите официальный WhatsApp Business API с одобренными шаблонами и платой за сообщения.

Согласие клиента

Проще всего получить согласие там, где клиент оставляет номер: строка рядом с полем телефона «Пришлём статус заказа в WhatsApp» или галочка в форме. Зафиксируйте у себя:

• когда и где дано согласие — дата, форма, сайт или касса;
• на что именно — «уведомления о заказе», а не «всё подряд»;
• отказ: клиент ответил «стоп» — поставьте отметку и больше не пишите. Ответы приходят вебхуком.

Требования к согласию на обработку персональных данных зависят от вашего бизнеса. Это не юридическая консультация — уточните у юриста.

Как писать уведомления

• Представьтесь в первой строке: клиент мог не сохранить ваш номер.
• Коротко: две-три строки. Номер заказа, время, адрес — всё, что нужно, чтобы не переспрашивать.
• Одно действие: «ответьте 1, чтобы подтвердить», «заберите до 20:00».
• Живым языком, без капслока и восклицательных знаков через слово.
• Днём: с 9 до 21 по Алматы. Ночное событие подождёт до утра — кроме кодов входа, их ждут сразу.

Здравствуйте, Ерлан! Это магазин «Ваш магазин». Заказ №1042 собран, доставим завтра с 14:00 до 16:00.
Если время не подходит — ответьте на это сообщение.

Переменные и дубли

Тексты собирают из шаблона с переменными: имя, номер заказа, время. Проверяйте, что все значения на месте: «Здравствуйте, undefined!» хуже, чем «Здравствуйте!». Если имени нет — отправляйте вариант без имени.

Дубли — главная болезнь уведомлений. CRM прислала одно событие дважды, скрипт перезапустился посреди отправки, опрос снова увидел тот же заказ. Решение — ключ события, например order:1042:shipped: перед отправкой проверяйте, не отправляли ли уже сообщение с таким ключом.

WhatsApp вместо SMS: когда да, когда нет

Честно о главном: у получателя должен быть WhatsApp. Проверить номер заранее можно через POST /contacts/check — до 200 проверок в сутки на номер. Для важных уведомлений держите резервный канал: SMS, звонок или email.

По деньгам: номер стоит 9 900 ₸ в месяц, сообщения и запросы к API не тарифицируются. Например, 3 000 уведомлений в месяц стоят те же 9 900 ₸ — в пределах лимитов номера (цены).

Архитектура: событие, очередь, API, статус

Не отправляйте сообщение прямо из обработчика события. Надёжная схема:

1. Событие в системе — заказ сменил статус, пришла оплата — кладёт задачу в очередь с ключом события.
2. Отдельный обработчик берёт задачи по одной, не чаще 1 сообщения в секунду с номера, и вызывает POST /messages/send.
3. Ответ API содержит id сообщения в журнале. Статус доставки придёт вебхуком message.ack: 1 — отправлено, 2 — доставлено, 3 — прочитано, -1 — ошибка. Его же показывает GET /messages/{id}.
4. Временные ошибки — повтор с паузой, лимиты — остановка и сигнал вам.

Пример очереди на Node.js 18+ без библиотек. Для продакшена храните очередь и ключи в базе, чтобы перезапуск ничего не терял.

// notify.mjs — очередь уведомлений: одно сообщение в секунду с номера
const WAPI = "https://wapi.kz/api/v1/messages/send";
const STOP = new Set(["daily_limit", "new_contacts_limit", "cold_blocked", "spam_detected", "number_paused", "not_connected"]);
const queue = [];
const sentKeys = new Set();
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export function notify(key, to, template, vars) {
  if (sentKeys.has(key)) return;                         // это событие уже отправляли
  const text = template.replace(/\{(\w+)\}/g, (_, k) => {
    if (vars[k] == null) throw new Error(`Нет значения для {${k}}`);
    return String(vars[k]);
  });
  sentKeys.add(key);
  queue.push({ key, to, text, tries: 0 });
}

async function send(job) {
  const r = await fetch(WAPI, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.WAPI_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ to: job.to, text: job.text }),
    signal: AbortSignal.timeout(15_000),
  });
  return { status: r.status, data: await r.json().catch(() => ({})) };
}

async function worker() {
  for (;;) {
    const job = queue.shift();
    if (!job) { await sleep(1000); continue; }
    try {
      const { status, data } = await send(job);
      if (status === 200) console.log("отправлено", job.key, "id", data.id);
      else if (STOP.has(data.code)) {
        queue.unshift(job);
        console.error("пауза 15 минут:", data.error);   // сюда — сигнал вам в Telegram
        await sleep(15 * 60_000);
      } else if (data.code === "rate_limited") {
        setTimeout(() => queue.push(job), 5000);         // слишком часто — повторим через 5 секунд
      } else if (status >= 500 && ++job.tries < 3) {
        setTimeout(() => queue.push(job), 30_000);       // временная ошибка — повторим позже
      } else {
        sentKeys.delete(job.key);                        // не отправилось — событие можно поставить в очередь снова
        console.error("не отправлено", job.key, data.code, data.error);
      }
    } catch {
      if (++job.tries < 3) setTimeout(() => queue.push(job), 10_000);
      else sentKeys.delete(job.key);
    }
    await sleep(1000);
  }
}

worker();
// notify("order:1042:shipped", "77011234567", "Заказ №{order} передан курьеру", { order: 1042 });

Код rate_limited придёт и тогда, когда первые сообщения новым людям идут чаще раза в 5 секунд — очередь просто повторит такую задачу позже. Полный список кодов — в разделе ошибок.