Робота з клієнтами

ЛЕГЕНДА:

was_in_state() | days_from_last_message() | free_client() | assign_to_user() | distribute_client()| get_operator() | get_operator_name() | delete_pended_messages() | set_note() | add_unread() | clear_unread() | unsubscribe()|block_client() | unblock_client() | set_client_name() | get_bind_clients() | get_current_pipline_id()

was_in_state(message_id)
перевіряє, чи був клієнт у вибраному стані (блоці). Номер блоку можна отримати з редактора.

days_from_last_message()
визначає кількість днів з моменту останнього повідомлення клієнта. Створено для перевірки, чи потрапляє він у 24-годинне вікно.

Приклад:
d = days_from_last_message()

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


free***_***client()
знімає призначення відповідального оператора.
Приклад: free_client()

assign_to_user(email, only_active)
призначає діалог оператору, де:

  1. email - рядковий параметр (необов'язковий). Якщо вказано лише email, діалог буде призначено вказаному оператору незалежно від його поточного статусу.
  2. only_active - True або False (необов'язковий параметр). Якщо встановлено True, діалог буде призначено вказаному оператору лише якщо він зараз на зміні.

Приклади:

assign_to_user() - призначає діалог випадковому оператору, який зараз на зміні

assign_to_user('email оператора') - призначає діалог оператору незалежно від його статусу

assign_to_user('email оператора', True) - призначає діалог вказаному оператору лише якщо він зараз на зміні

distribute_client()
призначає діалог оператору відповідно до налаштувань авторозподілу.
Приклад: distribute_client()

get_operator()
отримує email відповідального оператора

Приклад: get_operator()

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

get_operator_name()
отримує ім'я відповідального оператора

Приклад: get_operator_name()

Може використовуватися для відображення інформації клієнту. Якщо відповідального оператора немає, поверне None. Якщо оператору не призначено ім'я, поверне його email.

delete_pended_messages()
видаляє всі заплановані повідомлення для поточного клієнта. За замовчуванням також видаляє повідомлення, створені стрілками "Не скасовувати". Щоб зберегти повідомлення від стрілок "Не скасовувати", передайте параметр False: delete_pended_messages(False).

set_note(comment)
додає коментар до діалогу.

Приклад: set_note('Переробити')

add_unread(count)
позначає діалог з клієнтом як непрочитаний

Параметр count можна опустити або встановити на 1; у цьому випадку в діалозі з клієнтом з'явиться індикатор +1 непрочитане повідомлення.

Якщо передано будь-яке інше число, воно буде відображатися в розділі "Клієнти" як кількість непрочитаних повідомлень від клієнта.

clear_unread()
позначає діалог як прочитаний

unsubscribe()
Функція для відписки від повідомлень бота. Приклад наведено у цій статті.
Для відписаного клієнта з'явиться символ — червоне повідомлення з хрестиком.

Важливо!

Спочатку виконується Калькулятор, і лише потім надсилається повідомлення.

Тому, якщо вам потрібно надіслати фінальне повідомлення на кшталт "Ви відписалися від бота" або "Вас заблоковано", необхідно використовувати двоетапний процес:

  1. Спочатку надішліть блок з фінальним повідомленням.
  2. Потім надішліть порожній блок з функцією відписки/блокування.

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

Якщо ви розмістите функцію unsubscribe() у калькуляторі того ж блоку, що й ваше повідомлення, повідомлення не буде надіслано, і система покаже помилку.

block_client()
блокує клієнту можливість надсилати повідомлення боту. Раніше заплановані повідомлення від бота також буде скасовано. Однак, все ще можна буде надсилати повідомлення клієнту безпосередньо з діалогу в розділі "Клієнти"

Заблокований клієнт матиме позначку — червоний значок замка.

unblock_client()
розблоковує клієнта. Клієнт зможе знову взаємодіяти з ботом і проходити ланцюжки повідомлень.

set_client_name(name)
змінює ім'я клієнта. Передайте ім'я клієнта як рядок у подвійних лапках. Також можна використовувати змінну, що містить ім'я клієнта, наприклад: set_client_name("Іван Петренко")

get_bind_clients()
функція без параметрів, яка повертає масив ідентифікаторів клієнтів, прив'язаних до поточного клієнта.

get_current_pipline_id()
функція без параметрів, яка повертає ID вирви, в якій зараз знаходиться клієнт.

Якщо угода клієнта знаходиться на стадії "необроблено", повертає None.

Робота із завданнями

Функції, що працюють із завданнями, повертають статус операції як True або ID завдання у разі успіху. У разі невдачі повертають False або None.

MaviBot використовує формат дати "дд.мм.рррр" та формат часу "ГГ:ХХ".

create_task() | update_task() | done_task() | delete_task()

create_task(email, name, date_srok, description, time_srok) – створює завдання

Параметри:\ ! email - email відповідальної особи\ ! name - назва завдання\ ! date_srok - термін виконання, дата\ ! description - опис завдання
time_srok - час виконання, час

update_task(task_id,email, name, date_srok, description, time_srok) - оновлює завдання

Параметри:\ ! task_id- ID завдання\ ! email - email відповідальної особи\ ! name - назва завдання\ ! date_srok - термін виконання, дата\ ! description - опис завдання
time_srok - час виконання, час

done_task(task_id)- позначає завдання як виконане

Параметри:\ ! task_id- ID завдання

delete_task(task_id) – видаляє завдання

Параметри:\ ! task_id- ID завдання

Призначити відповідального користувача

assign_order_to_user(email, order_id) — призначити відповідального користувача на угоду

  • email — email співробітника, якого потрібно призначити відповідальним. Обов'язковий.
  • order_id — ID угоди, на яку потрібно призначити співробітника. Якщо не вказано, використовується поточна угода. Необов'язковий.

Отримати email відповідального користувача

get_order_operator(order_id) — отримати email відповідального користувача за угодою

  • order_id — ID угоди, для якої потрібно отримати відповідального користувача. Якщо не вказано, використовується поточна угода. Необов'язковий.

Створимо завдання для оператора:

Оновимо термін виконання та опис.

Позначимо завдання як виконане.

Видалення завдання

task_id=create_task('[email protected]', 'Test', '22.01.2023', 'test task', '08:00') status=delete_task(task_id)

Робота з угодами

get_order_id() | create_order() | set_order_name() | set_order_budget() | get_active_orders_ids() | get_success_orders_ids() | get_fail_orders_ids() | get_order_var() | get_order_vars() | set_order_var() | set_order_vars() | move_order_to_next_state() | set_order_status_success() | set_order_status_fail(order_id)| get_state_id() | change_state() | get_order_id_by_var_value() | latest_order_datetime() | count_client_orders(), get_count_orders() | delete_order(order_id) |

Отримання ID поточної угоди

get_order_id() - повертає стан угоди.

Створення нової угоди

create_order(name, budget, description, client_name, phone, email, state_id)
Поточна активна угода у воронці, разом з її змінними, буде доступна лише у функціях, пов'язаних з угодами, та в CRM.

Параметри функції: \ ! name - (необов'язковий), назва угоди. Якщо не вказано, функція застосовується до поточної активної угоди клієнта.

! budget - (необов'язковий) сума угоди. Якщо не вказано, застосовується до поточної активної угоди.
Якщо budget не є числом, функція поверне: budget must be a number

description - (необов'язковий), опис угоди.

Додаткові параметри для створення клієнта:

client_name - (необов'язковий) рядок, ім'я нового клієнта

phone - (необов'язковий) рядок, номер телефону нового клієнта.

email - (необов'язковий) рядок, електронна адреса нового клієнта.

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

Якщо вказано email без телефону і клієнта з таким email не існує, буде створено нового.

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

state_id - число, дозволяє встановити початковий стан угоди при створенні

Встановити або оновити назву угоди

set_order_name(name, order_id)

name - ❗обов'язковий, рядок; назва угоди

order_id - (необов'язковий) ID угоди. Якщо не вказано, зміна застосовується до поточної активної угоди клієнта.

Встановити або оновити бюджет угоди

set_order_budget(budget, order_id)

budget -❗обов'язковий, число; сума угоди

order_id - (необов'язковий) ID угоди. Якщо не вказано, застосовується до поточної активної угоди клієнта.

Для правильного використання order_id:

  1. Ви можете вказати його вручну — отримати ID угоди та передати його як параметр функції, якщо ви хочете вплинути на конкретну угоду.

  1. Отримати його за допомогою функції get_order_id(), оскільки вбудована змінна order_id повертає значення у форматі {client_id}-{order_id}, що може спричинити некоректну поведінку.

Отримання списків угод
((за винятком архівних, успішних або невдалих угод))

get_active_orders_ids()

Отримати список ID успішних угод

get_success_orders_ids()

Отримати список ID невдалих угод

get_fail_orders_ids()

Отримання значення змінної угоди

get_order_var(order_id, variable)

Параметри:

! order_id - ID угоди

! variable - назва змінної, значення якої потрібно отримати

Отримання даних угоди

get_order_vars(order_id, names)

Параметри:

! order_id - ID угоди

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

Функція повертає словник, що містить змінні, перелічені в масиві names для угоди, визначеної order_id. Якщо names не вказано, повертає словник з усіма змінними вказаної угоди.

Додавання змінної угоди

set_order_var(order_id, variable, value)

Параметри:

! order_id - ID угоди

! variable - назва змінної для додавання або оновлення в угоді

Якщо ви хочете змінити параметри угоди "name" або "description", використовуйте назви змінних "name" або "description" відповідно.

! value - значення змінної

Додавання кількох змінних угоди

set_order_vars(order_id, variables_dict)

Параметри:

! order_id - ID угоди.

! variables_dict - словник змінних

Перехід до наступного стану воронки

move_order_to_next_state(order_id)

Параметри:
order_id - ID угоди. Якщо не вказано, буде переміщено поточну активну угоду.
Порядок станів угоди визначається відповідно до послідовності, встановленої в MavibotCRM.

Отримання стадії воронки в MavibotCRM

get_state_id(client_id, order_id)
Ви також можете скопіювати ID стану воронки безпосередньо з "Налаштувань стану".

Параметри:

order_id - ID угоди клієнта

Ви можете викликати функцію з параметром order_id або без нього. Якщо order_id пропущено, функція поверне ID стану воронки для поточної активної угоди.

Для правильного використання order_id:

  1. Ви можете вказати його вручну, отримавши ID угоди та передавши його як параметр функції, коли ви хочете вплинути на конкретну угоду.
  2. Отримати його за допомогою функції get_order_id(), оскільки вбудована змінна order_id повертає значення у форматі {client_id}-{order_id}, що може спричинити некоректну поведінку.

Переміщення ліда по воронці MavibotCRM за ID стану

change_state(state_id, order_id)

Параметри:\ ! state_id - ID стану воронки
order_id ( необов'язковий) - ID угоди для переміщення по воронці. Якщо пропущено, буде переміщено поточну активну угоду.

Отримання ID угоди за назвою та значенням змінної

get_order_id_by_var_value(var_name, var_value, client_id)

Параметри:\ ! var_name - назва змінної\ ! var_value - значення змінної;
client_id - (необов'язковий) ID угоди клієнта; за замовчуванням дорівнює ID клієнта в боті

Отримання дати та часу останньої угоди

latest_order_datetime(client_id, dt_fmt)

Параметри:
client_id - (необов'язковий) ID угоди клієнта; за замовчуванням дорівнює ID клієнта в боті;
df_fmt - (необов'язковий) формат для повернення дати та часу; за замовчуванням "%d.%m.%y %H:%M"

Отримання кількості угод клієнта

count_client_orders(client_id, state_id, get_all, active)

Параметри:
client_id - (необов'язковий) ID угоди клієнта; за замовчуванням дорівнює ID клієнта в боті;
state_id - (необов'язковий) ID стану угоди у воронці;
get_all - (необов'язковий) прапорець фільтрації для параметра active; за замовчуванням 1 (фільтрація за active вимкнена);
active - використовується лише коли get_all дорівнює 0; фільтрує активні угоди; за замовчуванням 1 (повертає лише активні угоди);

Отримати кількість угод у певному стані угоди

get_count_orders(id) - повертає кількість угод, які зараз знаходяться в певному стані воронки за ID стану.

Функція приймає один параметр:

! id - ID стану угоди.

Приклад використання функції:

ID стадії можна знайти в налаштуваннях.

Далі потрібно ввести функцію в калькулятор наступним чином:

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

Видалення угоди

delete_order(order_id) — видаляє угоду в MaviBotCRM.

order_id - (необов'язковий) ID угоди для видалення. Якщо пропущено, буде видалено останню угоду.

Усі функції прості у використанні.

Наприклад, створимо нову угоду та надішлемо її номер клієнту:

Ви можете отримати ID поточної активної угоди клієнта за допомогою функції get_order_id(), або отримати повний список угод клієнта за допомогою get_active_orders_ids().

Встановлення позначки успішної угоди

set_order_status_success()

Опис

set_order_status_success(order_id)

Параметри:

order_id - ID угоди. Якщо параметр не вказано, позначку буде встановлено для поточної активної угоди.

Встановлення позначки невдалої угоди

set_order_status_fail()

Опис

set_order_status_fail(order_id)

Параметри:

order_id - ID угоди. Якщо параметр не вказано, позначку буде встановлено для поточної активної угоди.

Встановлення позначки архівної угоди

set_order_status_archive()

Опис

set_order_status_archive(order_id)

Параметри:

order_id - ID угоди. Якщо параметр не вказано, позначку буде встановлено для поточної активної угоди.

Приклади

/*Архівувати поточну активну угоду*/

res_arh = set_order_status_archive()