WhatsApp-шаблон
Нода WhatsApp-шаблон отправляет одно одобренное Meta шаблонное сообщение на один номер через подключенный канал WhatsApp. В палитре нода находится в разделе Интеграции; на холсте новая нода называется «Шаблон WhatsApp».
Чтобы ответить клиенту, который сам написал в WhatsApp, используйте ноду Ответ в WhatsApp.
Назначение
- Уведомление клиента, который вам не писал или писал больше 24 часов назад: статус заказа, напоминание о записи, готовый документ.
- Массовая рассылка по списку номеров -- через операцию «WhatsApp-шаблон» в ноде ForEach, см. Массовая рассылка.
- Повторный контакт с клиентом после закрытия 24-часового окна.
Шаблоны и 24-часовое окно
WhatsApp разрешает отправлять обычные сообщения (свободный текст, изображения) только в течение 24 часов после последнего сообщения клиента. Вне этого окна, а также если клиент вам еще не писал, Meta принимает только шаблоны -- сообщения, заранее созданные и одобренные Meta. Текст шаблона фиксируется при одобрении; изменить можно только значения его переменных.
Эта нода всегда отправляет шаблон, поэтому работает независимо от окна. Было ли окно открыто в момент отправки, показывает поле windowWasOpen результата.
Доставку шаблонов тарифицирует Meta: стоимость зависит от категории шаблона и страны получателя. Шаблоны категории MARKETING тарифицируются при каждой доставке. Категория отправленного шаблона возвращается в поле category.
Перед началом
- Подключите номер WhatsApp. Раздел Интеграции → вкладка WhatsApp → Подключить номер. В поле Проект канала укажите проект, в котором находится процесс: нода отправляет только через каналы своего проекта.
- Создайте шаблон в WhatsApp Manager и дождитесь одобрения: модерация Meta занимает до 24 часов.
- Синхронизируйте шаблоны. Раздел Интеграции → 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_..."
}
| Поле | Описание |
|---|---|
wamid | ID отправленного сообщения в WhatsApp |
to | Номер получателя (только цифры) |
templateName, language | Отправленный шаблон |
category | Категория шаблона по данным Meta |
sessionCreated | true, если диалог с этим номером в канале создан этой отправкой |
windowWasOpen | true, если 24-часовое окно с этим клиентом было открыто в момент отправки |
duplicate | true, если сообщение уже было отправлено ранее с тем же ключом и повторно не отправлялось |
channelId | ID канала |
При ошибке:
{
"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}}. С новым ключом прошлые отправки не учитываются.
В заголовке панели есть переключатель тихого режима.