Перейти к основному содержимому

WhatsApp-шаблон

Нода WhatsApp-шаблон отправляет одно одобренное Meta шаблонное сообщение на один номер через подключенный канал WhatsApp. В палитре нода находится в разделе Интеграции; на холсте новая нода называется «Шаблон WhatsApp».

Чтобы ответить клиенту, который сам написал в WhatsApp, используйте ноду Ответ в WhatsApp.

Назначение​

  • Уведомление клиента, который вам не писал или писал больше 24 часов назад: статус заказа, напоминание о записи, готовый документ.
  • Массовая рассылка по списку номеров -- через операцию «WhatsApp-шаблон» в ноде ForEach, см. Массовая рассылка.
  • Повторный контакт с клиентом после закрытия 24-часового окна.

Шаблоны и 24-часовое окно​

WhatsApp разрешает отправлять обычные сообщения (свободный текст, изображения) только в течение 24 часов после последнего сообщения клиента. Вне этого окна, а также если клиент вам еще не писал, Meta принимает только шаблоны -- сообщения, заранее созданные и одобренные Meta. Текст шаблона фиксируется при одобрении; изменить можно только значения его переменных.

Эта нода всегда отправляет шаблон, поэтому работает независимо от окна. Было ли окно открыто в момент отправки, показывает поле windowWasOpen результата.

Отправка шаблонов платная

Доставку шаблонов тарифицирует Meta: стоимость зависит от категории шаблона и страны получателя. Шаблоны категории MARKETING тарифицируются при каждой доставке. Категория отправленного шаблона возвращается в поле category.

Перед началом​

  1. Подключите номер WhatsApp. Раздел Интеграции → вкладка WhatsApp → Подключить номер. В поле Проект канала укажите проект, в котором находится процесс: нода отправляет только через каналы своего проекта.
  2. Создайте шаблон в WhatsApp Manager и дождитесь одобрения: модерация Meta занимает до 24 часов.
  3. Синхронизируйте шаблоны. Раздел Интеграции → WhatsApp → у канала Изменить → вкладка Шаблоны → Синхронизировать. Платформа отправляет только шаблоны, которые по последней синхронизации числятся одобренными (статус APPROVED). Если шаблон одобрен после последней синхронизации, синхронизируйте список еще раз.
Белый список номеров

Если в настройках канала включен Белый список номеров, шаблон уходит только на номера из этого списка, хотя подсказка к настройке говорит о входящих сообщениях. Отправка на другой номер завершится ошибкой recipient_not_whitelisted.

Настройки​

Поля перечислены в порядке, в котором они показаны в панели.

Ручной ввод​

Переключатель, по умолчанию выключен. Подсказка «?»: «Ввести канал/шаблон/язык вручную вместо выбора из списков — пригодится, если канал задаётся переменной {{variable}} или кэш шаблонов ещё пуст, потому что синхронизация ни разу не запускалась.»

ВыключенВключен
КаналВыбор из спискаТекстовое поле, принимает переменные
ШаблонВыбор из списка шаблонов каналаПоля «Название шаблона» и «Язык»
Предпросмотр и проверка числа параметровЕстьНет

Ручной ввод не отменяет проверку при отправке: шаблон с указанными названием и языком должен быть синхронизирован и одобрен в аккаунте WhatsApp Business канала, иначе нода вернет ошибку template_not_sendable.

Канал​

Обязательное поле. Подсказка «?»: «Канал WhatsApp, с которого будет отправлено сообщение. В режиме ручного ввода поддерживает {{variable}}.»

  • Список (ручной ввод выключен). Показывает каналы WhatsApp организации. Справа от списка -- кнопки + («Открыть интеграции», открывает раздел интеграций в новой вкладке) и Обновить список. Если каналов нет, в поле написано «В организации нет каналов WhatsApp»; если сохраненный канал удален -- «Канал не найден в организации». При смене канала выбранный шаблон и параметры сбрасываются, язык возвращается к ru: шаблоны принадлежат аккаунту WhatsApp Business канала.
  • Текстовое поле (ручной ввод включен). ID канала или переменная. Если процесс запущен сообщением из WhatsApp, ID канала, в который написал клиент, доступен как {{input.whatsapp.channel_id}}.
Канал другого проекта

Список показывает каналы всей организации, но отправить можно только через канал текущего проекта. Для канала другого проекта нода вернет ошибку Channel does not belong to this project.

Название шаблона и Язык​

Только в режиме ручного ввода. Название шаблона (обязательное) принимает переменные, например order_shipped. Язык -- код языка шаблона, например ru; по умолчанию ru. Переменную в поле «Язык» можно ввести вручную в виде {{...}}.

Шаблон определяется парой «название + язык»: один и тот же шаблон на двух языках -- это два разных шаблона со своими статусами одобрения.

Шаблон​

Обязательное поле, только при выключенном ручном вводе. Пока канал не выбран, поле недоступно: «Сначала выберите канал, чтобы загрузить его шаблоны.»

Каждый вариант списка показан как название (язык) — КАТЕГОРИЯ. Шаблоны, которые сейчас нельзя отправить, видны в списке, но выбрать их нельзя; рядом указан статус Meta и причина отклонения, если она есть. Подсказка «?»: «Шаблоны категории MARKETING тарифицируются при каждой доставке. Варианты, недоступные к отправке, отключены.»

Сообщения поля:

  • «В канале нет шаблонов — синхронизируйте их в интеграции» -- список пуст; кнопка + открывает раздел интеграций.
  • «Шаблон {name} ({language}) не найден в этом канале» -- сохраненного шаблона нет среди синхронизированных.
  • «Шаблон сейчас нельзя отправить — {reason}» -- сохраненный шаблон больше не одобрен (например, приостановлен Meta).

Кому​

Обязательное поле -- номер телефона получателя. Принимает переменные: подсказка «?» -- «Поддерживает переменные {{variable}} — как правило, это результат предыдущей ноды Function.»

Из номера берутся только цифры, поэтому +7 (999) 000-11-22 и 79990001122 -- один и тот же получатель. Указывайте номер в международном формате: 8 999 ... и 7 999 ... -- разные номера. Номер короче 8 цифр отклоняется (invalid_recipient).

Параметры тела​

Значения переменных текста шаблона. Каждое поле принимает переменные {{...}}. Подсказка «?»: «Значения сопоставляются с плейсхолдерами тела шаблона в порядке первого появления — {{1}}, {{2}}, ... для позиционных шаблонов или именованными токенами вроде {{first_name}} для именованных. Количество должно точно совпадать с ожидаемым шаблоном.»

  • При выборе шаблона из списка панель сама создает нужное число строк; введенные значения сохраняются там, где строки остались.
  • Справа от названия поля показано «Шаблон ожидает N». Если строк больше или меньше, появляется предупреждение «Шаблон ожидает {expected}, указано {actual}» -- такая отправка завершится ошибкой parameter_count_mismatch.
  • Если у шаблона нет переменных: «У этого шаблона нет параметров.»
  • Строки добавляются кнопкой Добавить параметр и удаляются кнопкой корзины.

Над строками показан Предпросмотр: сообщение так, как его увидит получатель, с подставленными значениями. Незаполненные переменные выделены. Медиазаголовок показан как надпись «Изображение», «Видео» или «Документ»; кнопки шаблона -- только иллюстрация. Если в шаблоне есть части, которые предпросмотр не умеет показать, под ним написано «В этом шаблоне есть части (например, карусель), которые предпросмотр не показывает.»

При отправке переводы строк и табуляции в значениях заменяются пробелами, а каждое значение обрезается до 900 символов.

Защита от дублей​

Сворачиваемый раздел с двумя полями. Он защищает от повторной отправки того же шаблона тому же получателю -- например, если вы перезапустили рассылку, которая оборвалась на середине.

Ключ дедупликации -- необязательное поле, принимает переменные. Если оставить его пустым, используется ключ по умолчанию, составленный из ID процесса, ID ноды, цифр номера получателя, названия и языка шаблона. В него не входит ID запуска, поэтому повторный запуск того же процесса распознается как повтор. Подсказка «?»: «Повторный запуск рассылки НЕ отправит сообщение получателям, которые уже получили его в пределах окна дедупликации. Оставить поле пустым допустимо — раннер сам выводит стабильный ключ по умолчанию. Чтобы намеренно повторить ту же кампанию, укажите здесь что-то отличающее, например дату или id кампании.»

Свой ключ -- с номером получателя

Ключ проверяется в пределах канала, без учета номера. Если вы задаете свой ключ, включите в него номер получателя (например, spring-sale-2026:{{input.phone}}): ключ без номера после первой отправки заблокирует отправку всем остальным получателям до конца окна -- они получат duplicate: true.

Окно дедупликации (часы) -- сколько часов после успешной отправки повтор с тем же ключом не выполняется. По умолчанию 720 часов (30 дней), минимум 1.

Как ведет себя нода при повторе с тем же ключом в том же канале:

Предыдущая отправкаРезультат
Принята Meta, окно еще не истеклоСообщение не отправляется; нода завершается успешно с duplicate: true и прежним wamid
Принята Meta, но окно истеклоСообщение отправляется снова
Meta отклонила ееСообщение отправляется снова
Еще выполняется (до 5 минут)Ошибка send_in_progress
Начата, но результат не подтвердилсяОшибка send_outcome_unknown: проверьте, получил ли клиент сообщение; чтобы отправить заново, задайте другой ключ дедупликации

Массовая рассылка​

Для рассылки по списку номеров используйте ноду ForEach с операцией WhatsApp-шаблон: каждый элемент массива -- номер получателя, шаблон уходит на каждый номер отдельным сообщением. В панели ForEach задаются канал, шаблон и «Окно защиты от повторов (часы)»; получатель подставляется автоматически ({{_loop_item}}), а полей для параметров тела там нет.

Ключ дедупликации по умолчанию не зависит от порядка номеров в списке, поэтому перезапуск оборвавшейся рассылки отправит сообщения только тем, кто их еще не получил. Ошибка по одному номеру не прерывает цикл: она попадает в errors результата ForEach, а в results на месте этого номера стоит null.

Подключения​

  • Вход: один вход (слева)
  • Выход: один выход output (справа)

Ошибка не останавливает процесс: следующая нода получает объект ошибки. Проверить результат можно нодой If/Else с условием вида node_4.__error, где node_4 -- ID ноды шаблона.

Входные данные​

Результат предыдущей ноды напрямую не используется: номер, параметры и остальные значения попадают в ноду через переменные {{...}} в полях.

Выходные данные​

{
"success": true,
"__success": true,
"__error": false,
"wamid": "wamid.HBgLNzk5OTAwMDExMjI...",
"to": "79990001122",
"templateName": "order_shipped",
"language": "ru",
"category": "UTILITY",
"sessionCreated": true,
"windowWasOpen": false,
"duplicate": false,
"channelId": "wac_..."
}
ПолеОписание
wamidID отправленного сообщения в WhatsApp
toНомер получателя (только цифры)
templateName, languageОтправленный шаблон
categoryКатегория шаблона по данным Meta
sessionCreatedtrue, если диалог с этим номером в канале создан этой отправкой
windowWasOpentrue, если 24-часовое окно с этим клиентом было открыто в момент отправки
duplicatetrue, если сообщение уже было отправлено ранее с тем же ключом и повторно не отправлялось
channelIdID канала

При ошибке:

{
"success": false,
"__success": false,
"__error": true,
"error": "whatsapp-service returned HTTP 409: parameter_count_mismatch: template 'order_shipped' expects 2 parameters, got 1",
"errorType": "APIError",
"status": 409,
"to": "79990001122",
"channelId": "wac_...",
"templateName": "order_shipped",
"wamid": null
}

Типичные ошибки​

Ошибки настройки (errorType: "ConfigurationError") возникают до обращения к WhatsApp:

Текст errorЧто сделать
WhatsApp channel must be selected (set channelId)Выберите канал; если канал задан переменной -- проверьте, что она не пустая
WhatsApp channel id is not validПеременная в поле «Канал» дала недопустимое значение
Recipient number is required (set to)Заполните «Кому»; проверьте, что переменная не пустая
Template name is required (set templateName)Выберите шаблон или заполните «Название шаблона»

Отказы сервиса WhatsApp приходят с errorType: "APIError" и текстом whatsapp-service returned HTTP <код>: ...:

Причина в текстеЧто означает и что сделать
Channel not found (404)Канал удален -- выберите другой
Channel does not belong to this organization / ... this project (403)Канал из другой организации или проекта -- выберите канал текущего проекта
Channel credentials are not valid (409)Токен доступа канала перестал работать -- обновите его в настройках канала
invalid_recipientВ номере меньше 8 цифр
recipient_not_whitelistedНомера нет в белом списке канала
template_not_sendableШаблон не синхронизирован, приостановлен, отключен или отклонен -- синхронизируйте шаблоны и проверьте статус
parameter_count_mismatchЧисло параметров тела не совпадает с шаблоном
too_many_parametersВ шаблоне больше 10 переменных -- такие шаблоны не поддерживаются
template_parameters_outside_bodyПеременные есть не только в тексте, но и в заголовке или кнопках -- такие шаблоны не поддерживаются
template_mixed_parameter_formatВ шаблоне смешаны позиционные ({{1}}) и именованные переменные
send_in_progress, send_outcome_unknownСм. Защита от дублей
Meta refused the send (<код>): ...Meta отклонила сообщение; причина -- в тексте после кода
Meta rejected these credentials: ...Meta не принимает доступы канала -- переподключите канал

Если сервис не ответил за 150 секунд, нода возвращает errorType: "TimeoutError" с текстом WhatsApp template send timed out. Отправка одному получателю может занимать до ~110 секунд: при временных сбоях Meta сервис повторяет попытку.

Проверки на холсте​

Если включен показ предупреждений (настройка холста Предупреждения), на ноде появляется красный значок «!», а при наведении -- список проблем:

  • «Канал WhatsApp не выбран — шаблон не отправится»
  • «Получатель не указан — шаблон не отправится»
  • «Шаблон не выбран — сообщение не отправится»

Проверки не мешают сохранить процесс.

Примеры использования​

Уведомление об отправке заказа​

Ручной ввод:      выключен
Канал: Линия поддержки
Шаблон: order_shipped (ru) — UTILITY
Кому: {{input.phone}}
Параметры тела: {{1}} = {{input.customer_name}}
{{2}} = {{input.order_id}}

После ноды поставьте If/Else с условием node_4.__error и в ветке «Если» сообщите менеджеру об ошибке, например нодой Сообщение в Telegram с текстом Не удалось отправить шаблон на {{node_4.to}}: {{node_4.error}}.

Повторная кампания по тому же списку​

Чтобы намеренно отправить тот же шаблон тем же получателям раньше, чем истечет окно дедупликации, задайте Ключ дедупликации с отличающим значением и номером получателя, например spring-sale-2026:{{input.phone}}. С новым ключом прошлые отправки не учитываются.

Тихий режим

В заголовке панели есть переключатель тихого режима.