SDK Node.js: установка и методы

Установка

Node.js 20 или новее. ESM, CommonJS и типы TypeScript входят в пакет. Дополнительных зависимостей нет.

Команда устанавливает пакет из npm. API v1 одинаков для всех трёх SDK; инструкции в репозиториях доступны на русском.

npm install waix-node

Ключ и первый запрос

Ключ хранится на сервере. Для отправки нужен scope messages:write; для чтения — messages:read. Connection ID берётся из раздела WhatsApp. Подготовьте собственный одобренный шаблон с одной переменной или измените компоненты примера.

import { Waix } from 'waix-node';
import { randomUUID } from 'node:crypto';

const waix = new Waix(process.env.WAIX_API_KEY);
// Сохраните UUID в записи заказа до отправки.
const eventId = randomUUID();
const { data } = await waix.messages.send({
  connection_id: process.env.WAIX_CONNECTION_ID,
  to: '+77071234567',
  type: 'template',
  template: {
    name: 'order_ready',
    language: { code: 'ru' },
    components: [{ type: 'body', parameters: [
      { type: 'text', text: '42' }
    ] }]
  }
}, eventId);

UUID создаётся один раз для логической отправки и сохраняется до запроса. После тайм-аута повторяйте тот же запрос с тем же UUID; новый ключ означает новое сообщение. HTTP 202 подтверждает постановку в очередь, а не доставку.

Ошибки и тайм-аут

Исключение WaixError содержит status, code, requestId, retryAfter. HTTP-статус 0 означает транспортную ошибку или тайм-аут. По request ID поддержка может найти запрос; ключи и полные тела сообщений в журнал писать не нужно.

Настройка тайм-аута: timeout: 30000 — миллисекунды. По умолчанию 30 секунд. Автоматических повторов и переходов по редиректам нет. При 429 дождитесь Retry-After; ошибки 400, 401 и 403 сначала исправьте.

OTP: отправить, проверить, узнать статус

Нужен ключ OTP-проекта с соответствующими правами. В sandbox отправка возвращает test_code и не обращается к WhatsApp. Не передавайте test_code посетителю: проверка потеряет смысл.

const otp = new Waix(process.env.WAIX_OTP_PROJECT_KEY);
const sent = await otp.otp.send({to: '+77071234567', ttl: 300}, eventId);
// Сохраните sent.data.id в сессии пользователя.
const status = await otp.otp.status(sent.data.id);
const result = await otp.otp.verify(sent.data.id, suppliedCode);

Пример показывает отдельные этапы. suppliedCode / supplied_code / $suppliedCode — код из следующего запроса того же пользователя. Challenge ID хранится в его серверной сессии, а не принимается без проверки от любого посетителя. Успешная доставка кода ещё не означает успешную авторизацию.

Медиа и пагинация

waix.media.upload(connectionId, new Blob([bytes], {type: 'application/pdf'}), 'invoice.pdf', {type: 'document'})

Укажите Connection ID, MIME-тип и вид медиа. Файлы должны соответствовать ограничениям API. Python загружает файл в память; для больших документов учитывайте доступную память процесса.

waix.messages.list({limit: 50, before, before_id})

Метод возвращает весь JSON-ответ. Для следующей страницы передайте одновременно pagination.next_before и pagination.next_before_id. Когда оба значения отсутствуют, список закончился.

Проверка вебхука

verifyWebhook(rawBody, timestamp, signature, secret)

rawBody / raw_body — исходные байты HTTP-запроса до JSON-парсера. timestamp и signature — заголовки X-Waix-Timestamp и X-Waix-Signature. secret — секрет вашего вебхука или OTP-проекта.

Проверка сравнивает HMAC-SHA256 за постоянное время и допускает расхождение часов до 300 секунд. Неверная подпись или просроченное время дают false. После проверки сохраняйте X-Waix-Delivery и не обрабатывайте одно событие дважды.

SDK 0.2: журнал и диагностика

Во всех SDK появился messages.iterate: он читает журнал по страницам, сохраняет фильтры и переносит оба курсора. У Node.js это async iterator, у Python и PHP — generator. Полный журнал не нужно загружать в память.

По умолчанию ответ ограничен 2 МиБ. Ошибки HTTP сохраняют статус, request ID и Retry-After, даже если прокси вернул HTML. Повторный курсор и превышение заданного количества страниц останавливают обход с понятной ошибкой.

Для журналирования используйте error.toJSON() в Node.js, error.to_dict() в Python или json_encode($error) в PHP. Эти методы исключают тело ответа, которое может содержать данные клиента. Полные примеры и настройки лимитов приведены в README пакета.

Остальные методы

SDK поддерживают чтение и обновление профиля номера, создание и редактирование шаблонов, preview, удаление медиа, настройку вебхука и смену его секрета. Названия методов и полные сигнатуры приведены в README пакета. Для новых методов API v1 есть общий request с относительным путём.

Часть методов управления требует более широких прав. OTP-ключ проекта не может изменять общий вебхук компании. Не расширяйте права рабочего ключа только ради отладки: создайте отдельный ключ для нужной операции.