Привет, Хабр. На связи Екатерина Саяпина, Product Owner платформы МТС Exolve. В этом материале я расскажу, как автоматически добавить в CRM оптимальное время для общения с клиентами. В рамках этого кейса я покажу настройку нашей платформы и получение информации из нее в Битрикс24.
Подготовка МТС Exolve
Подключение
Этот процесс описан в одном из наших предыдущих материалов: нужно завести аккаунт, подписать договор, создать приложение и получить API-ключ. В списке приложений выберите нужное:
Затем перейдите в «Настройки» на панели слева:
Пролистайте до конца вниз и нажмите на кнопку «Подключить» в блоке «Умная проверка номеров»:
Так как это платная услуга, то нужно будет ознакомиться с условиями и тарифами и подтвердить ваше согласие.
Теперь нам доступна работа с Number Lookup API — набором методов, с помощью которых можно получить оптимальное время для звонка. Мы используем GetBestCallTime. Он покажет, когда лучше всего позвонить абоненту. Надо учитывать, что этот метод работает только с клиентами МТС.
Применение
Используем POST-запрос https://api.exolve.ru/hlr/v1/GetBestCallTime. Для авторизации берем Bearer-токен из нашего приложения МТС Exolve, а в тело запроса в JSON-формате добавляем проверяемый телефон. Отправку запроса и преобразование ответа к нужному виду делаем так:
def get_time(time_string: str): hstr = time_string.split(':')[0] return time(hour=int(hstr)) def get_time_range(recepient: str): payload = {'number': recipient} r = requests.post(r'https://api.exolve.ru/hlr/v1/GetBestCallTime', headers={'Authorization': 'Bearer '+sms_api_key}, data=json.dumps(payload)) print(r.text) if r.status_code == 200: ans = json.loads(r.text) text = ans['result'].split(',') since, till = [get_time(t) for t in text] ans.update({'since': since, 'till': till}) return ans return None
Функция get_time_range отправляет запрос и проверяет успешность передачи информации. В последнем случае при помощи get_time получаем время в часах, соответствующее началу и концу периода, наиболее благоприятного для звонка этому абоненту.
Готовим приложение
Импортируем все необходимые библиотеки, в том числе для работы с CRM Битрикс24, потому что именно в ней будет все храниться:
from flask import Flask import requests import json from dataclasses import dataclass import pandas as pd from fast_bitrix24 import Bitrix from datetime import time from datetime import datetime as dt
База данных
Для синхронизации используем функции получения записей о клиентах и номерах телефонов по их ID. Работу с ними мы описывали в одном из прошлых материалов. Номера, а вместе с ними начало и конец подходящих для звонка интервалов храним в pandas DataFrame. Эта библиотека используется для автоматизации обработки данных, а объекты класса DataFrame можно представить как таблицу с индексацией по строкам и столбцам.
Создадим класс для управления базой данных и инициализируем ее поля:
@dataclass class DB: UTC_plus = 3 phones_and_clients_table = pd.DataFrame(columns=['phone', 'client_id', 'call_since', 'call_till']).set_index(['phone'])
Они содержат сдвиг в часах вашей временной зоны относительно UTC+0, а также pandas DataFrame с информацией о номерах телефонов.
Синхронизация с CRM
Сначала функция add_client_phones получает номера клиента из Битрикс24 и передает их в локальную базу. Затем push_phone нормализует номер телефона, проверяет его наличие в базе и при необходимости добавляет. У каждого номера должен быть свой уникальный client_id. Если его нет, то он присваивается автоматически.
def add_client_phones(self, client_full_record): contact_phones = [ph.get('VALUE', '') for ph in client_full_record.get('PHONE', [{}])] if len(contact_phones) == 0: return 0 for c in contact_phones: self.push_phone(c, client_ID=[client_full_record.get('ID')]) return 1 def push_phone(self, phone, client_ID=None, since=None, till=None, replace=False): phone_str = str(phone).replace(' ', '').replace('(', '').replace(')', '').replace('-', '').replace('+', '') if not replace and phone_str in self.phones_and_clients_table.index: return if client_ID is None: client_ID = self.phones_and_clients_table.shape[0] self.phones_and_clients_table.loc[phone_str, 'client_id'] = client_ID self.phones_and_clients_table.loc[phone_str, 'call_since'] = since + self.UTC_plus self.phones_and_clients_table.loc[phone_str, 'call_till'] = till + self.UTC_plus
Получение списка телефонов
При синхронизации с Битрикс24 для новых клиентов устанавливаются значения границ интервалов доступности — когда стоит звонить. Для уже внесенных в базу номеров данные не обновляются повторно — это позволяет избежать лишних запросов к API, если не установлен флаг update=True.
def add_times(self, phone, update=False): if phone not in self.phones_and_clients_table.index: return if self.phones_and_clients_table.loc[phone, 'call_since'] and self.phones_and_clients_table.loc[phone, 'call_till'] and not update: return ans = get_time_range(phone) if ans is None: return self.phones_and_clients_table.loc[phone, 'call_since'] = ans['since'] self.phones_and_clients_table.loc[phone, 'call_till'] = ans['till']
Функция add_times_for_db запускает обновление интервалов для всех телефонов в базе:
def add_times_for_db(self, update=False): for ph in self.phones_and_clients_table.index: self.add_times(ph, update)
Функция select_for_call возвращает список номеров, которые подходят для звонка в ближайшее время:
def select_for_call(self, hour=None): if hour is None: hour = dt.now().hour since_indexes = self.phones_and_clients_table['call_since'] <= hour + 1 till_indexes = self.phones_and_clients_table['call_till'] >= hour indexes = since_indexes * till_indexes temp_table = self.phones_and_clients_table.loc[indexes].sort_values('call_till') return temp_table.index.to_list()
По умолчанию используется текущий час. Выбираются номера:
чей интервал еще не истек (call_till ≥ hour);
интервал уже идет или начнется в течение следующего часа (call_since ≤ hour + 1).
Затем список сортируется по времени окончания интервала (call_till) — в приоритете те, у кого он скоро закончится. Номера, которые пока недоступны, в выборку не попадают.
Для экспорта базы телефонов в Excel используем эту функцию:
def dump(self): self.phones_and_clients_table.to_excel('Dump.xlsx')
Как работает серверная часть
Создаем сервер на фреймворке Flask. Нам достаточно одной функции, возвращающей JSON-объект. Flask автоматически преобразует словарь в объект, который можно передать по сети.
@app.route('/get_phones', methods=['GET']) def get_phones(): ans = crm_pipeline() return json.dumps(ans) def main(): app.run(host='0.0.0.0', port=5000)
В результате приложение возвращает JSON, содержащий только номера, упорядоченные в рекомендуемом порядке:
[ "79101????24", "79101????09", "79101????32", ]
Можно получить сведения о доступности клиентов, выгрузив JSON для последующей программной обработки. Для этого отправляем запрос по адресу https://<your_server>/get_phones_list и вызываем функцию:
@app.route('/get_phones_list', methods=['GET']) def get_phones_list(): return db.phone_table.to_json(None, 'index')
Она возвращает JSON вида:
{ "79101????00": { "client_id": 0, "call_since": 16, "call_till": 17 }, "79101????01": { "client_id": 1, "call_since": 8, "call_till": 9 }, "79101????03": { "client_id": 2, "call_since": 11, "call_till": 12 } }
В таком виде результат подходит для обработки другими приложениями. Его можно сделать удобным и для чтения человеком. Используем функции экспорта базы данных в Excel и передачи файла по HTTP-запросу:
@app.route('/get_phones_table', methods=['GET']) def get_phones_table(): db.dump() try: return send_file('Dump.xlsx', mimetype='application/octet-stream', as_attachment=True) except Exception as e: return str(e), 405
Так будет выглядеть полученная таблица:
Получение номеров телефонов клиентов, заполнение границ интервалов для звонков и создание упорядоченного списка задаются одной небольшой функцией, которая вызывается при каждом запросе определения доступности:
def crm_pipeline(): clients = get_contacts() for c in clients: db.add_client_phones(c) db.add_times_for_db() ans = db.select_for_call() return ans
Это решение можно развернуть в докер-контейнере, в том числе на бесплатном хостинге, как мы описывали в другом нашем материале. Информация от МТС Exolve будет обновляться только для номеров, которые добавляются в базу при синхронизации с CRM, выполняемой с каждым запросом.
Мы собрали рабочее решение для автоматического определения лучшего времени звонка и интегрировали его с CRM Битрикс24. В основе — метод одиночной проверки GetBestCallTime, который показывает, когда абонент чаще всего на связи. Для работы с большими списками номеров есть отдельный метод GenerateBestCallTimeReport.
