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

Давайте разберемся, что такое переменные и как эффективно их использовать при создании чат-ботов в 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.

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

  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 (сумма) и quantity (количество).

num = 10

sum = 1500

Как отобразить итоговую сумму

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

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

Как не нужно делать:

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

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

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

ИмяВашейПеременной =

или

ИмяВашейПеременной = ""

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

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

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

Пример:
project.ИмяВашейПеременной =
или
project.ИмяВашейПеременной = ""

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

Пример:
client.ИмяВашейПеременной = или
client.ИмяВашейПеременной = ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Значения client_type

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ID мессенджера (platform_id)

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

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

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

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

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

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

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

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

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

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

Итак, создадим блок "Старт":

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

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

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

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

  1. Включите переключатель "Пользователь вводит данные".
  2. В поле "Входные данные" введите имя переменной: name.

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

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

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

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

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

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

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

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

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

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

  1. В настройках соединения установите флажок "Пользователь вводит данные".
  2. Присвойте имя переменной (например, budget) для хранения ответа клиента.
  3. В поле "Переменная" используйте встроенную переменную #{question} (которая содержит последнее сообщение пользователя), чтобы создать условие.
    • Пример: #{question} <= 1000000

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

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

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

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

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

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

  1. Присваивать имена переменных вводимым пользователем данным (например, "Имя", "Бюджет")
  2. Присваивать значение переменной при переходе в блок (например, client_interest = Первичное жилье)

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

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

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

  • Каждая переменная занимает отдельную строку.
  • Имя переменной отображается слева.
  • Соответствующее значение отображается справа.

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

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

  • Редактировать имя переменной.
  • Редактировать значение переменной.
  • Полностью удалить переменную.

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

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

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

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

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

Пример: 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(), объясняется в статье "AI-ассистент с таблицей MaviBot".

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

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

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

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

Реализация:

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

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

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

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

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

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

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

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

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

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

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

  • Цены на товары и скидки для клиентов
  • Токены интеграции и API-ключи
  • Контактная информация продавца или службы поддержки
  • Любые другие фиксированные значения конфигурации

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Лимиты

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

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

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

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

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

Например, client_id = 1202020202 или client_id = '1202020202'?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

tag == "NONE"

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

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

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

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

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

  1. Условие в поле "Триггер".
  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" переход, если переменная name равна John

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

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

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

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

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

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

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

tag == "NONE"

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

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

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

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

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

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

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

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

Важно!

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

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

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

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

Примечание!

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

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

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