Змінні

Як використовувати змінні

Давайте розглянемо, що таке змінні та як ефективно використовувати їх під час створення чатботів у MaviBot.

triangle-exclamation

Змінна — це іменоване місце зберігання даних, яке ідентифікується унікальною текстовою міткою.

Рис. 1: Змінна з назвою total, що зберігає суму платежу.

MaviBot надає кілька типів змінних:

  1. Змінні, визначені користувачем — це ті, які ви створюєте самостійно в межах проєкту.

Оголосити змінну означає присвоїти значення іменованому контейнеру. Іншими словами, інструкція на кшталт a=0 є оголошенням змінної a. Ми щойно повідомили (оголосили) конструктору, що зберігатимемо число в змінній a, і наразі це значення дорівнює 0.

Присвоїти значення змінній має те саме значення.

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

Скинути змінну означає присвоїти їй значення 0.

Функції та методи — це заздалегідь визначені набори команд, які налаштовані MaviBot. Більшість функцій потребують параметрів — значень, які функція або метод може зрозуміти. Після того як бот отримує необхідні параметри, він виконує певну команду.

tg_send_message(platform_id, "Hello!") ця функція надсилає повідомлення "Hello!" у 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 тощо.

Як отримати значення змінної

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

triangle-exclamation

Приклад:

circle-check

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

num = 10

sum = 1500

Як показати загальну суму

Введіть у калькуляторі таке:

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

Як не потрібно це робити:

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

Як видалити змінну з бота

Щоб видалити (очистити) змінну, введіть одне з наведених нижче в полі "Калькулятор": YourVariableName = або YourVariableName = ""

Після знака рівності залиште пробіл або використайте подвійні (або одинарні) лапки.

circle-exclamation

Вбудовані змінні

Ось список вбудованих змінних:

#{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} - тип вхідного повідомлення. Можливі значення: regular message = 0 message sent via API = 1 callback notification (жовтий фон у діалозі) = 3 telephony notification (світло-блакитний фон у діалозі) = 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

Системні змінні

Система автоматично генерує різні змінні часу виконання під час роботи бота. Ви можете використовувати ці змінні під час створення свого бота. Ось список тих, які можуть бути вам корисні.

circle-info

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

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

notSubscribed - якщо змінна дорівнює 1, клієнт відписався від повідомлень і не отримуватиме жодних повідомлень

clientBlocked - клієнт заблокований, і бот для нього не працює

story_url - ідентифікатор Instagram-історії, на яку відповів клієнт

viewed_page - сторінка, з якої користувач пише в онлайн-чаті

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

circle-info

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

Користувацькі змінні

Користувацькі змінні поділяються на:

Кожен тип змінної буде пояснено нижче.

circle-info

Будь ласка, уникайте використання однакових назв для різних типів змінних, щоб уникнути плутанини, коли Builder відображає або використовує не те значення, яке ви очікували.

circle-info

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

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

Префікс опускається під час отримання значення змінної.

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

project.like = 0 - оголошення, виконується один раз

У блоці, де потрібно рахувати лайки, напишіть: project.like = like + 1

circle-info

Порядок пріоритету змінних: змінні угоди мають найвищий пріоритет, далі йдуть змінні клієнта, а потім змінні проєкту.

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 месенджера для каналів завжди починається зі знака мінус (-). Під час використання функцій обов'язково вказуйте повне значення, включно зі знаком мінус.

Як використовувати змінні

Змінні можна використовувати в тригерах, замовленнях, відповідях користувачів, блоках та багато де ще. Розгляньмо конкретний приклад під час створення воронки для агентства нерухомості.

Тож давайте створимо блок Start:

Крок 1: Створіть блок "Дякую"

Створіть новий блок із повідомленням подяки користувачу за надану інформацію.

Крок 2: Налаштуйте перехід

На зв'язку, що веде до цього блоку, налаштуйте такий тригер:

  1. Увімкніть перемикач "Користувач вводить дані" .

  2. У У полі "Введені дані" name.

введіть назву змінної: Введені користувачем дані зберігаються в змінній Name {}. Це значення можна повторно використовувати в будь-якому наступному блоці, викликавши змінну за допомогою синтаксису #{Name} наприклад:.

Ласкаво просимо, #{Name}!

Бот працюватиме так:

Тепер зробімо завдання трохи складнішим.

У цьому ж блоці ми запитаємо користувача, чи цікавить його первинне (нове) чи вторинне (вторинне) житло:

Далі створіть зв'язки від кнопок "Первинне житло" та "Вторинне житло" у блоці "Чат".

Тепер розгляньмо другий спосіб використання змінних усередині блоків. Виберіть правий блок і введіть у полі "Калькулятор" такий текст:client_interest = Primary housing . У лівому блоці введіть:.

circle-info

client_interest = Secondary housing

Користувачу присвоюється змінна, коли він переходить до будь-якого з цих блоків. Пізніше ми можемо використати її під час створення замовлення.

Далі ми запитаємо клієнта про його бюджет на придбання нерухомості в цих блоках і створимо ще два блоки зі стрілками, що ведуть до них, на основі тригерів відповіді клієнта. З блоку"Який у вас бюджет?"

  1. створіть зв'язок і встановіть умову тригера, щоб сегментувати користувачів за їхніми відповідями. У налаштуваннях зв'язку увімкніть прапорець для.

  2. "Користувач вводить дані" Призначте назву змінної (наприклад,budget

  3. У ) для збереження відповіді клієнта. У полі #{question} "Змінна"

    • Приклад: використайте вбудовану змінну

circle-exclamation

Ви також можете визначити додаткову змінну безпосередньо в Для всіх зв'язків до блоків блоці, щоб надати більш повну інформацію про угоду.

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

Давайте протестуємо потік у дії:

Ви можете переглянути створену угоду та збережені дані клієнта, перейшовши до "Клієнти" розділу й відкривши відповідну розмову. Змінні угоди будуть там видимі.

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

  1. Призначати імена змінних введеним користувачем даним (наприклад, “Name”, “Budget”)

  2. Призначати значення змінної під час переходу до блоку (наприклад, client_interest = Primary housing)

Як переглядати змінні

Щоб переглянути змінні клієнта, перейдіть до "Клієнти" розділу та відкрийте його картку клієнта.

Змінні відображаються у вигляді списку в картці клієнта:

  • Кожна змінна займає окремий рядок.

  • Поле назва змінної відображається ліворуч.

  • Її відповідне value значення

відображається праворуч.

Щоб змінити змінну:

  • Наведіть курсор на її рядок у списку, щоб відобразити кнопку дії. Натискання на цю кнопку дозволяє:

  • Редагувати назву змінної.

  • Редагувати значення змінної.

circle-info

Повністю видалити змінну.

Системні змінні не можна редагувати!

circle-info

Як налаштувати змінні клієнта

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

Приклад: client.age = 28 або client.age = 28:

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

Приклад:

Давайте створимо блок, у якому ми запитаємо ім'я клієнта, а також створимо блок нижче:

Далі перейдіть до налаштувань зв'язку та увімкніть опцію "Користувач вводить дані".

Використовуйте client. префікс під час називання вашої змінної (наприклад, client.name) для зберігання введених користувачем даних. Потім на цю змінну можна буде посилатися в наступних повідомленнях як #{client.name}.

circle-check

Як налаштувати змінні проєкту

circle-info

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

Глобальні змінні доступні всім користувачам бота. Вони ідеально підходять для керування поведінкою бота або для взаємодії між різними користувачами.

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

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

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

Приклади:

  • project.product_shop = 28

  • project.age = 28

Їх можна використовувати без будь-якого префікса.

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

Тепер виконайте блок "Start" у тестовому режимі.

Ми бачимо дані, які були записані в змінну з таблиці, у повідомленні, надісланому ботом. Оскільки ми посилалися на змінну в повідомленні за допомогою #{} синтаксису, дані, що зберігалися в ній, відобразилися в чаті бота.

circle-info

Докладніше про те, як працювати з функцією get_records_from_table(), пояснюється в статті "AI assistant with MaviBot table".

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

Ви можете редагувати змінні проєкту в налаштуваннях проєкту.

Приклад: використання змінних проєкту

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

Реалізація:

  1. Перейдіть до Налаштування проєкту.

  2. Створіть нову змінну проєкту (наприклад, project.client_counter).

  1. Встановіть її початкове значення (наприклад, 0) що означає "У боті немає клієнтів":

У стартовому блоці бота додайте логіку, яка:

  1. Збільшує значення змінної проєкту на 1.

  2. Присвоює нове значення змінній, специфічній для клієнта, для поточного користувача.

circle-info

Не забудьте встановити обмеження, щоб лічильник не можна було збільшити для одного й того самого клієнта двічі.

Як налаштувати константні змінні

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

Ключова відмінність від глобальних змінних:

На відміну від глобальних змінних, константи є специфічними для клієнта. Якщо значення константи змінено, зміна застосовується лише до сесії цього конкретного клієнта.

Типові варіанти використання:

Константи ідеально підходять для зберігання статичних даних, таких як:

  • Ціни на товари та знижки для клієнтів

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

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

  • Будь-які інші фіксовані значення конфігурації

Приклад: використання константних змінних

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

У "Налаштуваннях проєкту" → "Константи" введіть: Discount : 10

Щоб ввести промокод, додайте блок "Тригер", у якому ми присвоюємо змінній discount значення 25.

Відобразіть змінну, що показує суму знижки, у зеленому блоці:

Крок 1: Налаштуйте автоматичний перехід Створіть зв'язок із таймером на нуль секунд із сірого блоку. Це гарантує, що знижка застосовується одразу, а клієнт переходить до повідомлення в стартовому блоці.

Крок 2: Протестуйте потік Тепер напишіть повідомлення боту, щоб запустити й протестувати всю послідовність.

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

Отже, після введення промокоду змінна "discount" для цього клієнта стала 25.

Так сталося тому, що присвоєння на кшталт discount = 25 встановило значення для змінної угоди, а не змінило значення константи з тією самою назвою.

Ключові змінні угоди

name - назва угоди. Термін Введені користувачем дані зберігаються в змінній використовується для міжнародної версії проєкту.

description - опис угоди. Опис використовується в міжнародній версії проєкту

Призначте назву змінної (наприклад, - сума угоди (число).

Щоб редагувати змінні за допомогою API-запиту /set_order_vars, ви повинні використовувати назви з тцього посібника точно так, як вони показані, включно з регістром літер і версією проєкту.

Обмеження

circle-exclamation

Як правильно працювати зі змінними

Коли потрібно брати значення змінної в лапки?

Наприклад, client_id = 1202020202 або client_id = '1202020202'?

Обидва варіанти синтаксису є функціонально правильними. Використання лапок навколо значення впливає лише на його візуальне підсвічування в редакторі калькулятора.

Однак дотримання послідовних правил кодування покращує читабельність і підтримуваність:

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

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

Який правильний синтаксис для передавання ідентифікаторів, таких як Client ID, Site ID, Block ID або Certificate ID, у функції — чи потрібно брати їх у лапки?

ID не слід брати в лапки під час передавання методу або функції:

Що слід використовувати: подвійні лапки чи одинарні лапки?

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

Як мають бути розставлені пробіли?

Чи працює так само, якщо між змінною та знаком рівності є пробіл (наприклад, ans="yes", ans = "yes", ans= "yes", ans ="yes"?

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

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

circle-check

Як порівнювати змінні

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

Підтримувані оператори:

"+": додавання "-"': віднімання "*" множення "/": ділення "%'": остача від ділення "^" "**": піднесення до степеня "та" "AND" "&&": логічне І "або" "OR" "||": логічне АБО

Оператори порівняння: "==" — дорівнює "!=" — не дорівнює ">" — більше за "<" — менше за ">=" — більше або дорівнює "<=" — менше або дорівнює

circle-exclamation

Змінні слід порівнювати в умові в полі "Змінна" (і в налаштуваннях з'єднання, і в налаштуваннях блоку):

Приклад порівняння змінної в полі "Змінна" тригерного блоку.

Приклад порівняння змінної в полі "Змінна" з'єднання блоку.

Як змінні та тригери працюють разом

Щоб з'єднання було активовано, мають виконуватися обидва тригери:

  1. Умова в "Trigger" .

  2. Логіка порівняння в ) для збереження відповіді клієнта. .

Розуміння поля "Змінна"

Якщо ви вводите лише назву змінної (наприклад, client_type) у ) для збереження відповіді клієнта. полі без виразу, система перевіряє існування або істинність значення змінної. Вона не не порівнює його з необробленим введенням користувача.

Приклад: Наведена нижче конфігурація перевіряє, чи клієнт із WhatsApp, шляхом перевірки того, що client_type змінна дорівнює 6 (де 6 означає WhatsApp).

client_type == 6

Наведений нижче приклад працює так само:

circle-exclamation
circle-info

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

Щоб перевірити, порожня змінна чи ні, використовуйте вирази: "#{value}" == "" "#{value}" != ""

(де value є назвою змінної).

Результат операції порівняння повертає логічне значення: True або False.

circle-exclamation
circle-exclamation
circle-exclamation

Приклад: бот, що перевіряє вік користувача (age).

  • Якщо age < 18, він надсилає повідомлення для неповнолітніх.

  • Якщо age >= 18, він надсилає повідомлення для дорослих.

Зверніть увагу, що потік містить блок без тригера, від якого ведуть таймовані з'єднання.

Цей блок навмисно створено, щоб продемонструвати, як будувати потоки, де бот реагує не на дії користувача, а на результати обчислень. На першому кроці відповідь зберігається в змінну, а потім відбувається порівняння. Затримка на стрілках встановлена на 0 для миттєвої відповіді.

Порівняння "Вік >= 18" також можна виразити як "більше або дорівнює 18".

triangle-exclamation
circle-exclamation

Наприклад, на зображенні нижче блок буде активовано, якщо змінна phone заповнена (тобто не дорівнює None):

Наступний приклад показує, як поєднувати оператори:

Якщо в клієнта є змінна age зі значенням від 18 до 99, блок буде активовано. Якщо змінної немає, або вік менший за 18, або більший за 99, блок не активується.

circle-exclamation

Last updated