Як використовувати модифікатори змінних у чат-ботах

У чат-ботах SendPulse можна використовувати модифікатори для змінних, які перетворюють їх значення за заданими вами правилами. Наприклад, форматувати текст, дати, номери телефонів та URL-адреси.

Розглянемо, які бувають модифікатори та як їх використовувати у чат-ботах.

Синтаксис модифікаторів

Ви можете змінювати дані за допомогою {{ var_name | function(parameter="value") }}, де:

var_name Назва змінної.
function() Функція модифікатора.
parameter Параметр функції.
value Значення параметра.

Ви можете використовувати синтаксис модифікаторів за декількома напрямками: дата, регістр слів, довжина рядків, номер телефону та URL-адреси.

Модифікатори рядків

str_to_lower() Переводить усі символи в нижній регістр.

Наприклад: змінна title = "Назва".

{{ title | str_to_lower() }}
Результат: назва.

str_to_upper() Перекладає всі символи у верхній регістр.

Наприклад: змінна title = "назва".

{{ title | str_to_upper() }}

Результат: НАЗВА.

str_capitalize() Перетворює на рядок з першим великим символом.

Наприклад: змінна title = "моя назва".

{{ title | str_capitalize() }}

Результат: Моя Назва.

str_length() Повертає довжину рядка.

Наприклад: title = "назва".

{{ title | str_length() }}

Результат: 5.

str_limit(limit="100", end="...") Обрізає рядок до вказаної довжини.
  • limit — необов'язковий параметр, що визначає максимальну довжину рядка (за замовчуванням 100 символів).
  • end — необов'язковий параметр, що передає символи в кінці обмеженого рядка (за замовчуванням "...").

Ви можете обмежити кількість символів до 1000 під час надсилання тексту, щоб повідомлення було точно доставлене. Для цього пропишіть {{info | str_limit(limit="1000") }}.

implode(separator="") Об'єднує елементи масиву з допомогою рядка separator.
  • separator — необов'язковий параметр (за замовчуванням порожній рядок. Наприклад: {{ $["list"] | implode(separator=", ") }} виведе через кому дані з масиву, отриманого після запиту зовнішніх даних.
array_get(key="*.keyname")

Створює масив зі значень вказаних ключів масиву об'єктів.

Витягує значення з вкладеного масиву або об'єкта, використовуючи «точкову» нотацію — один зі способів доступу до властивостей об'єкта та значень масиву, де фігурує точка (.) і *, як зріз з масиву та номер елемента в масиві, тобто, може бути така адресація: array.*.object.id.

Наприклад, вам необхідно отримати імена з масиву об'єктів. Тоді можете використовувати {{$["users"] | array_get(key="*.name") | implode(separator="\n") }}, щоб вивести порядково поля name з масиву об'єктів.

{{str|match(pattern="/.*some(regex).*/")}}

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

Наприклад, щоб вивести частину посилання https://calendly.com/d/1n7-w04-ars/my-lesson між «d/» та «/», вкажіть{{link | match(pattern="/.+\/d\/(.+)\/.+/")}}

Результат: 1n7-w04-ars.

{{str|match_all(pattern="/.*(some)\s(regex).*/")}}

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

Наприклад, щоб вивести частину посилання https://calendly.com/d/1n7-w04-ars/my-lesson між «d/» та «/», а потім вибрати перше з отриманих значень, вкажіть {{link|match_all(pattern="/.+\/d\/(.+)\/(.+)/")| array_get(key="0")}}

Результат: 1n7-w04-ars.

{{str| explode(separator="/")}}

Розбиває рядок на масив за роздільником.

Наприклад, щоб розбити рядок https://calendly.com/d/1n7-w04-ars/my-lesson за символом «/» та витягти п'ятий елемент цього масиву, вкажіть {{ link | explode(separator="/")|array_get(key="4")}}

Результат: 1n7-w04-ars.

{{str| substr(start="",length="")}}

Виводить рядок починаючи з вказаного символу та вказаною довжиною.

Наприклад, щоб вивести частину рядка, починаючи з 23-символ та взяти наступні 11 символів, вкажіть {{link | substr(start="23", length="11")}}

Результат: 1n7-w04-ars.

Модифікатори чисел і дат

number_round(precision="0", mode="ROUND_HALF_UP") Округляє число до зазначеної точності precision (кількість цифр після коми).

number_round — округлює до нуля(за замовчуванням 0).

Якщо precision позитивний, число округляється до точності precision цифр після коми.

Якщо precision негативний, число округляється до точності precision цифр перед десятковою комою, тобто до найближчого кратного pow (10, -precision). Наприклад, для precision -1 число округляється до десятків, для precision -2 до сотень.

Можливі значення режиму округлення (mode) можна дізнатися детальніше з документації PHP.

number_format(decimals="0", decimal_separator=".", thousands_separator=",") Форматує число згрупованими тисячами та десятковими цифрами.
  • decimals — встановлює число знаків після коми. Якщо 0, decimal_separator опускається у значенні, що повертається.
  • decimal_separator — встановлює роздільник дробової частини.
  • thousands_separator — встановлює роздільник тисяч.

Наприклад, щоб великі числа сприймалися легше, можна розділити комами тисячі. Для цього пропишіть number_format(thousands_separator=",")

date(from_format="d.m.Y", format="d.m.Y", modify="") Форматує рядок з датою згідно з переданим форматом.
  • from_format — необов'язковий параметр, вказує з якого формату конвертувати дані дати. (за замовчуванням: 'd.m.Y').
  • format — необов'язковий параметр, вказує, в який формат перетворювати дані дати (за замовчуванням: 'd.m.Y').
  • modify — необов'язковий параметр, що модифікує саму дату, наприклад, "+1 day" додасть один день від початкової дати.

Підтримуються лише такі модифікатори: +/-day(s), +/-month(s), +/-year(s).

Детальніше про модифікатори дат читайте в документації PHP.

Наприклад, якщо ви хочете отримати дату у форматі «назва місяця та число», можете вказати {{ signup_date | date(format ="F jS")}}

Результат: January 5th.

date_time(from_format="d.m.Y H:i", format="d.m.Y H:i", modify="") Повертає під час виведення значення з типом date_time.
  • from_format — необов'язковий параметр, вказує з якого формату конвертувати дані дати та часу. (за замовчуванням: 'd.m.Y H:i').
  • format — необов'язковий параметр, вказує, в який формат перетворювати дані дати та часу (за замовчуванням: 'd.m.Y H:i').
  • modify — необов'язковий параметр, що модифікує дату і час, наприклад, "+1 hour" додасть одну годину від початкового часу.

Підтримуються модифікатори: +/-minute(s), +/-hour(s), +/-day(s), +/-month(s), +/-year(s).

Інші модифікатори

phone(formig-fix-handle_api_exceptionat="INTERNATIONAL") Форматує рядок із номером телефону згідно з переданим форматом.
  • format — необов'язковий параметр, вказує, який формат перетворювати номер телефону (за замовчуванням INTERNATIONAL).

Можливі варіанти формату:

  • INTERNATIONAL (+380 63 333 333 33)
  • NATIONAL (063 333 3333)
  • E164 (+380633333333)
  • RFC3966 (tel:+380-63-33-3333)
urlencode Повертає строку, де всі не цифро-буквені символи крім -_. повинні бути замінені знаком відсотка (%), за яким слідує два шістнадцяткових числа, а пробіли закодовані як знак додавання (+). Рядок кодується тим же способом, що й POST-дані веб-форми, тобто за типом контенту application/x-www-form-urlencoded.

Модифікатор можна використовувати для передачі отриманих від підписника значень далі в запит API, наприклад, як get-параметр.

Особливості використання

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

В елементі «Повідомлення» блоку ланцюжка або кампанії, а також у всіх інших елементах, де можна вставляти та використовувати змінні, ви можете застосовувати до них модифікатори. Найчастіше змінні отримують через функцію «Введення користувацьких змінних» або з відповіді елемента «Запит API».

Під час виклику функції модифікатора, якщо вона не приймає параметри, можна упускати дужки "()".

Якщо ім'я змінної містить символи }} та | , то вони повинні екрануватися \}\} та \| в імені.

Якщо значення параметра містить символи }}, | і " , то вони повинні екрануватися \}\}, \| і \". Значення параметра завжди задається як рядок.

Можливі помилки

Якщо модифікатор не може обробити змінну, він повертає її в такому ж вигляді, як і була до застосування модифікатора. Наприклад, якщо до змінної ім'я = 'Ivan' застосувати модифікатор {{ ім'я|phone(format="INTERNATIONAL") }}, ми отримаємо відповідь «Ivan», оскільки змінна не є телефоном.

Якщо модифікатор не можна застосувати до змінної, користувач не побачить помилку.

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

Комбінування модифікаторів

Ви можете комбінувати декілька модифікаторів, наприклад:

{{variable_name|modifier_name1(parameter_name1="value",parameter_name2="value",parameter_name3="value",)|modifier_name2()|modifier_name_N()}}
{{ім'я_змінної|ім'я_модифікатора1(ім'я_параметра1="значення", ім'я_параметра2="значення"ім'япараметра3="значення",)ім'я_модіфікатора2())

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

{{variable_name|modifier_name1(parameter_name1="value",parameter_name2="value",parameter_name3="value",)|modifier_name2()|modifier_name_N()}}
{{ String | str_limit(limit="10") | str_to_upper }}

Як використовувати модифікатори в конструкторі чат-ботів

Ви можете використовувати модифікатори у таких блоках:

Блок «Повідомлення» У текстовому блоці — для надсилання модифікованого повідомлення.
Блок «Запит API» У полі посилання або тіла запиту — для надсилання модифікованого запиту.
Блок «Дія» У полі встановлення значення змінної у дії «Встановити змінну» — для збереження модифікованої змінної.

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

Приклад форматування імені підписника

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

Для цього зайдіть або створіть ланцюжок, додайте елемент «Повідомлення» і напишіть текст із запитом, які дані хочете отримати від підписника. У панелі редагування активуйте «Чекати на відповідь підписника». У полі «Валідувати як» виберіть «Рядок» і виберіть змінну.

Натисніть «Застосувати» та додайте наступний елемент «Повідомлення».

Підписник може ввести ім'я з маленької літери, але хочемо звертатися до нього правильно, тому в тексті використовуємо модифікатор змінної str_title().

Ось як це виглядає у підписника.

Приклад форматування дати

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

Додайте елемент «Повідомлення», введіть текст із запитом, які дані хочете отримати від підписника. У панелі редагування активуйте «Чекати на відповідь підписника». У полі «Валідувати як» виберіть «Дата» і виберіть змінну.

Натисніть «Застосувати» та додайте наступний елемент «Повідомлення».

Ми хочемо, щоб дата бронювання завжди відображалася в одному форматі, тому додаємо модифікатор {{ order_date | date(format ="d.m.Y") }}.

Ось яка відповідь прийде користувачеві, коли вибере дату.

Приклад створення посилання в Google Календарі

Якщо ви хочете запропонувати користувачеві запланувати подію у календарі, можна додати доступні часові слоти за допомогою кнопок або швидких відповідей, або запропонувати ввести власні дату та час в елементі «Повідомлення» (Message).

Збережіть отримане значення змінної типу «Дата та час» (Date and time).

Тепер, щоб отримати посилання на створення зустрічі в Google Календарі, задайте в елементі рядок:

 https://www.google.com/calendar/render?action=TEMPLATE&text={{title|urlencode()}}&dates={{booked_datetime|date_time(format="YmdTHi00", modify="-2 hours")}}Z%2F{{booked_datetime|date_time(format="YmdTHi00", modify="-1 hours")}}Z&ctz=Europe%2FKyiv

Де title — мінна з аудиторії чат-бота для назви зустрічі.

booked_datetime — змінна для обраної дати та часу початку зустрічі.

Ymd — рік, місяць і день, зазначені без пробілів.

Т — Статичний роздільник дати та часу.

Hi — Годинник і хвилини без пробілів.

00 — Статично задані секунди.

Перша дата та час – час старту зустрічі з поправкою на часовий пояс (-2 години для київського часу). Друга дата - закінчення через годину.

Z — покажчик дати у часовому поясі UTC.

ctz=Europe%2FKyiv — покажчик часового поясу, у якому створюється подія.

Припустимо, користувач вкаже дату і час: «28.02.2023 11:00».

У такому разі чат-бот сформує посилання виду:

 https://www.google.com/calendar/render?action=TEMPLATE&text=%D0%9F%D1%80%D0%B5%D0%B7%D0%B5%D0%BD%D1%82%D0%B0%D1%86%D0%B8%D1%8F+%C2%ABUnidragon%C2%BB&dates=20230228T090000WITH%2F20230228T100000Z&ctz=Europe%2FKyiv

І відобразить як частину повідомлення.

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

    Оцініть, наскільки стаття була корисною "Як використовувати модифікатори змінних у чат-ботах"

    Оцінка: 4 / 5

    Назад

    Як перенести ланцюжок чат-бота з одного месенджера в інший

    Далі

    Як використовувати регулярні вирази в чат-ботах

    Спробуйте бота для розсилок в Facebook Messenger безкоштовно