Код на JavaScript в сценарии
Как посчитать, преобразовать данные, разобрать ответ внешней системы или собрать текст несколькими строками JavaScript и записать результат в переменные сценария.
Блок «Код на JavaScript» нужен там, где обычных блоков не хватает: посчитать скидку по формуле, выбрать нужное из ответа внешней системы, привести телефон к одному виду, собрать фразу со склонением. Код получает данные запуска, возвращает результат, и этот результат попадает в переменные, которые дальше работают в условиях, текстах и других блоках, как любые {{vars.…}}.
Где найти блок
- Откройте сценарий в разделе «Автоматизация» и перейдите в редактор.
- В библиотеке блоков откройте группу «Операции» и перетащите на холст блок «Код на JavaScript».
- В панели блока заполните поле «Код», добавьте «Переменные результата» и при желании «Описание»: оно видно на карточке блока на холсте.
- Нажмите «Проверить» в разделе «Проверить на образце», убедитесь, что результат тот, что нужен, и подключите выходы блока.
У блока два выхода: «Дальше» (код выполнился, переменные записаны) и «Ошибка» (синтаксис, исключение в коде, превышено время или память, среда выполнения недоступна).
Как писать код
Пишите тело функции, а не программу целиком: код выполняется как функция с одним аргументом input в строгом режиме ("use strict"). Результат возвращайте через return. Объявлять функцию, экспортировать или подключать модули не нужно.
В коде не работают подстановки {{…}}: код передаётся как есть. Данные берите из объекта input. Кнопка «Вставить переменную» в редакторе вставляет как раз путь в input, например input.vars.amount, а не {{vars.amount}}.
Что лежит в input
| Поле | Что внутри |
|---|---|
input.vars | Переменные запуска, то же, что {{vars.…}}: значения из блоков выше, ответы клиента, поля ответа внешней системы. |
input.trigger | Данные события, которое запустило сценарий, то же, что {{trigger.…}}. Для запуска по вебхуку тело заявки лежит в input.trigger.body. |
input.contact | Контакт запуска: id, name, phone, email, tags (список), custom (свои поля контакта). |
input.conversation | custom: свои поля диалога. |
input.const | Константы компании, то же, что {{const.…}}. |
input.company | id и timezone (часовой пояс компании). |
input.run | id запуска и is_test: true в пробном прогоне и при проверке на образце. |
В input только те данные, что и так доступны в подстановках сценария, ничего сверх этого. Пустые разделы приходят пустым объектом {}, поэтому input.vars.x можно читать всегда, без проверки на undefined у самого input.vars. Переменные и константы часто хранятся строкой: перед арифметикой приводите их к числу через Number(…). Если данных на входе больше 512 КБ, сначала отбрасывается тело вебхука, затем константы; если и этого мало, шаг уходит в «Ошибка».
Что вернуть и куда это запишется
В «Переменных результата» перечислите имена переменных, в которые код может писать: от 1 до 20, имя начинается с латинской буквы или _, дальше буквы, цифры и _, до 64 символов. Код пишет только в эти переменные, остальные переменные запуска он не трогает.
- Вернули объект. Каждая объявленная переменная получает значение ключа с тем же именем. Если ключа нет или он равен
null, переменная очищается. Ключи, которых нет в списке, пропускаются. - Вернули строку, число, `true`/`false` или список, а переменная одна. Значение целиком записывается в эту переменную.
- Вернули не объект, а переменных несколько. Шаг уходит в «Ошибка» с причиной «Нужен объект с ключами переменных».
- Вернули `null` или ничего не вернули. Все объявленные переменные очищаются. Забытый
returnтоже очищает их, проверка на образце это покажет.
Числа и логические значения сохраняют тип, вложенные объекты и списки сохраняются как структура. Длинная строка обрезается до размера одной переменной (8 КБ). В одном запуске не больше 50 переменных: если место кончилось, шаг уходит в «Ошибка», а часть переменных к этому моменту уже может быть записана. Ниже по сценарию результат берётся как обычно: {{vars.total}}.
Через await можно дождаться уже готового значения, но таймеров и сети в блоке нет: промис, который так и не завершится, даёт ошибку «Промис не завершился». Считайте синхронно.
Примеры
Скидка по формуле
Сумма заказа в переменной amount, процент скидки в константе компании discount_percent. Переменные результата: discount и total. Дальше в сообщении: «Ваша сумма со скидкой: {{vars.total}}».
const amount = Number(input.vars.amount) || 0;
const percent = Number(input.const.discount_percent) || 0;
const discount = Math.round(amount * percent / 100);
return { discount: discount, total: amount - discount };Разбор ответа внешней системы
Блок «Отправить вебхук» сохранил список товаров из ответа в переменную items. Код оставляет только товары в наличии, считает их и берёт название первого. Если в наличии ничего нет, first_title очищается (null). Дальше блок «Если / иначе» ветвит сценарий по available_count.
let items = input.vars.items;
if (typeof items === 'string') {
items = JSON.parse(items || '[]');
}
if (!Array.isArray(items)) {
items = [];
}
const available = items.filter((item) => item && item.in_stock);
console.log('items:', items.length, 'in stock:', available.length);
return {
available_count: available.length,
first_title: available.length > 0 ? available[0].title : null,
};Телефон в одном формате
Одна переменная результата phone_e164, поэтому код возвращает строку, а не объект. Если цифр слишком мало, переменная очищается.
const digits = String(input.contact.phone || '').replace(/\D/g, '');
return digits.length >= 10 ? '+' + digits : null;Текст со склонением
Собираем фразу «Анна, у вас 3 бонуса» с правильным окончанием и подставляем её в сообщение как {{vars.greeting}}.
const name = String(input.contact.name || '').trim().split(' ')[0] || 'Здравствуйте';
const count = Number(input.vars.bonus) || 0;
const mod10 = count % 10;
const mod100 = count % 100;
let word = 'бонусов';
if (mod10 === 1 && mod100 !== 11) {
word = 'бонус';
} else if (mod10 >= 2 && mod10 <= 4 && (mod100 < 12 || mod100 > 14)) {
word = 'бонуса';
}
return name + ', у вас ' + count + ' ' + word;Проверка на образце
В панели блока есть раздел «Проверить на образце». Поле «Образец input (JSON)» заранее заполнено переменными из блоков выше и ключами вебхука: поменяйте значения, чтобы проверить разные случаи, например пустой список или отсутствующее поле. Образец задаёт vars, trigger и contact; константы берутся настоящие, свои поля диалога в проверке пустые, input.run.is_test равен true. Образец до 64 КБ.
После нажатия «Проверить» код выполняется в той же среде и с теми же лимитами, что и в настоящем запуске. Панель показывает:
- «Результат»: что вернул код (длинный результат показывается не целиком);
- «Журнал»: строки, выведенные через
console.log; - «Что запишется»: для каждой переменной «запишется», «очистится» или «не объявлена» (ключ есть в результате, но не в списке переменных);
- при ошибке: её текст и подсвеченную строку кода. В сценарии такой шаг пошёл бы по выходу «Ошибка».
Проверка ничего не записывает и не запускает сценарий, образец не сохраняется. Проверок не больше 20 в минуту на сотрудника (и 60 в минуту на компанию). Если среда выполнения занята или недоступна, проверку можно повторить через несколько секунд, на сохранение блока это не влияет. Блок также выполняется в пробном прогоне сценария: он пишет только переменные запуска, поэтому ничего за пределами прогона не меняет.
Ограничения и лимиты
Доступен стандартный JavaScript: объекты и списки, строки, регулярные выражения, Math, JSON, Date. Каждый вызов блока выполняется в новой чистой среде: значения из прошлых запусков и других блоков в ней не остаются, обмен идёт только через input и переменные.
| Чего нет | Что делать |
|---|---|
Сети: fetch, запросов к сайтам и API | Сделайте запрос блоком «Отправить вебхук», сохраните ответ в переменную и разберите её кодом. |
Таймеров: setTimeout, setInterval | Для паузы используйте блок ожидания в сценарии. |
Модулей и библиотек: require, import | Пишите нужные функции прямо в коде блока. |
| Файлов, окружения и процесса | Нужные данные передавайте через переменные и константы. |
Intl и форматирования под язык | Форматируйте числа и даты вручную. Время в коде идёт по UTC; часовой пояс компании есть в input.company.timezone. |
| Лимит | Значение |
|---|---|
| Размер кода | 16 384 байт (16 КБ). Кириллица занимает 2 байта на символ. |
| Время выполнения | Около 1 секунды процессорного времени на вызов, затем код останавливается. |
| Память | Ограничена несколькими десятками мегабайт: хватает на обычные объекты и списки, но не на огромные массивы и строки, собранные в цикле. |
| Данные на входе | До 512 КБ (см. выше, что отбрасывается при превышении). |
| Результат | До 64 КБ в виде JSON. |
| Журнал | До 20 строк по 200 символов, остальное обрезается. |
| Переменные результата | От 1 до 20 на блок. |
| Один запуск сценария | Не больше 50 вызовов блоков кода и около 3 секунд процессорного времени на все такие блоки вместе. Это защита от зацикленных сценариев. |
Ветка «Ошибка»
На ветку «Ошибка» обычно ставят уведомление ответственному, внутреннюю заметку или безопасный вариант по умолчанию. Если среда выполнения временно недоступна или перегружена, шаг не падает сразу: он ждёт и повторяется автоматически (через 5, 20 и 60 секунд, в журнале запуска виден статус «Ждём среду выполнения кода»), и только после последней неудачной попытки идёт по выходу «Ошибка». В пробном прогоне повторов нет, шаг сразу уходит в «Ошибка».
Ошибки и что они значат
Причина ошибки видна в журнале запуска сценария (и при проверке на образце). Код причины в скобках приходит в API в поле reason шага.
| Ошибка | Что значит и что делать |
|---|---|
Синтаксическая ошибка в коде (syntax_error) | Незакрытая скобка, кавычка или опечатка. Нажмите «Проверить» и исправьте подсвеченную строку. |
Ошибка при выполнении кода (script_error) | Код бросил исключение, например обратился к полю пустого значения. Добавьте проверку на пустое значение. |
Код не уложился во время (timeout) | Обычно бесконечный цикл или перебор очень большого списка. |
Коду не хватило памяти (memory_limit) | Не собирайте большие массивы и строки в цикле. |
Слишком глубокая рекурсия (stack_overflow) | Замените рекурсию циклом или ограничьте глубину. |
Результат слишком большой (output_too_large) | Код вернул больше 64 КБ. Верните только нужные поля. |
Результат нельзя сохранить (result_not_serializable) | Вернули функцию, циклическую ссылку, BigInt или слишком вложенный объект. Верните обычный объект, строку или число. |
Промис не завершился (unresolved_promise) | Таймеров и сети нет, считайте синхронно. |
Нужен объект с ключами переменных (result_not_object) | Переменных несколько, а код вернул не объект. Верните { имя: значение } или оставьте одну переменную. |
Не хватило места для переменных (variable_limit) | В запуске кончился лимит переменных. Часть переменных могла уже записаться. |
Слишком много данных на входе (input_too_large), не удалось передать данные коду (input_invalid) | Уменьшите объём данных вебхука и переменных или проверьте их значения. |
Блок настроен с ошибкой (code_invalid_config) | Код пустой или слишком длинный либо список переменных неверный. Откройте блок и исправьте. |
Лимит кода на запуск исчерпан (budget_exhausted) | Блоки кода в одном запуске вызывались слишком часто или работали слишком долго. Проверьте, не зациклен ли сценарий. |
Среда выполнения кода недоступна или перегружена (sandbox_unavailable, sandbox_busy) | Сбой или нагрузка на нашей стороне, код менять не нужно. Появляется после всех повторных попыток. |
Блок кода отключён (feature_disabled) | Выполнение кода выключено для компании или платформы. Блок можно сохранить, но шаг идёт по выходу «Ошибка». |
Внутренняя ошибка (internal_error) и другие ошибки платформы | Сбой на нашей стороне. Если повторяется, напишите в поддержку. |
Журнал console.log
Внутри кода работают console.log, console.info, console.warn и console.error. Объекты выводятся как JSON. Сохраняются первые 20 строк по 200 символов. Журнал виден при проверке на образце и в журнале запуска сценария рядом с причиной ошибки и строкой, в которой она случилась.
Кто может работать с блоком
- Добавлять блок, писать код и проверять его на образце может сотрудник с правом «Автоматизация» → «Изменение» (
automation.update). Отдельного права для кода нет: блок видит те же данные, что и подстановки{{…}}. - Журнал скрипта, текст ошибки и детали шага в журнале запуска видят только роли с правом «Автоматизация» → «Персональные данные в журнале»: в них могут быть данные клиента. Без этого права сведения шага скрыты целиком.
- Код виден всем, кто может редактировать сценарии. Не пишите в коде пароли и ключи: у кода всё равно нет доступа к сети.
Приватность
Код и данные, которые он обрабатывает, не пишутся в журналы платформы: среда выполнения хранит только служебные сведения (отпечаток кода, время выполнения), без самого кода, входных данных и результата. В журнале запуска шага остаются имена записанных и очищенных переменных, число пропущенных ключей, время, причина ошибки и строки console.log; значения input и результата там не сохраняются. Образец из проверки нигде не хранится. Строки журнала вы формируете сами, поэтому не выводите через console.log персональные данные без необходимости.
Для разработчиков
Проверка на образце доступна через API: POST /v1/automations/code/check с телом code, variables и sample. Описание полей, ответа и лимитов: справочник REST, группа «Автоматизации». Связанные статьи: Автоматизации: типовые сценарии без программиста, Переменные, константы и кнопки в сценариях, CRM-блоки в сценариях.