Привет, Хабр.

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

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

Я Леонид Тараскин, руководитель портфеля продуктов в МТС Exolve. В этом гайде на Python расскажу, как собрать из связки МТС Exolve и MWS Tables легкую CRM с исходящими и входящими СМС-уведомлениями.

Что используем:

• MWS Tables — табличный сервис с доступом по API.

• Стек: Python 3.10+, Flask, requests, SQLite, python-dotenv, MWS Tables API, API МТС Exolve.

Общая схема работы

Открываем MWS Tables. В таблицу вручную или по API добавляем строку с данными клиента: имя, телефон, время визита, статус записи и код шаблона сообщения. Для команды это обычная рабочая строка, а для Python-сервиса — задача на отправку СМС.

Дальше фоновый воркер периодически просматривает таблицу. Он берет только те строки, где клиент записан, но СМС не получил. Для каждой такой строки сервис нормализует формат номера телефона, собирает текст по шаблону и отправляет сообщение через SMS API.

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

Сценарий заканчивается там же, где начался, — в MWS Tables. Если клиент отвечает, МТС Exolve присылает сообщение на вебхук, а сервис находит строку клиента по номеру телефона и записывает ответ в поле client_reply.

Коротко поток выглядит так:

1. Запись клиента появилась в MWS Tables

2. Воркер отправил СМС через МТС Exolve

3. Результат отправки вернулся в строку MWS Tables

4. Ответ клиента тоже вернулся в эту строку

Архитектура решения

В системе есть два процесса Python, одно локальное хранилище и две внешние системы.

MWS Tables хранит бизнес-данные: строки клиентов, телефоны, статусы записи, коды шаблонов, результат отправки и ответ клиента. Это источник задач для воркера и рабочий интерфейс для команды.

МТС Exolve используется в двух местах. Через SMS API сервис отправляет исходящие СМС. Через вебхук МТС Exolve возвращает входящие сообщения клиентов на маршрут POST: /webhook/exolve/incoming.

worker.py — фоновый процесс. Читает строки из MWS Tables, выбирает записи для отправки, вызывает SMS API и обновляет результат в таблице. Его можно запускать отдельно от веб-сервера.

app.py — HTTP-сервер на Flask. Он принимает вебхук от МТС Exolve, ищет клиента по номеру телефона и записывает ответ в поле client_reply в MWS Tables.

SQLite хранит техническое состояние отправок. В базе delivery_log.db лежат попытки, статус задачи, последняя ошибка, messageid и время следующей попытки. Клиентские карточки там не хранятся.

Интеграционные файлы держат внешние вызовы отдельно от бизнес-логики. tables_api.py читает и обновляет MWS Tables, sms_sender.py вызывает SMS API, sms_templates.py хранит тексты сообщений, а config.py собирает ключи, URL и интервалы.

В минимальном решении воркер работает через полинг, состояние отправок хранится в SQLite.

Пререквизит

Устанавливаем зависимости и задаем переменные окружения. Конфигурация загружается из .env, а секреты остаются вне кода.

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Минимальный .env:

MWS_TABLES_BASE_URL=https://tables.mws.ru
MWS_TABLES_API_KEY=***
MWS_TABLE_ID=***
MWS_VIEW_ID=***


EXOLVE_API_KEY=***
EXOLVE_SENDER=MYBRAND


WORKER_POLL_INTERVAL_SECONDS=300
MAX_ATTEMPTS=2
RETRY_INTERVAL_SECONDS=1800
DB_NAME=delivery_log.db

Шаг 1. Выносим настройки в окружение

В окружение выносим адрес MWS Tables, токены, отправителя и интервалы повторов. Так один и тот же код запускается в разных средах без правки исходников.

`config.py`


```python
import os
from dotenv import load_dotenv


load_dotenv()


class Config:
   MWS_TABLES_BASE_URL = os.environ.get("MWS_TABLES_BASE_URL", "https://tables.mws.ru")
   MWS_TABLES_API_KEY = os.environ.get("MWS_TABLES_API_KEY", "your_mws_token")
   MWS_TABLE_ID = os.environ.get("MWS_TABLE_ID", "your_datasheet_id")
   MWS_VIEW_ID = os.environ.get("MWS_VIEW_ID", "your_view_id")


   EXOLVE_API_KEY = os.environ.get("EXOLVE_API_KEY", "your_exolve_key")
   EXOLVE_SENDER = os.environ.get("EXOLVE_SENDER", "MYBRAND")


   WORKER_POLL_INTERVAL_SECONDS = int(os.environ.get("WORKER_POLL_INTERVAL_SECONDS", 300))
   MAX_ATTEMPTS = int(os.environ.get("MAX_ATTEMPTS", 2))
   DB_NAME = os.environ.get("DB_NAME", "delivery_log.db")
```

Шаг 2. Подключаем MWS Tables как источник задач

Таблица хранит бизнес-данные и показывает результат автоматизации. Воркер читает из нее строки, а затем записывает статусы отправки и ошибки обратно. Команда не меняет привычный интерфейс, но получает больше контроля. В tablesapi.py URL собирается из MWS_TABLES_BASE_URL, MWS_TABLE_ID и пути /fusion/v1/datasheets/…/records.

Две основные функции — fetch_rows() для чтения записей и update_row() для обновления конкретной строки.

```python
def fetch_rows():
   params = {"viewId": Config.MWS_VIEW_ID, "fieldKey": "name"}
   resp = requests.get(_records_url(), headers=_headers(), params=params, timeout=20)
   resp.raise_for_status()
   payload = resp.json()
   if not payload.get("success", True):
       raise RuntimeError(f"MWS Tables API error: {payload}")
   return payload.get("data", {}).get("records", [])


def update_row(record_id: str, fields: dict):
   params = {"viewId": Config.MWS_VIEW_ID, "fieldKey": "name"}
   payload = {
       "records": [{"recordId": record_id, "fields": fields}],
       "fieldKey": "name",
   }
   resp = requests.patch(
       _records_url(),
       headers=_headers(),
       params=params,
       json=payload,
       timeout=20,
   )
   resp.raise_for_status()
   return resp.json()
```

Минимальная строка, которую ожидает воркер:

```json
{
 "recordId": "rec_1",
 "fields": {
   "client_name": "Анна",
   "phone": "+79991112233",
   "status": "Записан",
   "template_code": "appointment_created",
   "sms_sent": false
 }
}
```

У HTTP-вызовов есть timeout=20. HTTP-ошибки и success = false не маскируются: обработка прерывается исключением.

Шаг 3. Храним состояние отправки в SQLite

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

`database.py`


```python
STATUSES = {"READY", "PROCESSING", "SENT", "FAILED", "RETRY_WAIT"}


def init_db():
   with get_conn() as conn:
       conn.execute("""
       CREATE TABLE IF NOT EXISTS sms_jobs (
           external_row_id TEXT PRIMARY KEY,
           status TEXT NOT NULL,
           attempts INTEGER NOT NULL DEFAULT 0,
           template_code TEXT,
           phone TEXT,
           message_id TEXT,
           last_error TEXT,
           next_retry_at INTEGER,
           created_at INTEGER NOT NULL,
           updated_at INTEGER NOT NULL
       )
       """)
       conn.commit()
```

external_row_id — это recordId из MWS Tables. Он связывает бизнес-строку и техническую задачу, а заодно дает базовую идемпотентность: для одной строки создается одна запись в sms_jobs. Функция upsert_job() создает задачу со статусом READY или обновляет существующую.

Шаг 4. Собираем текст и отправляем СМС

Код шаблона в MWS Tables определяет текст сообщения, а воркер подставляет данные клиента.

`sms_templates.py`


```python
SMS_TEMPLATES = {
   "appointment_created": "Здравствуйте, {client_name}! Вы записаны на {visit_at}.",
   "appointment_reminder": "Здравствуйте, {client_name}! Напоминаем о вашей записи на {visit_at}.",
   "order_ready": "Здравствуйте, {client_name}! Ваш заказ готов к выдаче."
}
```

Отправку через МТС Exolve выносим в отдельную функцию, чтобы воркер не зависел от деталей HTTP-запроса.

`sms_sender.py`


```python
def send_sms(destination: str, text: str):
   url = "https://api.exolve.ru/messaging/v1/SendSMS"
   headers = {
       "Authorization": f"Bearer {Config.EXOLVE_API_KEY}",
       "Content-Type": "application/json",
   }
   payload = {
       "number": Config.EXOLVE_SENDER,
       "destination": destination,
       "text": text,
   }
   resp = requests.post(url, headers=headers, json=payload, timeout=20)
   resp.raise_for_status()
   return resp.json()
```

Если МТС Exolve вернет HTTP-ошибку или сеть упадет по таймауту, исключение поднимется в воркер. Там задача уйдет в RETRY_WAIT или FAILED.

Шаг 5. Обрабатываем строки воркером

Воркер соединяет таблицу, шаблоны, SMS API и локальный журнал. Каждая строка проходит одинаковые проверки, а результат возвращается в MWS Tables.

Первые фильтры воркера — нормализовать номер и проверить бизнес-статус. Нормализация приводит разные записи телефона к одному виду: убирает пробелы, скобки и дефисы, 8 в начале заменяет на 7.

`worker.py`


```python
def normalize_phone(phone: str) -> str:
   digits = "".join(ch for ch in str(phone) if ch.isdigit())
   if len(digits) == 11 and digits.startswith("8"):
       digits = "7" + digits[1:]
   return digits


def is_valid_phone(phone: str) -> bool:
   digits = "".join(ch for ch in str(phone) if ch.isdigit())
   return len(digits) == 11 and digits.startswith("7")


def is_ready_for_sms(fields: dict) -> bool:
   return fields.get("status") == "Записан" and not fields.get("sms_sent")
```

Дальше process_rows() читает записи и отбрасывает всё, что не готово к отправке. Если телефон неправильный, нет template_code или код шаблона неизвестен, воркер не отправляет СМС и пишет ошибку в таблицу.

```python
if not phone or not is_valid_phone(phone):
   update_row(row_id, {
       "delivery_status": "FAILED",
       "last_error": "Invalid phone number"
   })
   continue


if template_code not in SMS_TEMPLATES:
   update_row(row_id, {
       "delivery_status": "FAILED",
       "last_error": f"Unknown template: {template_code}"
   })
   continue
```

Ошибка возвращается в MWS Tables: менеджер видит FAILED и причину в last_error без доступа к логам.

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

```python
upsert_job(row_id, template_code, phone)
job = get_job(row_id)


if job["status"] == "SENT":
   continue


if job["status"] == "RETRY_WAIT" and job["next_retry_at"] and job["next_retry_at"] > now:
   continue


text = SMS_TEMPLATES[template_code].format(
   client_name=fields.get("client_name", "клиент"),
   visit_at=fields.get("visit_at", "указанное время"),
)
```

Статусы SENT и RETRY_WAIT защищают от дублей и ранних повторов. Текст собирается через .format(), для отсутствующих данных заданы значения по умолчанию.

Успешная отправка обновляет и SQLite, и MWS Tables.

```python
mark_job(row_id, status="PROCESSING")
result = send_sms(phone, text)


message_id = (
   result.get("message_id")
   or result.get("id")
   or result.get("result", {}).get("message_id")
)


mark_job(row_id, status="SENT", message_id=message_id, increment_attempt=True)


update_row(row_id, {
   "sms_sent": True,
   "sms_sent_at": now,
   "sms_message_id": message_id,
   "delivery_status": "SENT",
   "last_error": None
})
```

Если отправка падает, код переводит задачу в RETRY_WAIT или FAILED и пишет ошибку в таблицу. Интервал повтора фиксированный, а число попыток задается через MAX_ATTEMPTS.

Запускается воркер простым циклом:

```python
def run_forever():
   init_db()
   logger.info("SMS worker started")
   while True:
       try:
           process_rows()
       except Exception:
           logger.exception("Worker loop error")
       time.sleep(Config.WORKER_POLL_INTERVAL_SECONDS)
```

Полинг проще очереди и хорошо подходит для пилота. Если нужна быстрая реакция или много сообщений, следующим шагом будет Celery или RQ с Redis.

Шаг 6. Принимаем ответы клиентов

Когда клиент отвечает на СМС, МТС Exolve отправляет входящее сообщение на Flask-маршрут POST: /webhook/exolve/incoming. Обработчик берет номер отправителя и текст ответа, а затем обновляет строку клиента в MWS Tables.

`app.py`


```python
@app.route("/webhook/exolve/incoming", methods=["POST"])
def incoming_sms():
   data = request.get_json(silent=True) or {}


   direction = data.get("direction")
   if direction and direction != "DIRECTION_INCOMING":
       return jsonify({"status": "ignored_direction"}), 200


   sender = data.get("sender")
   text = data.get("text")


   if not sender or not text:
       return "Bad Request: sender or text missing", 400
```

На входе отсекаем не входящие события и payload без sender или text. Пример:

```json
{
 "direction": "DIRECTION_INCOMING",
 "sender": "+79991112233",
 "text": "Да, буду"
}
```

После этого сервис нормализует номер, читает строки из MWS Tables и ищет последнюю запись с таким телефоном.

```python
client_phone = normalize_phone(sender)
rows = fetch_rows()
target_row_id = None


for row in reversed(rows):
   fields = row.get("fields", {})
   if normalize_phone(fields.get("phone", "")) == client_phone:
       target_row_id = row["recordId"]
       break


if target_row_id:
   update_row(target_row_id, {"client_reply": text})
   return jsonify({"status": "updated"}), 200


return jsonify({"status": "client_not_found"}), 404
```

В этой версии ответ перезаписывает поле client_reply, история входящих сообщений не хранится.

Запуск и проверка

Перед запуском подготовьте строку в MWS Tables: телефон клиента, статус «Записан», код шаблона и sms_sent = false. И задайте реальные параметры MWS Tables и МТС Exolve:

```bash
export MWS_TABLES_BASE_URL=https://tables.mws.ru
export MWS_TABLES_API_KEY=***
export MWS_TABLE_ID=***
export MWS_VIEW_ID=***
export EXOLVE_API_KEY=***
export EXOLVE_SENDER=MYBRAND
```

Запускаем воркер. Он прочитает строки из MWS Tables, найдет запись для отправки и вызовет SMS API МТС Exolve.

```bash
python worker.py
```

После успешной отправки в строке появятся sms_sent, sms_sent_at, sms_message_id и delivery_status.

Вебхук запускается отдельно:

```bash
python app.py
```

Проверяем входящее СМС вручную. В sender укажите тот же номер, что в MWS Tables:

```bash
curl -X POST "http://127.0.0.1:5000/webhook/exolve/incoming" 
 -H "Content-Type: application/json" 
 -d '{"direction":"DIRECTION_INCOMING","sender":"+79991112233","text":"Да, буду"}'
```

Ожидаемый ответ:

```json
{"status": "updated"}
```

Если получили 400, проверьте sender и text. Если 404 — номер не совпал ни с одной строкой после нормализации. Если 5xx — проверьте доступность MWS Tables API, токен, MWS_TABLE_ID, MWS_VIEW_ID и сетевые таймауты.

Как улучшить результат

До стабильного прод-решения осталось несколько действий:

1. Добавить проверку подписи или секрет вебхука. Сейчас маршрут доверяет любому POST с подходящим JSON

2. Перейти с SQLite на Postgres и миграции, если будет несколько воркеров или общая продовая среда

3. Вынести отправку в очередь Celery или RQ с Redis, чтобы не зависеть от полинга и проще управлять повторами

4. Разделить ошибки данных и временные ошибки API. Невалидный номер не нужно повторять так же, как сетевой сбой

5. Сделать историю входящих СМС отдельной таблицей, а не перезаписывать поле client_reply

6. Добавить наблюдаемость: структурированные логи по recordId, счетчики SENT, FAILED, RETRY_WAIT и алерты по росту ошибок

Что изменит мини-CRM

Решение закрывает простой, но болезненный операционный сценарий: команда больше не отправляет СМС вручную и видит результат в той же таблице, где ведет записи клиентов. MWS Tables остается рабочим интерфейсом, МТС Exolve отвечает за отправку СМС, SQLite хранит состояние попыток, а вебхук возвращает ответы клиентов обратно в строку.

Для «пилота» этого достаточно. У команды появляется понятный поток данных: кто ждет сообщение, кому уже отправили, что ответил клиент, возникла ли ошибка и где. Эффект можно измерять по числу ручных отправок, доле ошибок, скорости подтверждения записи и количеству потерянных ответов.