Переменные

Как использовать переменные

Давайте разберём, что такое переменные и как эффективно использовать их при создании чат-ботов в MaviBot.

Обратите внимание на следующие системные ограничения для переменных и констант в одном проекте:

Переменные шаблона:

• Максимальное количество: 100 переменных

• Максимальная длина имени: 100 символов

Константы проекта:

• Максимальное количество: 50 констант

• Максимальная длина имени: 100 символов

• Максимальная длина значения: 5 000 символов

Переменная — это именованное место хранения данных, обозначенное уникальной текстовой меткой.

Рис. 1: Переменная с именем total, хранящая сумму платежа.

MaviBot предоставляет несколько типов переменных:

1. Встроенные переменные

2. Системные переменные

3. Переменные, определяемые пользователем — это те, которые вы создаёте самостоятельно в рамках проекта.

Объявить переменную означает присвоить значение именованному контейнеру. Иными словами, выражение вроде a=0 — это объявление переменной a. Мы только что сообщили (объявили) конструктору, что будем хранить число в переменной a, и пока это значение равно 0.

Присвоить значение переменной имеет то же значение.

Выражения "присвоить переменной значение функции" или "установить для переменной значение функции" тоже часто используются. Принцип тот же: вместо конкретного значения вы присваиваете результат функции. Например: s_id = tg_send_message(platform_id, "Привет!") В этом случае результат функции будет сохранён в переменной.

Сбросить переменную означает присвоить ей значение 0.

Функции и методы — это заранее определённые наборы команд, которые настраиваются в MaviBot. Большинство функций требуют параметры — значения, которые функция или метод может понять. Как только бот получает необходимые параметры, он выполняет определённую команду.

tg_send_message(platform_id, "Привет!") — эта функция отправляет сообщение "Привет!" в Telegram.

Рис. 2. Пример переменной text1, присвоенной функции.

ПРАВИЛА РАБОТЫ С ПЕРЕМЕННЫМИ:

1. Имя переменной может начинаться только с буквы; оно не может начинаться с цифры.

   Age1 - ✅ правильно

   1Age - ❌ неправильно

   age1 - ✅ правильно - рекомендуемый вариант

2. Переменная не может содержать пробелы или специальные символы, кроме подчёркивания (_).

   Name_Surname - ✅ правильно

   Name Surname - ❌ неправильно

   nameSurname - ✅ правильно - рекомендуемый вариант

   Ключевые слова из языков программирования нельзя использовать в качестве имён переменных, например: print, true, false, count, sum и так далее.

3. Строго запрещено использовать использовать имена встроенных и системных переменных для пользовательских переменных. Список таких переменных можно найти здесь. ссылка

4. Мы рекомендуем:

   • Используйте латинские (английские) названия для переменных.

   • Используйте короткие, но понятные имена переменных, например: totalSum, pay_name, ns, name_client и т. д.

Как получить значение переменной

Поместите имя переменной в фигурные скобки #{}. Так можно обратиться к её значению в поле текста сообщения. Однако в поле "Калькулятор" следует обращаться к значению переменной просто по имени, без дополнительного синтаксиса.

Текст #{} конструкция позволяет получить значение переменной. Она используется в поле "Текст сообщения", чтобы вставить значение переменной в текст.

Пример:

Система поддерживает вложенные переменные, где значение одной переменной является частью имени другой переменной. Например: #{q#{test#{i}}}

В поле "Калькулятор" обращайтесь к переменным по их именам без использования нотации #{}. Например, если у нас есть две переменные: price (sum) и quantity (num).

num = 10

sum = 1500

Как вывести общую сумму

Введите в калькуляторе следующее:

total_sum = sum1 * num2 ✅ правильно

Как не делать:

total_sum = #{sum1} * #{num2} - ❌ неправильно

Как удалить переменную из бота

Чтобы удалить (очистить) переменную, введите в поле "Калькулятор" одну из следующих конструкций: YourVariableName = или YourVariableName = ""

После знака равенства оставьте пробел или используйте двойные (или одинарные) кавычки.

Обратите внимание! Важно использовать правильный префикс, чтобы указать, к чему относится переменная.

Для переменных уровня проекта (хранятся в настройках проекта) используйте префикс project: Пример: project.YourVariableName = или project.YourVariableName = ""

Для переменных уровня клиента используйте префикс client: Пример: client.YourVariableName = или client.YourVariableName = ""

Для переменных уровня сделки префикс не нужен.

Встроенные переменные

Вот список встроенных переменных:

#{none} - игнорировать сообщение

#{api_key} - API-токен, используемый в запросах к API Salebot

#{attachment_url} - содержит ссылку на вложение

#{attachments} - JSON-массив URL вложений из сообщения пользователя

#{avatar} - ссылка на аватар пользователя (показывается в разделе "Клиенты")

#{client_id} - ID клиента в конструкторе, также используется в API-запросах

#{client_type} - тип мессенджера, из которого пришёл клиент (значения описаны [здесь])

#{current_date} - текущая дата в формате dd.mm.yyyy, основанная на часовом поясе проекта

#{current_time} - текущее время в формате hh:mm, основанное на часовом поясе проекта

#{custom_answer} - ответ, полученный от сервера, указанного в поле "URL ответа сервера"

#{message_from_outside} - тип входящего сообщения. Возможные значения: обычное сообщение = 0 сообщение, отправленное через API = 1 callback-уведомление (жёлтый фон в диалоге) = 3 телефонное уведомление (светло-голубой фон в диалоге) = 5 Эта переменная генерируется с каждым входящим сообщением, но не отображается в карточке клиента. Вы можете использовать её в поле "Переменная для сравнения" для настройки условий для триггеров и связей блоков.

#{date_of_creation} - дата, когда пользователь был добавлен в бота или написал ему впервые

#{full_name} - полное имя пользователя (имя и фамилия)

#{group} - бот, к которому привязан клиент (отображается как "Привязан к боту" в карточке клиента)

#{main_client_id} - ID основного клиента среди группы связанных карточек клиентов

#{message_id} - ID текущего состояния диалога с клиентом (по умолчанию NONE)

#{messenger} - название мессенджера, из которого пришёл клиент

#{name} - имя пользователя

#{next_day} - дата завтрашнего дня в формате dd.mm.yyyy (полезно для планирования сообщений)

#{order_id} - идентификатор заказа (ID клиента и внутренний ID заказа, разделённые дефисом)

#{order} - содержимое заказа, отправленного пользователем

#{platform_id} - ID клиента в платформе для обмена сообщениями

#{question} - сообщение, отправленное пользователем

#{timestamp} - текущая временная метка, включая миллисекунды

#{time_of_creation} - время, когда пользователь был добавлен в бота или написал ему впервые

#{wa_bot} - номер WhatsApp, на который написал пользователь (полезно для передачи в поля CRM и распределения лидов между менеджерами)

#{weekday} - день недели в виде числа (понедельник = 1, вторник = 2 и т. д.)

Значения client_type

Значение	Мессенджер
1	для Telegram
2	для Viber
3	для Facebook
5	для онлайн-чата
10	для Instagram
14	e-mail
16	Telegram Business Account
21	учётная запись Telegram
22	TikTok

Системные переменные

Система автоматически генерирует различные переменные времени выполнения во время работы бота. Вы можете использовать эти переменные при создании бота. Вот список тех, которые могут быть вам полезны.

Дополнительные системные переменные можно найти в документации. Они расположены в разделах, относящихся к их использованию.

phone - номер телефона

notSubscribed - если значение переменной равно 1, клиент отписался от сообщений и не будет получать никаких сообщений

clientBlocked - клиент заблокирован, и бот для него не работает

story_url - идентификатор истории Instagram, на которую ответил клиент

viewed_page - страница, с которой пользователь пишет в онлайн-чате

wa_bot - номер телефона WhatsApp-бота

Чтобы узнать, какие переменные можно создать во время оплаты, обратитесь к руководствам по интеграции платёжных сервисов в разделе "Платёжная система".

Пользовательские переменные

Пользовательские переменные делятся на:

• Переменные проекта (также называемые общими переменными)

• Переменные клиента

• Переменные сделки (также называемые обычными переменными)

• Константы

Ниже будет объяснён каждый тип переменной.

Пожалуйста, избегайте использования одинаковых имён для разных типов переменных, чтобы не возникало путаницы, когда Builder отображает или использует не то значение, которое вы ожидали.

При присвоении значения переменной важно указывать её тип с помощью соответствующего префикса:

client. (для переменных клиента) и project. (для переменных проекта). Для переменных сделки префикс не используется.

Префикс опускается при получении значения переменной.

Пример: Предположим, вы хотите создать переменную проекта с именем like, чтобы использовать её как счётчик лайков от ваших клиентов.

project.like = 0 - объявление, выполняется один раз

В блоке, где нужно считать лайки, напишите: project.like = like + 1

Порядок приоритета переменных: переменные сделки имеют наивысший приоритет, затем идут переменные клиента, затем переменные проекта.

Messenger ID (platform_id)

Messenger ID (platform_id) — это идентификатор пользователя/чата/канала в мессенджере. Чтобы найти его, откройте диалог с нужным клиентом в разделе "Клиенты". Справа в окне чата перейдите на вкладку "О клиенте - Системные переменные" или вкладку "Все" .

Текст platform_id — это постоянная, сгенерированная системой переменная, представляющая уникальный ID пользователя в мессенджере.

• Постоянство: Этот ID остаётся неизменным для пользователя. Даже если вы удалите его запись из конструктора, его platform_id будет таким же при повторной регистрации.

• Источник: ID назначается платформой мессенджера (например, Telegram, WhatsApp), когда пользователь впервые взаимодействует с ботом.

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

Переменная platform_id существует как для обычных пользователей, так и для сообществ, каналов и чатов.

Чтобы получить platform_id (идентификатор мессенджера) Telegram-канала, где бот является администратором, просто отправьте сообщение в канал со своего личного аккаунта. Это автоматически создаст диалог между ботом и каналом.

Вы можете скопировать platform_id значение канала в разделе "О клиенте".

В Telegram идентификатор мессенджера для каналов всегда начинается с минуса (-). При использовании функций обязательно включайте всё значение целиком, включая знак минуса.

Как использовать переменные

Переменные можно использовать в триггерах, заказах, ответах пользователя, блоках и многом другом. Давайте рассмотрим конкретный пример при создании воронки для агентства недвижимости.

Итак, создадим стартовый блок:

Шаг 1: Создайте блок "Спасибо"

Создайте новый блок с сообщением, благодарящим пользователя за его ввод.

Шаг 2: Настройте переход

На соединении, ведущем к этому блоку, настройте следующий триггер:

1. Включите переключатель "Пользователь вводит данные" .

2. Во вкладке в поле "Ввод данных" введите имя переменной: name.

Ввод пользователя сохраняется в переменной Name . Это значение можно повторно использовать в любом последующем блоке, вызывая переменную с помощью #{Name} синтаксиса, например: Добро пожаловать, #{Name}!.

Бот будет работать следующим образом:

Теперь усложним задачу.

В этом же блоке мы спросим пользователя, интересует ли его первичное (новое) или вторичное (вторичное) жильё:

Затем создайте связи от кнопок "Первичное жильё" и "Вторичное жильё" в блоке "Чат".

Теперь давайте посмотрим на второй способ использования переменных внутри блоков.

Выберите нужный блок и введите следующий текст в поле "Калькулятор": client_interest = Первичное жильё. В левом блоке введите: client_interest = Вторичное жильё.

Переменная присваивается пользователю при переходе в любой из этих блоков. Позже мы можем использовать её при создании заказа.

Затем мы спросим клиента о его бюджете на покупку недвижимости в этих блоках и создадим ещё два блока со стрелками, ведущими к ним, на основе триггеров ответа клиента.

Из блока "Какой у вас бюджет?"создайте соединение и задайте условие триггера для сегментации пользователей по их ответу.

1. В настройках соединения включите чекбокс "Пользователь вводит данные".

2. Назначьте имя переменной (например, budget) для хранения ответа клиента.

3. Во вкладке в поле "Переменная" используйте встроенную переменную #{question} (которая содержит последнее сообщение пользователя) для создания условия.

   • Пример: #{question} <= 1000000

Для всех соединений к блокам "Лиды" активируйте "Пользователь вводит данные" и определите переменную.

Вы также можете определить дополнительную переменную прямо в "Лиды" блоке, чтобы предоставить более полную информацию о сделке.

Теперь измените тип двух последних блоков на "Лиды" и посмотрите результат:

Давайте протестируем поток в действии:

Вы можете просмотреть созданную сделку и сохранённые данные клиента, перейдя в «Клиенты» раздел и открыв соответствующий диалог. Там будут видны переменные сделки.

Теперь вы знаете, как использовать переменные как минимум тремя разными способами:

1. Назначать имена переменных данным, введённым пользователем (например, "Имя", "Бюджет")

2. Присваивать значение переменной при переходе в блок (например, client_interest = Первичное жильё)

Как просматривать переменные

Чтобы просмотреть переменные клиента, перейдите в «Клиенты» раздел и откройте его карточку клиента.

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

• Каждая переменная занимает отдельную строку.

• Текст имя переменной показывается слева.

• Её соответствующее value отображается справа.

Чтобы изменить переменную:

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

• Изменить имя переменной.

• Изменить значение переменной.

• Полностью удалить переменную.

Системные переменные нельзя редактировать!

Как задавать переменные клиента

Переменные клиента не удаляются, не сбрасываются и не теряются при использовании блока "Окончание сбора данных" (красный блок).

Переменную клиента можно задать двумя способами: явно и неявно. Явный способ определения переменной — задать её в поле "Калькулятор" одного из блоков воронки.

Пример: client.age = 28 или client.age = 28:

Неявный способ — задать переменную в поле ввода данных стрелки.

Пример:

Создадим блок, где мы спросим имя клиента, а также создадим блок ниже:

Затем перейдите в настройки соединения и включите опцию "Пользователь вводит данные".

Используйте client. префикс при именовании переменной (например, client.name) для сохранения ввода пользователя. Затем на эту переменную можно ссылаться в последующих сообщениях как #{client.name}.

Переменные клиента используются в конструкторе точно так же, как обычные переменные, но без client префикса.

Как задавать переменные проекта

Глобальные переменные не удаляются, не сбрасываются и не теряются при использовании блока "Лиды" (красный блок).

Глобальные переменные доступны всем пользователям бота. Они идеально подходят для управления поведением бота или для взаимодействия между разными пользователями.

Пример использования: Один пользователь может опубликовать товар в канале маркетплейса, установив переменную (например, project.latest_listing), и все остальные пользователи могут его увидеть и ответить.

Синтаксис присваивания

Чтобы создать или обновить глобальную переменную, используйте project. префикс в Калькуляторе:

Примеры:

• project.product_shop = 28

• project.age = 28

Их можно использовать без какого-либо префикса.

Давайте посмотрим, как данные отображаются в таблице.

Теперь запустите блок "Старт" в тестовом режиме.

Мы видим данные, которые были записаны в переменную из таблицы, в сообщении, отправленном ботом. Поскольку мы обратились к переменной в сообщении с помощью #{} синтаксиса, данные, сохранённые в ней, были отображены в чате бота.

Подробнее о том, как работать с функцией get_records_from_table(), рассказано в статье "ИИ-ассистент с таблицей MaviBot".

Текст project. префикс позволил функции записать данные таблицы напрямую в глобальные переменные проекта, доступные в вкладке "Переменные" .

Вы можете редактировать переменные проекта в настройках проекта.

Пример: использование переменных проекта

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

Реализация:

1. Перейдите в Настройки проекта.

2. Создайте новую переменную проекта (например, project.client_counter).

1. Установите её начальное значение (например, 0) что означает "В боте нет клиентов":

В стартовом блоке бота добавьте логику, которая:

1. Увеличивает значение переменной проекта на 1.

2. Присваивает новое значение клиентской переменной для текущего пользователя.

Не забудьте установить ограничение, чтобы счётчик не мог быть увеличен для одного и того же клиента дважды.

Как задавать переменные-константы

Константы — это фиксированные значения, которые остаются неизменными (или меняются очень редко) на протяжении всего жизненного цикла проекта.

Ключевое отличие от глобальных переменных:

В отличие от глобальных переменных, константы зависят от клиента. Если значение константы изменяется, изменение применяется только к сессии этого конкретного клиента.

Типичные варианты использования:

Константы идеально подходят для хранения статических данных, таких как:

• Цены на товары и скидки для клиентов

• Токены интеграций и API-ключи

• Контактная информация продавца или службы поддержки

• Любые другие фиксированные значения конфигурации

Пример: использование переменных-констант

Например, скидка клиента по умолчанию может составлять 10%, но измениться до 25% при вводе промокода.

В "Настройки проекта" → "Константы" введите: Discount : 10

Чтобы ввести промокод, добавьте блок "Триггер", где мы присваиваем переменной discount значение 25.

Отобразите переменную, показывающую размер скидки, в зелёном блоке:

Шаг 1: Настройте автоматический переход Создайте соединение с нулевой задержкой из серого блока. Это обеспечивает немедленное применение скидки и переход клиента к сообщению в стартовом блоке.

Шаг 2: Проверьте поток Теперь отправьте сообщение боту, чтобы запустить и протестировать всю последовательность.

Стандартная скидка без промокода составляет 10%. Однако ввод действующего промокода меняет ситуацию.

Таким образом, после ввода промокода переменная "discount" для этого клиента стала равна 25.

Это произошло потому, что присваивание вроде discount = 25 установило значение для переменной сделки, а не изменило значение константы с тем же именем.

Ключевые переменные сделки

name - название сделки. Термин Name используется для международной версии проекта.

description - описание tdeal. Описание используется в международной версии проекта

budget - сумма сделки (число).

Чтобы редактировать переменные с помощью API-запроса /set_order_vars, вы должны использовать имена из этого руководстваточно так, как они показаны , включая чувствительность к регистру и версию проекта.Ограничения

Максимальная длина имени переменной: 500 символов

Максимальная длина значения переменной: 100 000 символов

Максимальное количество переменных на клиента или сделку: 1 000 символов.

Как правильно работать с переменными

Когда нужно заключать значение переменной в кавычки?

Например,

client_id = 1202020202 client_id = '1202020202' или Оба варианта синтаксиса функционально корректны. Использование кавычек вокруг значения влияет только на его визуальную подсветку в редакторе калькулятора.?

Однако соблюдение единых правил оформления кода повышает читаемость и удобство сопровождения:

Не используйте кавычки

• для числовых значений (например, discount = 25 Используйте кавычки).

• для числовых строковых discount = 25 status = "active").

Каков правильный синтаксис передачи идентификаторов, таких как Client ID, Site ID, Block ID или Certificate ID, функциям — нужно ли заключать их в кавычки?

ID не должен заключаться в кавычки при передаче методу или функции:

Что следует использовать: двойные или одинарные кавычки?

Между использованием одинарных и двойных кавычек нет разницы, но мы рекомендуем использовать двойные кавычки. Так, например, при вставке переменной внутрь строки переменная будет выделяться другим цветом, и её будет легче заметить.

Как следует расставлять пробелы?

Одинаково ли это работает, если между переменной и знаком равенства есть пробел (например, ans="yes", ans = "yes", ans= "yes", ans ="yes"?

Пробелы не влияют на работу методов, переменных или функций. Однако рекомендуется использовать пробелы в коде для повышения читаемости.

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

Подробнее о том, как писать комментарии в Калькуляторе, см. эту статью.

Как сравнивать переменные

Вы можете управлять ходом чат-бота, сравнивая значения переменных. Это позволяет создавать условную логику, например проверять возраст пользователя на соответствие требованиям закона или направлять взаимодействия в зависимости от платформы мессенджера пользователя.

Вот как разделить воронку по разным мессенджерам или по разным аккаунтам одного и того же мессенджера, объясняется здесь.

Поддерживаемые операторы:

"+": сложение "-"': вычитание "*" умножение "/": деление "%'": остаток от деления "^" "**": возведение в степень "и" "И" "&&": логическое И "или" "ИЛИ" "||": логическое ИЛИ

Операторы сравнения: "==" — равно "!=" — не равно ">" — больше чем "<" — меньше чем ">=" — больше или равно "<=" — меньше или равно

ВАЖНО! Чтобы проверить, что встроенный тег переменной (тег запуска бота) отсутствует в карточке клиента, используйте следующий способ сравнения: tag == "NONE"

Переменные следует сравнивать в условии в поле "Переменная" (как в настройках соединения, так и в настройках блока):

Пример сравнения переменной в поле "Переменная" блока-триггера.

Пример сравнения переменной в поле "Переменная" соединения блока.

Как переменные и триггеры работают вместе

Чтобы соединение было активировано, должны выполняться оба триггера:

1. Условие в «Trigger» .

2. Логика сравнения в в поле "Переменная" .

Понимание поля "Переменная"

Если вы вводите только имя переменной (например, client_type) в в поле "Переменная" поле без выражения, система проверяет наличие или истинность значения переменной. Она не не сравнивает его с необработанным вводом пользователя.

Пример: Приведённая ниже настройка проверяет, что клиент из WhatsApp, убеждаясь, что client_type переменная равна 6 (где 6 обозначает WhatsApp).

client_type == 6

Приведённый ниже пример работает точно так же:

Обратите внимание! Нельзя указывать несколько значений для сравнения переменной в поле "Триггер".

Это неправильно!

Если вам нужно сравнить несколько переменных, укажите их значения в поле "Переменная".

Эти варианты правильные.

client_type == 3 переход, если значение переменной равно 3 attachments != None переход, если переменная содержит любое значение attachments == None переход, если переменная не задана product_quantity >= 100 переход, если количество товара больше или равно 100 product_quantity <= 100 переход, если количество товара меньше или равно 100 name == "John" переход, если имя переменной равно John

Чтобы проверить, пуста переменная или нет, используйте выражения: "#{value}" == "" "#{value}" != ""

(где value — это имя переменной).

Результат операции сравнения возвращает логическое значение: True или False.

Максимальная длина выражения: 1000 символов

Значение по умолчанию будет возвращено в результате при попытке сравнить значения разных типов.

"==" - False "<" - False "!=" - True ">=" - False ">" - False "<=" - False

ВАЖНО! Чтобы проверить, что встроенный тег переменной (тег запуска бота) отсутствует в карточке клиента, используйте следующий способ сравнения: tag == "NONE"

Пример: бот, который проверяет возраст пользователя (возраст).

• Если age < 18), отправляет сообщение для несовершеннолетних.

• Если age >= 18), отправляет сообщение для совершеннолетних.

Обратите внимание, что сценарий включает блок без триггера, от которого идут соединения с задержкой.

Этот блок специально создан, чтобы показать, как строить сценарии, в которых бот реагирует не на действия пользователя, а на результаты вычислений. На первом шаге ответ сохраняется в переменную, а затем происходит сравнение. Задержка на стрелках установлена в 0 для мгновенного ответа.

Сравнение "Возраст >= 18" также можно выразить как "больше или равно 18."

Обратите внимание на ошибки в триггерах:

Число не может одновременно быть больше, меньше и равно 18!

Эти триггеры бессмысленны. Любое число либо меньше 18, либо больше 18, либо равно 18.

Важно!

Логические триггеры с переменными должны быть написаны в в поле "Переменная" поле, а не в поле "Триггер"!

Например, на изображении ниже блок сработает, если переменная phone заполнена (то есть не равна None):

Следующий пример показывает, как комбинировать операторы:

Если у клиента есть переменная возраста со значением от 18 до 99, блок сработает. Если переменная отсутствует, либо возраст меньше 18 или больше 99, блок не активируется.

Примечание!

Если вы сравниваете переменную со значением в кавычках, убедитесь, что между кавычками и значением нет пробелов; иначе блок может не сработать или вести себя некорректно!

Правильно (без пробела перед кавычкой или после значения my_new_bot):

Неправильно (с пробелом перед кавычкой):