DEV Community: ALEKSANDR MICHAILOVICH

CRM CSV Exports: Quarantine Suspicious Fields Before Handoff [cross-post]

ALEKSANDR MICHAILOVICH — Fri, 30 Oct 2026 20:08:41 +0000

Why a CRM CSV export needs its own check

Separate machine transfer from spreadsheet viewing before handing an export to a sales representative. User-entered fields can become formulas in the application that opens the file. Under an agreed policy, hold suspicious rows for review while retaining their original values in protected storage. Putting fields inside quotation marks does not establish that formulas are safe.

OWASP describes CSV Injection as untrusted input entering a CSV and subsequently being interpreted by spreadsheet software. In particular, a cell beginning with = may be treated as a formula. CWE-1236 documents the weakness and the limitations of mitigation techniques.[1][2]

A company name, an enquiry comment, or a field copied from another service can contain untrusted text. Passing through a trusted CRM does not change its origin. Permission to download a report does not establish that every value is safe for the next application.

This article proposes a policy for an export handler you control. It does not describe a verified built-in 24go.site feature, a universal defense for every spreadsheet, or permission to collect other people's contacts. The example uses synthetic records only. It checks handler decisions, does not launch Excel or Calc, and makes no CRM requests.

Agree on who will open the file

An export needs a named consumer. A machine-transfer file must preserve values according to an explicit data contract. A file intended for human viewing needs application-specific behavior checks. Button labels, format descriptions, and storage routes should make that distinction visible.

Purpose	Agree on	Treat as an error
Machine transfer	Schema, encoding, delimiter, empty-value handling	Silently changing a phone number or comment
Sales representative's review	Application, version, import settings, exception policy	Interpreting untrusted text as a formula
Exception investigation	Owner, access, retention, viewing method	Moving the original suspect values into an ordinary CSV

Do not label a machine-transfer CSV safe to open by double-clicking. It has a different contract with its recipient. JSON with an explicit schema may be a suitable choice when exact text transfer matters, but JSON itself cannot control what the recipient does next. A later conversion into a spreadsheet creates another boundary that needs checking.

Start a human-readable report with the smallest useful set of columns. If the recipient needs only an enquiry ID, status, and date, omit the full conversation. Reducing fields reduces the amount of untrusted text and disclosed information; it does not replace validation of the values that remain.

The handoff sits alongside Telegram-to-CRM integration, but export checking addresses a separate task after a record has been stored. The policy here does not verify the product settings or capabilities mentioned in historical blog articles.

Keep CSV serialization separate from formula policy

A CSV library handles field and row boundaries. Your content policy decides which values may be handed to a particular consumer. Run these checks in sequence. Reading a file back successfully with the same library verifies the transfer format, not spreadsheet formula behavior.

Python's documentation describes csv.writer, delimiter and quoting options, and opening CSV files with newline=''. By default, csv.reader returns strings without automatic type conversion. That is Python parser behavior, not a promise about how a spreadsheet will open the same file.[3]

Do not construct a row using ','.join(...). Commas, quotation marks, and line breaks inside a comment must remain inside that field. The example uses csv.writer to quote every field, then csv.reader to check the round trip. It applies the suspicious-prefix policy before writing; the QUOTE_ALL option does not replace that policy.

OWASP lists risky beginnings including =, +, -, @, tab, carriage return, line feed, and some full-width character variants. It also warns that delimiters and quotes can create a new cell boundary when handled incorrectly.[1] This gives you test cases, not evidence that a particular detector covers every interpretation.

Do not remove the first character from the original CRM record. A plus can belong to a phone number, a minus can be meaningful text, and an apostrophe can belong to a name. If you choose a viewing transformation, retain the original separately and document what the recipient will see. Apply the change in the presentation layer and test it in the target application.

What whole-row quarantine means

Under this proposed policy, a row containing a suspicious field is withheld from the human-view CSV. A separate exception log receives its ID, column name, and reason code. The original value stays in the system under restricted access. The handler does not automatically repair the value or delete the enquiry.

This is deliberately conservative. A phone number beginning with a plus can hold up an export if you include it among the text columns checked by this rule. That is an expected false positive of the policy. Phone numbers, amounts, and other typed fields need their own agreed contract, not an undocumented exemption.

Situation	Example's decision	Next action
Ordinary text	Include the row	Check CSV structure
Formula-like prefix after leading spaces	Hold the entire row	Review the field through a protected interface
Tab or line break anywhere in the field	Hold the entire row	Confirm whether multiline text is required
Unknown status or invalid schema	Stop processing with an error	Repair the contract; do not issue a successful file
Comma and quotes inside ordinary text	Serialize with the CSV library	Compare the value after reading it back

In a real workflow, show both the included-row count and the held-row count. The recipient must know that the report is incomplete. Do not call it a complete export while records remain under review. Give the exception owner a separate, access-controlled work list.

The exception log must not become another route for the same problem. Do not put the original suspect comment in a second CSV or paste the entire value into a notification. The example's JSON log contains only a synthetic ID, field name, and reason. Inspecting originals requires an interface that displays them as text without interpreting markup or formulas.

Reproduce the policy check without a spreadsheet

Save the following code as csv_policy_check.py and run python3 csv_policy_check.py. It requires Python 3 and its standard library. It creates records in memory, checks included rows and the exception log, writes no export file, and opens no spreadsheet. The value =1+1 is a harmless string used to exercise the rule; no calculation is performed.

import csv
import io
import json
import unicodedata

PREFIXES = set("=+-@＝＋－＠")
FIELDS = ("id", "status", "note")
STATUSES = {"new", "qualified"}

def reason(value):
    if any(ch in value for ch in "\t\r\n"):
        return "control_separator"
    probe = value.lstrip()
    if probe and unicodedata.category(probe[0]) == "Cf":
        return "leading_format_character"
    if probe and probe[0] in PREFIXES:
        return "formula_prefix"
    return None

def export_for_review(rows):
    accepted = []
    held = []
    for row in rows:
        if set(row) != set(FIELDS):
            raise ValueError("schema")
        if not all(isinstance(row[k], str) for k in FIELDS):
            raise ValueError("types")
        if not row["id"].isascii() or not row["id"].isdigit():
            raise ValueError("id")
        if row["status"] not in STATUSES:
            raise ValueError("status")
        issue = reason(row["note"])
        if issue:
            held.append({"id": row["id"], "field": "note", "reason": issue})
        else:
            accepted.append(row)
    out = io.StringIO(newline="")
    writer = csv.DictWriter(out, fieldnames=FIELDS, quoting=csv.QUOTE_ALL)
    writer.writeheader()
    writer.writerows(accepted)
    result = out.getvalue()
    restored = list(csv.DictReader(io.StringIO(result, newline="")))
    assert restored == accepted
    return result, held

rows = [
    {"id": "1", "status": "new", "note": "Call tomorrow"},
    {"id": "2", "status": "new", "note": '=1+1'},
    {"id": "3", "status": "qualified", "note": 'Said "yes", call later'},
    {"id": "4", "status": "new", "note": "  +44123"},
    {"id": "5", "status": "new", "note": "line\nbreak"},
    {"id": "6", "status": "new", "note": "＝1+1"},
    {"id": "7", "status": "new", "note": "\u200b=1+1"},
]
text, held = export_for_review(rows)
assert [r["id"] for r in csv.DictReader(io.StringIO(text))] == ["1", "3"]
assert [r["id"] for r in held] == ["2", "4", "5", "6", "7"]
for value in ("=1+1", "+1", "-1", "@name", "＝1", "＋1", "－1", "＠name"):
    assert reason(value) == "formula_prefix"
assert reason("  =1+1") == "formula_prefix"
assert reason("\tplain") == "control_separator"
assert reason("plain\rtext") == "control_separator"
for bad in (
    {"id": "8", "status": "unknown", "note": "plain"},
    {"id": "x", "status": "new", "note": "plain"},
    {"id": "8", "status": "new", "note": None},
):
    try:
        export_for_review([bad])
    except ValueError:
        pass
    else:
        raise AssertionError("invalid row accepted")
print(json.dumps({"accepted_ids": ["1", "3"], "held": held}, sort_keys=True))

Expect included IDs 1 and 3; the other synthetic records should appear in the held list with reason codes. The assertions also require rejection of an unknown status, a nonnumeric ID, and None. A traceback or AssertionError means the check failed; do not count that run as evidence that the policy works.

The detector intentionally holds any line break in a note and a leading Unicode format character in category Cf after whitespace. These are additional restrictions proposed by this example. They are not CSV requirements or a complete model of Unicode behavior in spreadsheets. If you add columns, extend validation to every new untrusted field.

What the Python check cannot establish

The round trip establishes that the two permitted synthetic records survive this CSV dialect unchanged. It does not establish identical handling across every Excel version, Calc, or another application. OWASP explicitly warns that no sanitization strategy is universally safe for every spreadsheet and downstream consumer.[1]

Before deployment, record the application, its version, regional settings, and import route. In an isolated environment using synthetic data, check the displayed value, cell type, column boundaries, and the absence of calculation for values intended to remain text. Do not use network formulas, commands, or real personal information for these checks.

Then save and reopen the file through the same route the recipient will use. OWASP notes that Excel can remove quotes or escape characters during saving and reopening.[1] A first-open check is therefore insufficient for a policy that relies on cell transformations. If the required application is unavailable, that stage remains unverified rather than automatically passing.

Quarantine also needs an operational check: the recipient sees the exceptions count, the owner can find the original enquiry, and a later export neither loses it nor silently removes its restriction. Changing an enquiry's business status must not automatically declare its comment safe.

Introduce the policy without losing enquiries

Start with observation in a test environment. Agree on hold reasons with the process owner and establish that records remain in the original system. Decide whether to enable production blocking based on concrete tests and team requirements, not on the existence of one successful script.

Define the columns and permitted types, including separate rules for empty strings, missing values, and negative numbers.
Assign a consumer to each export and prevent silent switching between human viewing and machine import.
Retain inclusion and hold examples covering commas, quotes, spaces, control characters, and full-width characters.
Check that a schema violation fails the whole job. Do not distribute a partly written file as a successful result.
Agree on protected exception review and the route for exporting a record after a human decision.
After changing a library, target application, or column set, rerun the affected checks and retain execution conditions.

The in-memory approach in this example may not suit large exports. A production handler needs size limits, temporary-storage controls, access restrictions, and atomic delivery of the completed file. Those are implementation responsibilities, not properties of the sample function. Do not begin a download before checking the conditions under which you promise a complete result.

Start with one existing report: list its untrusted fields, identify the actual recipient, and agree on what happens when the first row is held. If those answers are missing, the export contract is not ready. Consider 24go.site for enquiry workflows separately from this check: this article does not establish that the service implements the export mechanism described here.

Sources

[1] OWASP, CSV Injection: https://owasp.org/www-community/attacks/CSV_Injection

[2] MITRE, CWE-1236: https://cwe.mitre.org/data/definitions/1236.html

[3] Python, csv: https://docs.python.org/3/library/csv.html

This article was also published on other platforms. Original: CRM CSV Exports: Quarantine Suspicious Fields Before Handoff

CSV из CRM: как отправлять подозрительные поля на проверку [перекрёстная публикация]

ALEKSANDR MICHAILOVICH — Fri, 30 Oct 2026 20:08:39 +0000

Почему CSV из CRM требует отдельной проверки

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

OWASP описывает CSV Injection как попадание недоверенных данных в CSV с последующей интерпретацией содержимого электронной таблицей. В частности, ячейка, начинающаяся с =, может быть прочитана как формула. CWE-1236 отдельно описывает эту слабость и ограничения способов её устранения.[1][2]

Недоверенный текст может оказаться в названии компании, комментарии к обращению или поле, перенесённом из другого сервиса. Данные проходят через доверенную CRM, но происхождение текста от этого не меняется. Право скачать файл тоже не означает, что все его значения безопасны для следующей программы.

Ниже предложена политика для собственного обработчика экспорта. Это не описание проверенной встроенной функции 24go.site, не универсальная защита всех таблиц и не разрешение собирать чужие контакты. Пример работает только с искусственными записями. Он проверяет решения обработчика, не запускает Excel или Calc и не обращается к CRM.

Сначала договоритесь, кто откроет файл

У выгрузки должен быть конкретный потребитель. Файл для переноса между системами требует сохранения значений по контракту. Файл для просмотра человеком требует проверки поведения выбранной программы. Названия кнопок, описание формата и маршрут хранения должны отражать эту разницу.

Назначение	Что согласовать	Что считать ошибкой
Машинный перенос	Схему, кодировку, разделитель, обработку пустых значений	Незаметное изменение телефона или комментария
Просмотр менеджером	Программу, версию, настройки импорта, правила исключений	Открытие недоверенного текста как формулы
Разбор исключений	Ответственного, доступ, срок хранения, способ просмотра	Перенос исходных подозрительных значений в обычный CSV

Не называйте машинный CSV безопасным для открытия двойным щелчком. У него другой договор с получателем. Если требуется точная передача текста, можно выбрать JSON с явно описанной схемой, но сам выбор JSON не управляет тем, что получатель сделает с данными дальше. После преобразования в таблицу проверка понадобится на новой границе.

Для человеческого отчёта начните с минимального набора колонок. Если менеджеру достаточно номера заявки, статуса и даты, не добавляйте полный текст переписки. Уменьшение состава полей сокращает объём недоверенного текста и раскрываемых сведений; оно не заменяет проверку оставшихся значений.

Процесс передачи заявок связан с интеграцией Telegram и CRM, но проверка экспорта решает отдельную задачу после сохранения записи. Приведённая здесь политика не подтверждает настройки и функции продукта, перечисленные в исторических материалах блога.

Разделите сериализацию и политику формул

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

Документация Python описывает csv.writer, параметры разделителя и кавычек, а также открытие файлов с newline=''. По умолчанию csv.reader возвращает строки без автоматического преобразования типов. Это поведение парсера Python, не обещание о том, как тот же файл откроет электронная таблица.[3]

Не собирайте строку через ','.join(...). Запятая, кавычка или перенос строки в комментарии должны остаться частью своего поля. В примере используется csv.writer с кавычками для всех полей, затем csv.reader проверяет обратное чтение. Политика подозрительных префиксов применяется до записи, а не подменяется параметром QUOTE_ALL.

OWASP перечисляет среди рискованных начал =, +, -, @, табуляцию, возврат каретки, перевод строки и некоторые полноширинные варианты символов. Там же указано, что разделители и кавычки могут изменить границу ячейки при неправильной обработке.[1] Список помогает составить тесты, но не доказывает полноту конкретного детектора.

Не удаляйте первый знак из исходной CRM-записи. Плюс может быть частью номера телефона, минус — осмысленного текста, а апостроф — имени. Если выбран способ преобразования для просмотра, храните исходник отдельно и документируйте, какое значение увидит человек. Изменение должно происходить в представлении, с проверкой на целевом приложении.

Что означает карантин всей строки

В предложенной политике строка с подозрительным полем не попадает в человеческий CSV. Вместо неё в отдельный журнал исключений записываются идентификатор, название колонки и код причины. Исходное поле остаётся в системе с ограниченным доступом. Обработчик не пытается автоматически исправить значение и не удаляет заявку.

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

Ситуация	Решение примера	Дальнейшее действие
Обычный текст	Разрешить строку	Проверить структуру CSV
Формульный префикс после начальных пробелов	Задержать всю строку	Разобрать поле в защищённом интерфейсе
Табуляция или перенос строки в любом месте	Задержать всю строку	Подтвердить необходимость многострочного текста
Неизвестный статус или неверная схема	Остановить обработку с ошибкой	Исправить контракт, не выдавать успешный файл
Запятая и кавычки внутри обычного текста	Сохранить через CSV-библиотеку	Сверить значение после обратного чтения

В реальном процессе полезно показывать два числа: сколько строк включено и сколько задержано. Получатель должен знать, что отчёт неполон. Не называйте файл полной выгрузкой, если часть строк осталась на проверке. Для ответственного за исключения нужен отдельный список работ с контролем доступа.

Сам журнал не должен становиться вторым каналом проблемы. Не складывайте в его CSV исходный подозрительный комментарий и не отправляйте весь текст в уведомление. В примере JSON-журнал содержит только искусственный ID, имя поля и причину. Просмотр исходных данных потребует интерфейса, который выводит их как текст и не интерпретирует как разметку или формулы.

Воспроизводимый тест без электронной таблицы

Сохраните код как csv_policy_check.py и выполните python3 csv_policy_check.py. Нужен Python 3 со стандартной библиотекой. Программа создаёт данные только в памяти, проверяет разрешённые строки и журнал исключений. Она не пишет выгрузку на диск и не открывает таблицы. Значение =1+1 служит безопасной строкой для теста правила, вычисления не происходит.

import csv
import io
import json
import unicodedata

PREFIXES = set("=+-@＝＋－＠")
FIELDS = ("id", "status", "note")
STATUSES = {"new", "qualified"}

def reason(value):
    if any(ch in value for ch in "\t\r\n"):
        return "control_separator"
    probe = value.lstrip()
    if probe and unicodedata.category(probe[0]) == "Cf":
        return "leading_format_character"
    if probe and probe[0] in PREFIXES:
        return "formula_prefix"
    return None

def export_for_review(rows):
    accepted = []
    held = []
    for row in rows:
        if set(row) != set(FIELDS):
            raise ValueError("schema")
        if not all(isinstance(row[k], str) for k in FIELDS):
            raise ValueError("types")
        if not row["id"].isascii() or not row["id"].isdigit():
            raise ValueError("id")
        if row["status"] not in STATUSES:
            raise ValueError("status")
        issue = reason(row["note"])
        if issue:
            held.append({"id": row["id"], "field": "note", "reason": issue})
        else:
            accepted.append(row)
    out = io.StringIO(newline="")
    writer = csv.DictWriter(out, fieldnames=FIELDS, quoting=csv.QUOTE_ALL)
    writer.writeheader()
    writer.writerows(accepted)
    result = out.getvalue()
    restored = list(csv.DictReader(io.StringIO(result, newline="")))
    assert restored == accepted
    return result, held

rows = [
    {"id": "1", "status": "new", "note": "Call tomorrow"},
    {"id": "2", "status": "new", "note": '=1+1'},
    {"id": "3", "status": "qualified", "note": 'Said "yes", call later'},
    {"id": "4", "status": "new", "note": "  +44123"},
    {"id": "5", "status": "new", "note": "line\nbreak"},
    {"id": "6", "status": "new", "note": "＝1+1"},
    {"id": "7", "status": "new", "note": "\u200b=1+1"},
]
text, held = export_for_review(rows)
assert [r["id"] for r in csv.DictReader(io.StringIO(text))] == ["1", "3"]
assert [r["id"] for r in held] == ["2", "4", "5", "6", "7"]
for value in ("=1+1", "+1", "-1", "@name", "＝1", "＋1", "－1", "＠name"):
    assert reason(value) == "formula_prefix"
assert reason("  =1+1") == "formula_prefix"
assert reason("\tplain") == "control_separator"
assert reason("plain\rtext") == "control_separator"
for bad in (
    {"id": "8", "status": "unknown", "note": "plain"},
    {"id": "x", "status": "new", "note": "plain"},
    {"id": "8", "status": "new", "note": None},
):
    try:
        export_for_review([bad])
    except ValueError:
        pass
    else:
        raise AssertionError("invalid row accepted")
print(json.dumps({"accepted_ids": ["1", "3"], "held": held}, sort_keys=True))

Ожидаются разрешённые ID 1 и 3; остальные тестовые записи попадут в журнал с причинами. Проверки также требуют отказа при неизвестном статусе, нецифровом ID и значении None. Ошибка даёт traceback или AssertionError; такой запуск нельзя считать подтверждением политики.

Детектор сознательно задерживает любой перенос строки в комментарии и начальный форматирующий символ категории Cf после пробелов. Это собственные дополнительные ограничения примера. Они не объявлены требованиями CSV или полным описанием поведения Unicode в таблицах. После изменения набора колонок проверку надо расширить на каждое новое недоверенное поле.

Какие проверки остаются за пределами Python

Обратное чтение доказывает сохранение двух разрешённых тестовых записей в данном диалекте CSV. Оно не доказывает, что все версии Excel, Calc и другие программы одинаково обработают файл. OWASP прямо предупреждает об отсутствии универсальной стратегии для всех приложений и последующих потребителей.[1]

Перед внедрением зафиксируйте программу, её версию, региональные настройки и способ импорта. В изолированной среде на искусственных данных проверьте видимое значение ячейки, её тип, границы колонок и отсутствие вычисления у текста, который должен остаться текстом. Не используйте сетевые формулы, команды или реальные персональные данные для такой проверки.

Затем сохраните и повторно откройте файл тем же маршрутом, которым пойдёт менеджер. OWASP отмечает, что Excel может убирать кавычки или экранирующие символы при сохранении и повторном открытии.[1] Поэтому проверка первого открытия недостаточна для политики, которая полагается на преобразование ячеек. Если необходимого приложения нет, этот этап остаётся непроверенным, а не автоматически успешным.

Карантин также требует эксплуатационной проверки: получатель видит число исключений, ответственный может найти исходную заявку, повторный экспорт не теряет её и не снимает ограничение самопроизвольно. Изменение статуса заявки не должно означать автоматическое признание комментария безопасным.

Как внедрять без потери заявок

Сначала включите наблюдение в тестовом контуре, согласуйте причины задержки с владельцем процесса и убедитесь, что записи не исчезают из исходной системы. Решение о включении производственной блокировки принимается по конкретным тестам и требованиям команды, не по наличию одного успешного скрипта.

Опишите колонки и разрешённые типы; отдельно укажите правила для пустой строки, отсутствующего значения и отрицательных чисел.
Назначьте каждой выгрузке потребителя и запретите незаметно менять режим просмотра на машинный импорт.
Сохраните примеры разрешения и задержки, включая запятые, кавычки, пробелы, управляющие и полноширинные символы.
Проверьте отказ всего задания при нарушении схемы. Не отправляйте частично записанный файл как успешный результат.
Согласуйте защищённый разбор исключений и способ повторного экспорта после решения человека.
После обновления библиотеки, приложения или колонок повторите затронутые проверки и сохраните условия запуска.

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

Начните с одного своего отчёта: перечислите недоверенные поля, найдите его фактического получателя и согласуйте поведение при первой задержанной строке. Если это пока неизвестно, экспортный договор ещё не готов. Обсуждать использование 24go.site для работы с обращениями стоит отдельно от этой проверки: статья не подтверждает наличие в сервисе описанного экспортного механизма.

Источники

[1] OWASP, CSV Injection: https://owasp.org/www-community/attacks/CSV_Injection

[2] MITRE, CWE-1236: https://cwe.mitre.org/data/definitions/1236.html

[3] Python, csv: https://docs.python.org/3/library/csv.html

Эта статья также опубликована на других платформах. Оригинал: CSV из CRM: как отправлять подозрительные поля на проверку

Telegram Group Migration: Keep CRM Routing When the Chat ID Changes [cross-post]

ALEKSANDR MICHAILOVICH — Wed, 28 Oct 2026 02:36:09 +0000

Telegram Group Migration: Keep CRM Routing When the Chat ID Changes

When a Telegram group becomes a supergroup, do not treat its new chat ID as a new customer conversation. Record the relationship between the old and new IDs, keep your internal conversation identifier unchanged, and resolve the current destination before sending an authorized notification. If the two IDs already belong to different conversations, stop automatic processing and investigate the conflict rather than silently merging records.

This guide is for developers maintaining their own Telegram Bot API integration and CRM routing. It assumes a bot legitimately present in a working group, authenticated incoming updates, durable storage and a staging environment. The design is not a verified built-in feature of 24go.site. It does not require collecting members or sending unsolicited messages. A group is not an individual contact, and continuity of a group does not grant new permission to contact its members.

Read the migration fields in the right direction

The official Message reference defines two optional fields. They describe the same relationship from different sides:

Received evidence	Old group ID	New supergroup ID
A message with `migrate_to_chat_id`	That message's `chat.id`	Its `migrate_to_chat_id`
A message with `migrate_from_chat_id`	Its `migrate_from_chat_id`	That message's `chat.id`
Failed request with `parameters.migrate_to_chat_id`	The `chat_id` used in that exact request	The parameter's value

The third row comes from ResponseParameters, not from a service-message body. Keep the request context: without the original destination, the error response alone does not identify both ends. Do not look for an old identifier in a translated error description. Branch on the documented structured field, not on a particular English sentence or on every HTTP 400 response.

The fields are optional. Your handler must work when it observes only one direction, receives equivalent evidence again, or encounters migration evidence after normal traffic to the new group. Do not require two service messages to arrive together or in an assumed order. This is a defensive processing rule, not a claim that every installation will see all these cases.

Store the identifiers without narrowing them to 32-bit integers. Telegram notes that migration IDs can have more than 32 significant bits and at most 52 significant bits. A signed 64-bit database integer is a straightforward choice. If a CRM custom field cannot preserve that integer exactly, use a validated decimal string at that boundary and test round trips. Do not manufacture a new ID by adding a prefix to the old one; use the value supplied by Telegram.

Separate the conversation from its transport address

A fragile schema uses chat_id simultaneously as the CRM conversation key, the destination for notifications and the historical identity of every event. A simple replacement then either loses history or makes the new chat look like a new lead.

Use separate concepts in your own data model:

conversation_id: your stable internal identity for the working conversation.
chat_alias: a Telegram identifier known to refer to that conversation, scoped to your tenant and bot.
active_chat_id: the current destination proposed for new operations, subject to current permissions and application policy.
received_chat_id: the actual ID recorded on a historical event; keep this value unchanged.

The scope is your integration's isolation rule, not Telegram's identifier format. Include tenant and bot context in lookups so one installation cannot accidentally attach evidence to another tenant's conversation. A unique constraint on scope plus alias should prevent the same alias from owning two internal conversations. With concurrent workers, you still need transactional checks; an in-memory lookup is not enough.

An alias preserves continuity of routing. It does not mean that two CRM people are the same person, that all deals should be merged, or that a message identifier from the old chat is valid in the new one. Preserve message references as their original chat-and-message pair. Test historical link or reply behavior separately instead of rewriting old message IDs on the strength of a chat migration alone.

For the wider integration problem, see handling repeated Telegram webhooks. Event deduplication remains necessary, but it solves a different problem: a migration can arrive as a new update and still concern the existing conversation.

Make migration one atomic local decision

Process the migration branch before a generic “unknown chat means create a CRM conversation” branch. Otherwise, a service message from the supergroup may create an unnecessary second record before your handler examines its migration fields.

Validate the update at your normal trusted intake boundary. Persist the incoming evidence and its source event key. A user's text containing an ID is not equivalent to a Telegram migration field.
Extract the old and new IDs using the table above. Reject malformed values and self-mappings. Retain which field supplied the relationship.
In a database transaction, lock or otherwise serialize the scoped alias records involved. Read their current conversation ownership again inside that transaction.
If the old alias has one owner and the new alias is unclaimed, attach the new alias to the existing conversation. Record the migration relationship and update its active destination.
If both aliases already belong to the same conversation, treat the operation as a repeat. Preserve the evidence, but do not create another CRM object or notification job.
If the aliases belong to different conversations, quarantine the operation for reconciliation. Do not choose the newer row, overwrite a foreign key or delete either conversation automatically.
Commit the mapping and any local follow-up job together. Only then acknowledge or finish the corresponding processing step according to your intake contract.

If neither alias is known, store unresolved evidence or use an explicit onboarding rule approved for that group. Do not guess which existing CRM record should own it based on the group title. If only the new alias is known, link the old alias only after the same scope and evidence checks; a reverse lookup is not permission to overwrite a conflict.

A database transaction does not include a remote CRM write. If the CRM also stores the active destination, update it through a separately tracked operation and retain its result. After an ambiguous timeout, reconcile the actual result instead of assuming the update failed. The local alias table should remain the routing authority while the external projection catches up under a documented policy.

Check direction, repeats and conflicts locally

Save this example as migration_check.py and run python3 migration_check.py. It uses only the Python standard library, artificial IDs and process memory. It never calls Telegram or a CRM and does not create a database. The scope tuple represents one tenant and one bot. The two message dictionaries are deliberately simplified input fixtures, not recordings from a real group.


def pair(message):
    chat = message["chat"]["id"]
    if "migrate_to_chat_id" in message:
        return chat, message["migrate_to_chat_id"]
    if "migrate_from_chat_id" in message:
        return message["migrate_from_chat_id"], chat
    raise ValueError("no migration field")


def apply(aliases, scope, old, new):
    if type(old) is not int or type(new) is not int or old == new:
        raise ValueError("invalid pair")
    before = aliases.get((scope, old))
    after = aliases.get((scope, new))
    if before is None:
        raise ValueError("old alias needs reconciliation")
    if after is not None and after != before:
        raise ValueError("conversation conflict")
    aliases[(scope, new)] = before
    return before


scope = ("tenant-demo", "bot-demo")
old, new = -12345, -1009876543210
left = {"chat": {"id": old}, "migrate_to_chat_id": new}
right = {"chat": {"id": new}, "migrate_from_chat_id": old}
assert pair(left) == pair(right) == (old, new)
aliases = {(scope, old): "conversation-A"}
assert apply(aliases, scope, *pair(left)) == "conversation-A"
assert apply(aliases, scope, *pair(right)) == "conversation-A"
assert len(aliases) == 2
aliases[(scope, -1001111111111)] = "conversation-B"
try:
    apply(aliases, scope, old, -1001111111111)
except ValueError as exc:
    assert str(exc) == "conversation conflict"
else:
    raise AssertionError("conflict accepted")
assert aliases[(scope, -1001111111111)] == "conversation-B"
try:
    apply(aliases, ("other-tenant", "bot-demo"), old, new)
except ValueError as exc:
    assert str(exc) == "old alias needs reconciliation"
else:
    raise AssertionError("scope crossed")
print("direction=ok repeat=ok conflict=blocked scope=isolated")

The expected final line is direction=ok repeat=ok conflict=blocked scope=isolated. A failed assertion means the checked policy has not held; do not remove the assertion just to get the line. The example intentionally stops on an unknown old alias. It does not implement the optional reverse-linking or onboarding paths described above.

This check establishes field direction and a small sequential policy only. It does not validate a full Telegram update schema, integer bounds, authenticated intake, concurrent transactions, durable recovery, active-destination changes or the remote CRM projection. Add those checks at the layers that actually implement them. Keeping the example small makes its result inspectable instead of presenting a toy dictionary as a production integration.

Resolve queued work without erasing its history

Old jobs may still contain the old chat ID. Deleting them loses work; changing every historical payload obscures what originally happened. Prefer storing a stable conversation reference on the job and resolving its current destination at execution time. Record both the originally requested destination and the resolved destination in the operation receipt.

Before sending, verify that the bot still has the required access and that the operation remains appropriate for the conversation. A migration alias alone does not establish current membership or posting permission. Do not automatically replay an operation whose earlier delivery result is unknown: resolving a destination does not determine whether a message was already sent.

If your system follows alias chains, impose a hop limit and detect cycles. A repeated mapping from old to new should not create a reverse edge just because migrate_from_chat_id was observed. Both service-message forms express a direction from old to new. If a chain conflicts with current ownership or loops, stop routing that job and preserve the evidence for an operator. A fixed hop limit is your safety policy, not a Telegram migration limit.

Cached destinations need a clear invalidation strategy. Otherwise, the database can be correct while a worker continues using an obsolete address. In staging, make one worker hold an old cached value and check how the migration version or cache expiry causes it to reload. Do not claim this is solved because a single fresh process finds the new row.

Diagnose the failure before editing CRM records

Observation	Check next	Avoid
Structured migration target in a failed response	Match it to the stored request and scoped conversation	Parsing any error text as a new ID
New-group traffic creates a second conversation	Handler ordering and alias lookup	Deleting the new record before checking ownership
Database has the new ID, worker sends to the old one	Queue resolution and cache invalidation	Replaying every queued operation
New alias belongs to another conversation	Tenant/bot scope and previous onboarding	Automatic conversation merge
New destination still rejects an operation	Current permissions and the actual error	Treating migration as a blanket access repair

An operator should be able to see the source evidence, both IDs, conversation ownership and the decision without opening entire message histories. Log only the metadata required for diagnosis under your retention policy. Keep bot tokens and unnecessary personal data out of operational receipts.

Verify the real integration before resuming work

Back up the affected mapping records and test in an authorized staging group. Deliver the same migration evidence sequentially and concurrently: there should be one ownership decision and no duplicate local job. Stop the worker after the transaction commits, restart it, and confirm that unfinished projection work can resume. Introduce an explicit ownership conflict and check that neither conversation is silently reassigned.

Then inspect an old queued job. Its historical source ID should remain intact, its resolved destination should follow the accepted mapping, and its prior delivery state should still determine whether it may run. Check the CRM projection separately from the alias table. Finally, verify an ordinary authorized interaction in the current group and record what actually happened; a local test line is not evidence of delivery.

The rollout is ready only when continuity, isolation and failure handling have all been observed in your own stack. If trustworthy evidence does not establish the old-to-new relationship, leave the mapping unresolved. Pausing one route with a clear reason is safer than attaching a working group to the wrong customer record.

This article was also published on other platforms. Original: Telegram Group Migration: Keep CRM Routing When the Chat ID Changes

Миграция группы Telegram: как сохранить привязку к CRM при смене chat_id [перекрёстная публикация]

ALEKSANDR MICHAILOVICH — Wed, 28 Oct 2026 02:36:08 +0000

Миграция группы Telegram: как сохранить привязку к CRM при смене chat_id

После преобразования группы Telegram в супергруппу не считайте новый chat_id новой беседой с клиентом. Зафиксируйте связь старого и нового идентификаторов, сохраните внутренний идентификатор беседы, а перед разрешённой отправкой определяйте её текущий адрес. Если два chat_id уже принадлежат разным беседам, остановите автоматическую обработку и разберите конфликт вместо того, чтобы незаметно объединять карточки.

Это руководство предназначено разработчику собственной интеграции Telegram Bot API с CRM. Предполагаются бот, законно добавленный в рабочую группу, проверка входящих запросов, постоянное хранилище и тестовое окружение. Описанный подход не является подтверждённой встроенной функцией 24go.site. Для него не нужны сбор участников или нежелательные рассылки. Группа не равна отдельному контакту, а сохранение её истории не даёт нового согласия на обращения к участникам.

В какую сторону читать поля миграции

В официальном описании Message указаны два необязательных поля. Они показывают одну связь с разных сторон:

Полученное свидетельство	Старый ID группы	Новый ID супергруппы
Сообщение с `migrate_to_chat_id`	`chat.id` этого сообщения	Значение `migrate_to_chat_id`
Сообщение с `migrate_from_chat_id`	Значение `migrate_from_chat_id`	`chat.id` этого сообщения
Неуспешный запрос с `parameters.migrate_to_chat_id`	`chat_id`, использованный именно в этом запросе	Значение параметра

Третья строка относится к ResponseParameters, а не к телу служебного сообщения. Сохраняйте контекст запроса: без исходного адреса ответ с ошибкой не определяет оба конца связи. Не извлекайте старый идентификатор из переведённого описания ошибки. Ветвитесь по документированному структурному полю, а не по конкретной английской фразе или любому HTTP 400.

Поля необязательны. Обработчик должен выдерживать ситуацию, когда обнаружено только одно направление, эквивалентные сведения пришли повторно или сведения о миграции получены уже после обычного события из новой группы. Не требуйте, чтобы два служебных сообщения пришли вместе или в предполагаемом порядке. Это защитное правило обработки, а не утверждение, что каждая установка обязательно встретит все перечисленные ситуации.

Храните идентификаторы без сужения до 32-битного целого. Telegram указывает, что у migration ID может быть больше 32 значащих бит, но не больше 52. Знаковое 64-битное целое в БД - прямой вариант хранения. Если пользовательское поле CRM не сохраняет такое целое точно, используйте на этой границе проверенную десятичную строку и проверьте обратное преобразование. Не вычисляйте новый ID, добавляя префикс к старому: используйте значение, переданное Telegram.

Отделите беседу от транспортного адреса

Хрупкая схема использует chat_id одновременно как ключ беседы в CRM, адрес уведомлений и историческую принадлежность каждого события. Простая замена тогда либо стирает происхождение старых данных, либо превращает новую группу в новый лид.

В своей модели разделите четыре понятия:

conversation_id - стабильный внутренний идентификатор рабочей беседы.
chat_alias - идентификатор Telegram, который относится к этой беседе в пределах вашего клиента системы и бота.
active_chat_id - текущий адрес для новых операций; его применимость всё равно зависит от актуальных прав и правил приложения.
received_chat_id - фактический ID, записанный в историческом событии; его не переписывают.

Область изоляции задаёт ваша интеграция, а не формат Telegram ID. Включайте tenant и bot в ключи поиска, чтобы одна установка не могла случайно привязать свидетельство к беседе другого клиента системы. Уникальное ограничение по области и alias должно запрещать принадлежность одного alias двум внутренним беседам. При нескольких обработчиках нужны транзакционные проверки: словарь в памяти их не заменяет.

Alias сохраняет непрерывность маршрутизации. Он не доказывает, что два человека в CRM - один человек, что все сделки нужно объединить или что идентификатор сообщения старого чата действителен в новом. Сохраняйте ссылки на сообщения как исходную пару «чат-сообщение». Поведение старых ссылок и ответов проверяйте отдельно, а не переписывайте message_id только на основании миграции чата.

Общую задачу повторной доставки разбирает материал о повторных вебхуках Telegram. Дедупликация событий по-прежнему нужна, но решает другой вопрос: миграция может прийти как новый update и при этом относиться к существующей беседе.

Принимайте решение о миграции атомарно

Ветку миграции обрабатывайте раньше универсального правила «неизвестный чат - создать беседу в CRM». Иначе служебное сообщение из супергруппы может создать ненужную карточку до того, как обработчик проверит поля миграции.

Проверьте обновление на обычной доверенной границе приёма. Сохраните входящее свидетельство и ключ исходного события. Текст пользователя с каким-либо ID не равен структурному полю миграции Telegram.
Извлеките старый и новый ID по таблице. Отклоните некорректные значения и случай, когда старый и новый ID одинаковы. Сохраните, какое поле подтвердило связь.
В транзакции БД заблокируйте затронутые scoped alias или иным способом сериализуйте работу с ними. Заново прочитайте принадлежность обоих alias внутри транзакции.
Если у старого alias одна беседа, а новый свободен, привяжите новый alias к существующей беседе. Запишите связь миграции и обновите активный адрес беседы.
Если оба alias уже принадлежат той же беседе, считайте операцию повтором. Сохраните свидетельство, но не создавайте новый объект CRM или новое задание уведомления.
Если alias принадлежат разным беседам, отправьте операцию на сверку. Не выбирайте более свежую строку, не перезаписывайте внешний ключ и не удаляйте одну беседу автоматически.
Зафиксируйте привязку и локальное последующее задание вместе. Только после этого подтверждайте соответствующий шаг обработки согласно контракту вашего приёмника.

Если неизвестны оба alias, сохраните неразрешённое свидетельство либо примените отдельное правило подключения, согласованное для этой группы. Не угадывайте владельца среди существующих карточек по названию группы. Если известен только новый alias, старый можно привязать после тех же проверок области и свидетельства; обратный поиск не разрешает перезаписывать конфликт.

Транзакция вашей БД не охватывает удалённую запись в CRM. Если CRM тоже хранит текущий адрес, обновляйте его отдельной отслеживаемой операцией и сохраняйте её результат. После неоднозначного таймаута сначала установите фактический результат, а не считайте запись неудачной. Таблица alias должна оставаться источником маршрутизации, пока внешняя копия догоняет её по заранее определённому правилу.

Локально проверьте направление, повтор и конфликт

Сохраните пример в migration_check.py и выполните python3 migration_check.py. Нужна только стандартная библиотека Python; используются искусственные ID и память процесса. Пример не обращается к Telegram или CRM и не создаёт базу данных. Кортеж scope обозначает одного клиента системы и одного бота. Два словаря сообщений - намеренно упрощённые входные данные, а не записи событий реальной группы.


def pair(message):
    chat = message["chat"]["id"]
    if "migrate_to_chat_id" in message:
        return chat, message["migrate_to_chat_id"]
    if "migrate_from_chat_id" in message:
        return message["migrate_from_chat_id"], chat
    raise ValueError("no migration field")


def apply(aliases, scope, old, new):
    if type(old) is not int or type(new) is not int or old == new:
        raise ValueError("invalid pair")
    before = aliases.get((scope, old))
    after = aliases.get((scope, new))
    if before is None:
        raise ValueError("old alias needs reconciliation")
    if after is not None and after != before:
        raise ValueError("conversation conflict")
    aliases[(scope, new)] = before
    return before


scope = ("tenant-demo", "bot-demo")
old, new = -12345, -1009876543210
left = {"chat": {"id": old}, "migrate_to_chat_id": new}
right = {"chat": {"id": new}, "migrate_from_chat_id": old}
assert pair(left) == pair(right) == (old, new)
aliases = {(scope, old): "conversation-A"}
assert apply(aliases, scope, *pair(left)) == "conversation-A"
assert apply(aliases, scope, *pair(right)) == "conversation-A"
assert len(aliases) == 2
aliases[(scope, -1001111111111)] = "conversation-B"
try:
    apply(aliases, scope, old, -1001111111111)
except ValueError as exc:
    assert str(exc) == "conversation conflict"
else:
    raise AssertionError("conflict accepted")
assert aliases[(scope, -1001111111111)] == "conversation-B"
try:
    apply(aliases, ("other-tenant", "bot-demo"), old, new)
except ValueError as exc:
    assert str(exc) == "old alias needs reconciliation"
else:
    raise AssertionError("scope crossed")
print("direction=ok repeat=ok conflict=blocked scope=isolated")

Ожидаемая последняя строка: direction=ok repeat=ok conflict=blocked scope=isolated. Ошибка assertion означает, что проверяемое правило не выдержано; не удаляйте проверку ради нужной строки. Пример намеренно останавливается при неизвестном старом alias. Он не реализует необязательные ветки обратной привязки и первичного подключения, описанные выше.

Такая проверка устанавливает направление полей и небольшое последовательное правило. Она не проверяет полную схему Telegram update, допустимый диапазон целых чисел, доверенный приём, конкурентные транзакции, восстановление после сбоя, смену активного адреса или внешнюю копию в CRM. Эти проверки добавляют на тех уровнях, где соответствующее поведение действительно реализовано. Небольшой пример позволяет проверить результат, не выдавая учебный словарь за промышленную интеграцию.

Обновляйте маршрут задания, а не его прошлое

В очереди могут остаться задания со старым chat_id. Удаление таких заданий теряет работу, а массовая замена исторических payload скрывает исходные обстоятельства. Предпочтительно хранить в задании стабильную ссылку на беседу и определять текущий адрес при исполнении. В квитанции операции записывайте и первоначально запрошенный адрес, и фактически выбранный.

До отправки проверьте, что у бота остался нужный доступ, а сама операция по-прежнему уместна в этой беседе. Alias миграции не устанавливает актуальное членство или разрешение на публикацию. Не повторяйте автоматически операцию с неизвестным предыдущим результатом доставки: определение адреса не отвечает на вопрос, было ли сообщение уже отправлено.

Если система проходит цепочки alias, ограничьте число переходов и обнаруживайте циклы. Повтор связи старого ID с новым не должен создавать обратное ребро только потому, что встретилось migrate_from_chat_id. Оба вида служебного сообщения задают направление от старого к новому. Если цепочка зацикливается или противоречит принадлежности беседы, остановите задание и сохраните свидетельства для оператора. Ограничение числа переходов - ваше защитное правило, а не заявленный лимит миграций Telegram.

Для закешированных адресов нужен ясный способ сброса. Иначе данные в БД могут быть верными, а обработчик продолжит обращаться по старому адресу. В тестовом окружении оставьте одному обработчику старое значение в кеше и проверьте, как версия миграции или истечение срока кеша заставляет перечитать запись. Успешный поиск в новом процессе не доказывает, что обновился старый кеш.

Прежде чем править CRM, определите причину

Наблюдение	Следующая проверка	Чего избегать
В ошибке есть структурный migration target	Связать его с сохранённым запросом и scoped беседой	Получать новый ID из любого текста ошибки
Трафик новой группы создаёт вторую беседу	Порядок веток обработчика и поиск alias	Удалять новую карточку до проверки принадлежности
В БД новый ID, обработчик отправляет на старый	Выбор адреса в очереди и сброс кеша	Повторять все задания подряд
Новый alias занят другой беседой	Область tenant/bot и предыдущее подключение	Автоматически объединять беседы
Новый адрес всё равно отклоняет действие	Актуальные права и фактическая ошибка	Считать миграцию универсальным восстановлением доступа

Оператору нужны исходное свидетельство, оба ID, принадлежность бесед и принятое решение, а не доступ ко всей переписке. Записывайте только необходимые для диагностики метаданные согласно своей политике хранения. Не включайте токены бота и лишние персональные данные в технические квитанции.

Проверьте настоящую интеграцию до возобновления работы

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

Затем проверьте старое задание из очереди. Его исходный chat_id должен остаться неизменным в истории, текущий адрес должен определяться по принятой связи, а предыдущее состояние доставки должно по-прежнему влиять на решение о запуске. Отдельно проверьте внешнюю копию адреса в CRM, а не только таблицу alias. Наконец, выполните обычное разрешённое взаимодействие в текущей группе и запишите фактический результат: строка локального теста не подтверждает доставку.

Внедрение готово только после того, как непрерывность, изоляция и обработка ошибок проверены именно в вашем стеке. Если надёжное свидетельство не связывает старый ID с новым, оставьте привязку неразрешённой. Приостановить один маршрут с понятной причиной безопаснее, чем привязать рабочую группу к чужой карточке клиента.

Эта статья также опубликована на других платформах. Оригинал: Миграция группы Telegram: как сохранить привязку к CRM при смене chat_id

Telegram Bot Webhooks: Validate secret_token Before Queuing CRM Work [cross-post]

ALEKSANDR MICHAILOVICH — Tue, 27 Oct 2026 04:12:41 +0000

Telegram Bot Webhooks: Validate secret_token Before Queuing CRM Work

Check X-Telegram-Bot-Api-Secret-Token before interpreting a business event or writing a job to a queue. Your system chooses the expected value and supplies it to Telegram as secret_token when registering the webhook. A request without an accepted value must not start qualification, create a lead, or change a deal. A matching secret, however, neither establishes the user's permissions nor prevents repeated delivery.

This guide covers the ingress boundary of your own Telegram Bot API → receiver → queue → CRM integration. You need access to the receiver's code, configuration, and a test environment. It does not describe a verified built-in feature of 24go.site. The example uses invented public test values, runs locally, and neither contacts Telegram nor reads real secrets. It tests a receiver decision, not the security of an entire deployed service.

What secret_token actually checks

Telegram's setWebhook documentation defines an optional secret_token: a string of 1 to 256 characters using A-Z, a-z, 0-9, _, and -. When configured, Telegram includes that value in the X-Telegram-Bot-Api-Secret-Token header of every webhook request. Supplying the parameter during registration is only half the setup. Your receiver must enforce the header check.

This is a shared secret, not a signature over the message body. The documented mechanism does not include a signed timestamp or a single-use nonce. Someone who obtains the value can present it again; the header alone does not establish the freshness of the JSON or replace secret protection. Protect the connections and keep the value out of logs, traces, screenshots, and error messages.

Keep the webhook secret distinct from the bot token. The bot token is used to access the Bot API; this guide concerns a separate value for incoming requests. Separating them lets you replace the ingress secret without deliberately exposing the bot token. A leaked bot token remains a separate incident: replacing only the webhook secret does not address every consequence of compromised API access.

A successful check answers a narrow question: did this request present a secret accepted by this endpoint? It does not establish whether a particular Telegram user may change a particular deal. After accepting the event, you still need to check the actor, their access to the object, and whether the requested transition is allowed. A CRM record identifier in incoming JSON is not, by itself, permission to modify that record.

Reject before creating a side effect

Give the receiver an explicit sequence so a refusal cannot accidentally create work:

Limit request size and read time at the outer layer. You can check a header before application-level JSON parsing, but the HTTP server might already buffer the body. Server and proxy limits are still necessary.
Check that the method and route match your webhook endpoint. Do not redirect a request containing the secret to an arbitrary location or provide an alternative unprotected route.
Extract one secret header using the HTTP framework's normal facilities. Header names are case-insensitive; compare the value exactly, without changing its case or trimming whitespace.
Validate the receiver configuration. An empty expected value is a configuration error, not permission to accept requests without credentials. Prefer detecting this at startup and withholding readiness.
On mismatch, stop without queuing a job or calling the CRM. Do not return the expected value or comparison details to the caller.
Only then parse JSON, validate the event structure, and pass the event to durable storage. The successful HTTP acknowledgement must match the storage guarantee your system actually provides.

The status codes below are our example policy, not mandatory Telegram choices: 403 for a failed secret check, 503 for missing configuration, and 202 for the decision “allow the next step.” A real handler must not send that final response before successfully preserving the event. If storage fails, authorization may have succeeded, but the request as a whole has not yet been accepted.

Telegram documents retries after responses outside the 2XY range. Rejecting legitimate events because of a configuration mismatch can therefore trigger repeated delivery. Do not hide the problem with an unconditional 200: that can conceal event loss. Restore matching configuration and receiver readiness, then verify that the event flow has recovered. This guide does not assume a precise retry schedule.

A receiver decision table

Condition	Decision before the queue	What the operator checks
Expected secret is absent	Do not accept; instance is not ready	Configuration delivery to every instance
Header is missing or empty	Reject without business actions	Webhook registration and proxy forwarding
Value differs by one character	Reject; do not try to repair it	Registered and expected configuration versions
Value has extra whitespace	Reject under this exact-match policy	Configuration serialization; do not add trimming as a workaround
Secret is correct but JSON is invalid	Authentication passed; event not accepted	Separate body limits and schema checks
Secret is correct and event was already stored	Apply deduplication	Stable event key and existing processing record
Secret is correct but actor lacks permission	Do not execute the forbidden action	Business authorization, not the transport secret

Define a separate policy for duplicate secret headers. Reject ambiguous input at an agreed layer and test the actual HTTP stack. Servers can expose repeated fields as a list, a combined string, or a selected value. A function that takes one string cannot establish how duplicate headers behave across your network path.

A local test without a real secret

Save this as ingress_check.py and run python3 ingress_check.py. It uses only the Python 3 standard library: no packages, bot, network, or CRM. Every value shown is public test data and must not be copied into production configuration. The function receives the already-extracted header value, not raw HTTP bytes.

Python's documentation describes hmac.compare_digest as avoiding content-based short-circuit comparison. String arguments must be ASCII, so the example first checks the type and permitted alphabet. This is not a claim that the entire network service is immune to timing analysis. The documentation separately notes information that differences in argument types and lengths could reveal.

import hmac
import re

TOKEN = re.compile(r"[A-Za-z0-9_-]{1,256}")


def decision(received, expected):
    if not isinstance(expected, str) or not TOKEN.fullmatch(expected):
        return 503
    if not isinstance(received, str) or not TOKEN.fullmatch(received):
        return 403
    return 202 if hmac.compare_digest(received, expected) else 403


def run_checks():
    expected = "Demo_receiver_token_123"
    cases = [
        ("match", expected, expected, 202),
        ("missing", None, expected, 403),
        ("empty", "", expected, 403),
        ("wrong", "Demo_receiver_token_124", expected, 403),
        ("space", expected + " ", expected, 403),
        ("unicode", "token_я", expected, 403),
        ("too_long", "A" * 257, expected, 403),
        ("bad_config", expected, "", 503),
        ("repeat", expected, expected, 202),
    ]
    queued = []
    for label, received, configured, want in cases:
        status = decision(received, configured)
        assert status == want, (label, status, want)
        if status == 202:
            queued.append(label)
        print(f"{label}: {status}")
    assert queued == ["match", "repeat"]
    print("accepted_for_next_step:", len(queued))


if __name__ == "__main__":
    run_checks()

The local execution checked nine cases. match and repeat returned 202; six invalid incoming values returned 403; empty configuration returned 503. The final line was accepted_for_next_step: 2. Here, queued is only a list counting permission to continue, not a real queue. The repeated value is deliberately accepted again: secret comparison stores no event history. This result shows the boundary of the check, not a problem that rotation solves.

Use a separate event key and durable storage to handle repeated deliveries. The Telegram-to-CRM idempotency guide covers that stage. Do not treat the secret and update_id as interchangeable controls: one limits entry, while the other helps distinguish deliveries of an already accepted event.

Check the reverse-proxy boundary

A reverse proxy receives the external HTTP request and forwards it to the application. Draw the actual route: public address → TLS termination → proxy or load balancer → specific handler. For each segment, identify who can connect and where the secret is checked. HTTPS on the public address alone says nothing about whether an internal application port is reachable by an unintended caller.

Check that clients cannot bypass the protective layer and reach the application directly. If only the proxy validates the secret, direct backend access without the same check bypasses that boundary. If the application validates it, the proxy must preserve the incoming value. Do not configure the proxy to insert the correct secret unconditionally into every external request: that would give an arbitrary client a trusted header inside your infrastructure.

The official aiogram webhook example supplies secret_token both when registering the webhook and when constructing SimpleRequestHandler. It also shows a web server bound to localhost behind a proxy. These are useful inspection points, not a universal deployment recipe. Container networking or a separate load balancer may require a different bind address and appropriate network restrictions. Verify the behavior of the framework version you actually run.

In a test deployment, send a request with a deliberately incorrect test value through the public address and confirm that no job appears in storage. Repeat through any accessible internal route within the authorized scope of your infrastructure. With the correct test value, check a different outcome: whether the request reaches the handler that validates and persists the event. These network checks were not performed for this guide. A local function cannot detect a dropped proxy header, an exposed backend port, or a wrongly routed endpoint.

Rotate without leaving a permanent spare entrance

Rotation means coordinating a replacement of the accepted value and the webhook registration parameter. Treat it as a distributed configuration change: instances can update at different times, and previously sent requests may still be in flight. The cited Telegram contract does not promise an atomic changeover of every delivery to a new configuration.

For a planned replacement, prepare the new secret in your approved secret store and make the receiver configuration available to every instance. If you choose to accept two values temporarily, specify a bounded overlap window, an owner, and the removal point for the old value. Register the new value through the existing secure bot-management tool and verify fresh test events. After changeover, remove the old value from every receiver and confirm rejection using the old test value. This is an operational proposal, not a built-in automatic Telegram rotation feature.

If the old secret may have leaked, overlap extends the period in which someone can use it. Work with the incident owner to decide whether to revoke it immediately, accepting a temporary interruption if necessary. Do not switch to “accept anything while we investigate.” Also, do not use drop_pending_updates merely to make an error disappear. Telegram documents that option as dropping pending updates, not repairing authentication.

Keep working values out of article commands, shell history, and tickets. Record the configuration version, changeover time, and test outcome, not the secret itself. Separately inspect how your management tool retrieves and passes the value. A general guide cannot establish that it never appears in process arguments or debug logs.

Diagnose refusals and establish readiness

When refusals increase after a change, first establish which layer generated the response: an external protection service, the proxy, the HTTP framework, or your check. A 403 by itself does not establish a bad secret_token. Correlate request time and trace identifier without copying sensitive headers. Check the selected endpoint, configuration version on every instance, and header forwarding. Broader CRM permissions will not repair an ingress failure.

The Bot API's getWebhookInfo method reports webhook state, including the pending-update count and last-error details when present. It is a diagnostic source, not evidence of the secret expected by your application. Review the output before sharing it: webhook addresses and infrastructure details can also be sensitive.

Start operational monitoring with ingress-refusal counts, configuration failures, and the age of unprocessed events. A failed check must not automatically dump the entire conversation into logs. For an authorized request, separately track durable acceptance and work completion: transport authentication does not prove CRM success. Inspect the logging and metrics pipeline too, since it may capture sensitive headers independently of your handler.

Readiness for the next stage means an incorrect test secret creates no job through any reachable route, a correct one reaches format validation and storage, missing configuration prevents readiness, and a repeated valid request is handled by separate deduplication. Test user permissions and the actual CRM effect independently. These are observable checks of your own system, not a security guarantee or permission to collect contacts or send unsolicited messages.

This article was also published on other platforms. Original: Telegram Bot Webhooks: Validate secret_token Before Queuing CRM Work

Вебхук Telegram-бота: проверка secret_token до очереди и CRM [перекрёстная публикация]

ALEKSANDR MICHAILOVICH — Tue, 27 Oct 2026 04:12:39 +0000

Вебхук Telegram-бота: проверка secret_token до очереди и CRM

Проверяйте X-Telegram-Bot-Api-Secret-Token до разбора бизнес-события и записи задания в очередь. Ожидаемое значение задаётся на вашей стороне и передаётся Telegram при регистрации вебхука через secret_token. Запрос без подходящего значения не должен запускать квалификацию, создавать лид или менять сделку. Однако совпадение секрета не подтверждает права пользователя и не защищает от повторной доставки.

Ниже разобрана входная граница собственной интеграции Telegram Bot API → обработчик → очередь → CRM. Понадобятся доступ к коду приёмника, его настройкам и тестовому окружению. Это не инструкция по настройке проверенной встроенной функции 24go.site. Пример работает локально с вымышленными значениями, не обращается к Telegram и не читает настоящие секреты. Он проверяет решение приёмника, а не безопасность развёрнутого сервиса целиком.

Какую проверку даёт secret_token

В описании setWebhook Telegram документирует необязательный secret_token: строку длиной от 1 до 256 символов из A-Z, a-z, 0-9, _ и -. Если параметр задан, Telegram включает его в заголовок X-Telegram-Bot-Api-Secret-Token каждого webhook-запроса. Передать параметр при регистрации недостаточно: ваш приёмник должен действительно проверять заголовок.

Это общий секрет между отправителем и приёмником, а не подпись содержимого сообщения. В указанном контракте нет подписанного времени или одноразового nonce. Следовательно, тот, кто получил значение, может предъявить его повторно; сам заголовок не доказывает свежесть JSON и не заменяет защиту ключей. Защищайте соединения и не записывайте значение в журналы, трассировки, скриншоты или сообщения об ошибках.

Не путайте webhook secret с токеном бота. Токен бота используется для доступа к Bot API; здесь обсуждается отдельное значение для входящих запросов. Разделение позволяет менять входной секрет, не раскрывая намеренно токен бота. Но утечку токена бота нужно разбирать отдельно: замена только webhook secret не устраняет все последствия компрометации доступа к API.

Успешная проверка отвечает на узкий вопрос: предъявлен ли секрет, который принимает этот endpoint? Она не отвечает на вопрос, имеет ли конкретный Telegram-пользователь право менять данную сделку. После приёма события всё ещё нужно проверить отправителя, его доступ к объекту и допустимость действия. Нельзя считать идентификатор CRM из входящего JSON достаточным разрешением на изменение записи.

Поставьте отказ перед побочным эффектом

Задайте последовательность обработки так, чтобы отказ не успевал создать работу:

На внешнем слое ограничьте размер запроса и время чтения. Заголовок можно проверить до прикладного разбора JSON, но HTTP-сервер всё равно может буферизовать тело. Ограничения на сервере и прокси остаются необходимыми.
Убедитесь, что метод и маршрут соответствуют вашему webhook endpoint. Не перенаправляйте запрос с секретом на произвольный адрес и не создавайте запасной маршрут без той же проверки.
Извлеките один заголовок секрета штатными средствами HTTP-фреймворка. Имена HTTP-заголовков регистронезависимы; значение секрета сравнивайте точно, не меняя регистр и не удаляя пробелы.
Проверьте конфигурацию приёмника. Пустое ожидаемое значение - ошибка настройки, а не разрешение принимать запросы без секрета. Лучше обнаружить её при запуске и не объявлять экземпляр готовым.
При несовпадении завершите обработку без постановки задания и без вызова CRM. Не возвращайте клиенту ожидаемое значение или подробности сравнения.
Только после этого разбирайте JSON, проверяйте его структуру и передавайте событие в надёжное хранилище. Успешное HTTP-подтверждение должно соответствовать фактической гарантии сохранения в вашей системе.

Коды ответа ниже - наша примерная политика, а не обязательный выбор Telegram: 403 для проверки секрета, завершившейся отказом, 503 при отсутствии настройки и 202 как решение «разрешить следующий шаг». В реальном обработчике последний код нельзя отправлять до успешного сохранения события. Если хранилище недоступно, авторизация могла пройти, но запрос ещё не принят целиком.

Telegram описывает повтор запросов при ответе не из диапазона 2XY. Поэтому отказ на настоящем событии из-за ошибки конфигурации может вызвать повторные доставки. Не «чините» это безусловным 200: так можно скрыть потерю события. Восстановите согласованность секрета и готовность приёмника, затем проверьте, что поток событий возобновился. Точные сроки повторов здесь не предполагаются.

Таблица решений для приёмника

Условие	Решение до очереди	Что проверять оператору
Ожидаемый секрет отсутствует	Не принимать; экземпляр не готов	Доставку настройки всем экземплярам
Заголовка нет или значение пустое	Отклонить без бизнес-действий	Регистрацию вебхука и передачу заголовка прокси
Значение отличается на один символ	Отклонить, не исправлять автоматически	Согласованность зарегистрированной и ожидаемой версий
В значении есть лишний пробел	Отклонить по выбранной политике точного сравнения	Сериализацию настройки; не добавлять `strip()` как обход
Секрет верен, JSON некорректен	Авторизация прошла, событие не принято	Отдельные проверки формата и лимитов тела
Секрет верен, событие уже сохранено	Применить дедупликацию	Ключ события и существующую запись обработки
Секрет верен, пользователь не имеет прав	Не выполнять запрещённое действие	Бизнес-авторизацию, а не транспортный секрет

Политику для дублирующихся заголовков задайте отдельно: отклоняйте неоднозначный ввод на согласованном слое и тестируйте именно свой стек. Разные серверы могут представлять повторные поля списком, объединённой строкой или одним выбранным значением. Нельзя утверждать, что пример с одним строковым аргументом проверил поведение дублирующихся заголовков на сетевом пути.

Локальная проверка без настоящего секрета

Сохраните код в ingress_check.py и выполните python3 ingress_check.py. Нужна только стандартная библиотека Python 3; пакеты, бот, сеть и CRM не используются. Все строки ниже - публичные тестовые данные, их нельзя переносить в рабочую конфигурацию. Функция получает уже извлечённое значение заголовка, а не сырые HTTP-байты.

В документации Python указано, что hmac.compare_digest позволяет избежать короткого замыкания сравнения по содержимому. Строковые аргументы должны состоять из ASCII-символов, поэтому пример сначала проверяет тип и допустимый алфавит. Это не обещание полной защиты сетевого сервиса от анализа времени: документация отдельно оговаривает возможные утечки при различии типов и длин аргументов.

import hmac
import re

TOKEN = re.compile(r"[A-Za-z0-9_-]{1,256}")


def decision(received, expected):
    if not isinstance(expected, str) or not TOKEN.fullmatch(expected):
        return 503
    if not isinstance(received, str) or not TOKEN.fullmatch(received):
        return 403
    return 202 if hmac.compare_digest(received, expected) else 403


def run_checks():
    expected = "Demo_receiver_token_123"
    cases = [
        ("match", expected, expected, 202),
        ("missing", None, expected, 403),
        ("empty", "", expected, 403),
        ("wrong", "Demo_receiver_token_124", expected, 403),
        ("space", expected + " ", expected, 403),
        ("unicode", "token_я", expected, 403),
        ("too_long", "A" * 257, expected, 403),
        ("bad_config", expected, "", 503),
        ("repeat", expected, expected, 202),
    ]
    queued = []
    for label, received, configured, want in cases:
        status = decision(received, configured)
        assert status == want, (label, status, want)
        if status == 202:
            queued.append(label)
        print(f"{label}: {status}")
    assert queued == ["match", "repeat"]
    print("accepted_for_next_step:", len(queued))


if __name__ == "__main__":
    run_checks()

В локальном запуске примера проверены девять случаев: match и repeat дают 202, шесть некорректных входных значений дают 403, пустая конфигурация - 503. Итоговая строка: accepted_for_next_step: 2. Список queued здесь лишь считает разрешения на следующий шаг и не является настоящей очередью. Повтор намеренно принимается ещё раз: сравнение секрета не хранит историю событий. Это показывает границу проверки, а не недостаток, который нужно исправлять ротацией.

Для обработки повторов используйте отдельный ключ события и постоянное хранилище. Этот этап подробнее разобран в руководстве по идемпотентности Telegram → CRM. Не объединяйте секрет и update_id в один критерий: первый ограничивает вход, второй помогает различать доставки уже принятого события.

Что меняется за обратным прокси

Обратный прокси принимает внешний HTTP-запрос и пересылает его приложению. Составьте схему реального пути: публичный адрес → TLS termination → прокси или балансировщик → конкретный обработчик. Для каждого участка определите, кто может подключиться и где проверяется заголовок. Наличие HTTPS на публичном адресе само по себе ничего не говорит о доступности внутреннего порта.

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

В официальном примере aiogram secret_token передаётся и при регистрации webhook, и при создании SimpleRequestHandler. Там же показан web-сервер, привязанный к localhost за прокси. Это полезные точки для проверки, а не универсальная схема развёртывания. Контейнерная сеть или отдельный балансировщик могут потребовать другой адрес привязки и соответствующие сетевые ограничения. Проверьте поведение именно той версии фреймворка, которую используете.

В тестовом развёртывании отправьте через публичный адрес запрос с заведомо неверным тестовым значением и убедитесь, что в хранилище не появилось задания. Повторите проверку через любой доступный внутренний маршрут, не выходя за разрешённые пределы своей инфраструктуры. Затем проверьте другой результат с правильным тестовым значением: доходит ли запрос до обработчика, который проверяет и сохраняет событие. Эти сетевые проверки здесь не выполнялись. Локальная функция не обнаружит потерю заголовка на прокси, открытый внутренний порт или неверно настроенный маршрут.

Ротация без постоянного запасного входа

Ротация означает согласованную замену принимаемого значения и параметра регистрации webhook. Планируйте её как изменение распределённой системы: экземпляры могут обновиться в разное время, а ранее отправленные запросы ещё могут находиться в пути. Приведённый контракт Telegram не обещает атомарного переключения всех доставок на новую конфигурацию.

Для плановой замены подготовьте новый секрет в разрешённом хранилище и доставьте конфигурацию всем экземплярам приёмника. Если временно принимаются два значения, явно определите ограниченное окно, ответственного за изменение и момент удаления старого значения. Затем зарегистрируйте новое значение через существующий безопасный инструмент управления ботом и проверьте поступление новых тестовых событий. После переключения удалите старое значение на всех экземплярах и подтвердите отказ при запросе со старым тестовым значением. Это эксплуатационная рекомендация, а не встроенная функция автоматической ротации Telegram.

Если старый секрет мог утечь, окно совместимости продлевает возможность его использования. Вместе с ответственным за инцидент решите, нужно ли немедленно отозвать старое значение, даже если это приведёт к временному перерыву. Не переходите к режиму «принимать всё, пока разбираемся». Не используйте и drop_pending_updates только для того, чтобы убрать ошибку: в документации эта настройка описана как удаление ожидающих обновлений, а не как исправление авторизации.

Не вставляйте рабочие значения в команды из статьи, историю shell или тикеты. Записывайте версию конфигурации, время переключения и результат проверки, но не сам секрет. Отдельно проверьте, как инструмент управления получает и передаёт значение. Общее руководство не подтверждает, что секрет не появляется в аргументах процесса или отладочных журналах.

Как разбирать отказы и определять готовность

Если после изменения стало больше отказов, сначала выясните, на каком уровне сформирован ответ: внешним защитным сервисом, прокси, HTTP-фреймворком или вашим проверяющим кодом. Один 403 сам по себе не доказывает, что неверен secret_token. Сопоставьте время запроса и идентификатор трассировки, не копируя чувствительные заголовки. Проверьте выбранный endpoint, версию настройки на каждом экземпляре и передачу заголовка. Расширение прав CRM не исправит ошибку на входе.

Метод getWebhookInfo в Bot API позволяет смотреть состояние вебхука, включая число ожидающих обновлений и сведения о последней ошибке, если они есть. Это источник диагностических данных, а не подтверждение значения секрета, которое ожидает приложение. Прежде чем делиться полным ответом, проверьте его: адрес вебхука и сведения об инфраструктуре тоже могут быть чувствительными.

Начните мониторинг со счётчиков отказов на входе, ошибок конфигурации и возраста необработанных событий. Отказ проверки не должен приводить к записи всей переписки в журналы. Для разрешённого запроса отдельно отслеживайте надёжное сохранение и выполнение работы: транспортная авторизация не доказывает успешную работу CRM. Проверьте также конвейер журналирования и метрик: он может записывать чувствительные заголовки независимо от обработчика.

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

Эта статья также опубликована на других платформах. Оригинал: Вебхук Telegram-бота: проверка secret_token до очереди и CRM

Telegram Bot Inline Buttons: Check Permissions and Reject Stale Actions [cross-post]

ALEKSANDR MICHAILOVICH — Tue, 27 Oct 2026 03:11:40 +0000

Telegram Bot Inline Buttons: Check Permissions and Reject Stale Actions

Do not update a CRM enquiry just because callback_data contains a command. Use the value to look up a server-side action record. Before making a change, check the sender, their current permissions, the button's expiry, the enquiry version, and whether the action has already run. A button sent yesterday is not permanent authority to change today's record.

This design is for developers building their own Telegram Bot API bot to handle inbound enquiries. It is not a 24go.site feature setup. The scope is ordinary callback buttons on messages in private chats. Inline mode, games, and Web Apps need separate handlers. At this point, the server must already authenticate update delivery and validate the JSON structure. Checks inside a forged request do not authenticate its user.

What a button press actually supplies

In CallbackQuery, from identifies the sender. A message sent by the bot supplies message; a message sent through inline mode supplies inline_message_id. Do not assume every callback contains an ordinary, accessible message.

The documentation explicitly warns that the originating message may contain no buttons with the received data. Looking for a matching string in the current keyboard therefore does not replace a server-side check. A label such as “Confirm demo” is not authorization either.

InlineKeyboardButton limits callback_data to 1-64 bytes. In a production design, use a short, unpredictable identifier rather than a phone number, staff role, or full enquiry JSON. Check the UTF-8 byte length, not the character count. The identifier does not replace permission checks: even a known, valid key must work only in an authorized context.

It helps to distinguish three things when handling a callback: the callback data, the message context, and the server-side action record. The first helps locate an action, the second supports context checks, and the third defines exactly which operation may run. Neither the visible button label nor the presence of a similar button in the interface proves that the operation is still authorized.

Do not use callback_data to carry the entire business command. Apart from the length limit, doing so makes revoking permission harder and can expose data in logs or during mishandling. The server-side record should remain the source of truth. Even if an identifier is guessed or copied, all the other checks still apply.

Keep the action's meaning on the server

When issuing a button, store a record containing its key, internal enquiry ID, allowed operation, intended Telegram user ID, enquiry version, expiry, and execution state. Bind the record to the appropriate bot and, where needed, to the chat and message. The application chooses the lifetime; Telegram does not define the business expiry used here.

Resolve permissions from current server-side records, not from a role embedded in a button. If an employee loses access or the enquiry moves to another team, an old button must not restore that access. For a customer-facing bot, first establish a link between the Telegram user and the specific enquiry. A matching username or knowledge of an enquiry number does not establish that link.

Check	On failure
Is the message context supported?	Do not act; ask the user to open the current conversation
Does the server recognize the key?	Do not reconstruct commands from an arbitrary string
Is the sender the action's intended owner?	Leave the enquiry unchanged and disclose no enquiry details
Does the user still have access?	Refuse, even if the button is still visible
Has the action expired?	Offer a way to request a new button
Has the action already completed?	Do not run it again; show the known result only if access is authorized
Are the enquiry version and state still suitable?	Reload the record and request fresh confirmation

For plan or price selection, keep the offer and its version on the server. If the terms have changed, show the new terms and ask for confirmation rather than silently applying a different price. This design is not a complete payment protocol.

The order of checks matters too. First reject unsupported contexts and unknown keys, then check the sender and their current permissions. Do not reveal a detailed rejection reason to someone who is not allowed to access the enquiry: messages such as “that enquiry does not exist” or “someone else owns it” may disclose information. Keep a structured reason in internal logs, but use a neutral response for the user.

If the user is authorized but the action has expired or the enquiry version has changed, do not automatically apply the old command to the new version. Load the current state, create a new action, and show the user what they are confirming. This is particularly important for changes to ownership, status, amount, meeting consent, or offer terms.

Expiry and version checks solve different problems. Expiry limits how long a particular button can be used. The version check detects whether the object has changed since the action was created. A longer expiry does not solve stale data, and a new version does not make an old key safe to use indefinitely.

Acknowledgement is not a successful write

Telegram clients display a progress indicator until answerCallbackQuery is called. Answer rejected callbacks too. For a longer operation, a neutral “Checking your request” is appropriate. Say “Enquiry updated” only after the result is confirmed. A successful Telegram method response does not confirm a CRM write.

Perform the version check, action claim, and local change atomically in a transaction. Otherwise, two handlers can both observe used: false. The function below does not protect against that race.

A local transaction cannot cover a request to a remote CRM. Persist a durable operation and use that CRM's documented idempotency mechanism, or reconcile an ambiguous timeout. Do not mark an action as finally completed before its effect is confirmed. The separate guide to repeated webhooks and duplicate CRM leads covers this boundary. A second click and redelivery of one event are different causes that may need to resolve to the same business operation.

Define in advance what each server-side action state means: awaiting checks, claimed by a handler, sent to an external system, confirmed, or requiring reconciliation. The names and storage model depend on the application; the important point is that a timeout must not become a confirmed success automatically. If the external request has an ambiguous outcome, retry only with a safe idempotency key or after checking the result with the CRM.

Avoid holding a database lock during a long network request unless your design requires it. One possible approach is to check permissions and version, atomically claim the action, and store a durable task in a transaction; then process the task separately and record the confirmed result. This is a general outline, not a ready-made design for every database and CRM. Choose transaction and recovery boundaries for the storage system you use.

A callback repeated after a successful operation must not start a new change. If access is still authorized, you can return the known result. If access has been revoked, do not disclose that result merely because the same user clicked the same button before. Check access when returning a result, too.

Test the refusal rules locally

Save the code as callback_policy_test.py and run python callback_policy_test.py without -O, which disables assert. It requires Python 3 and no additional libraries. This is a sequential decision test with artificial inputs, not a bot, storage implementation, or concurrency test. DEMO_ONLY is a public test string, not an example of a production secret key.

import copy
import json


def decide(query, action, lead, now):
    # Preconditions: authenticated delivery and validated object shapes.
    message = query.get("message")
    if not message or message.get("chat", {}).get("type") != "private":
        return "unsupported_context"
    if not action or query.get("data") != action["token"]:
        return "unknown_action"
    sender = query["from"]["id"]
    if type(sender) is not int or sender != action["owner_id"]:
        return "wrong_user"
    if sender not in lead["allowed_users"]:
        return "permission_denied"
    if now >= action["expires_at"]:
        return "expired"
    if action["used"]:
        return "already_used"
    if lead["version"] != action["lead_version"]:
        return "stale_version"
    if lead["status"] != "new" or action["kind"] != "request_demo":
        return "invalid_transition"
    return "eligible"


query = {"from": {"id": 1001}, "data": "DEMO_ONLY",
         "message": {"chat": {"type": "private"}}}
action = {"token": "DEMO_ONLY", "owner_id": 1001, "expires_at": 200,
          "used": False, "lead_version": 3, "kind": "request_demo"}
lead = {"allowed_users": [1001], "version": 3, "status": "new"}
results = [decide(query, action, lead, 100)]
q = copy.deepcopy(query)
q["from"]["id"] = 2002
results.append(decide(q, action, lead, 100))
results.append(decide(query, action, {**lead, "allowed_users": []}, 100))
results.append(decide(query, action, lead, 200))
results.append(decide(query, {**action, "used": True}, lead, 100))
results.append(decide(query, action, {**lead, "version": 4}, 100))
results.append(decide(query, None, lead, 100))
results.append(decide({**query, "message": None}, action, lead, 100))
results.append(decide(query, action, {**lead, "status": "closed"}, 100))
assert results == ["eligible", "wrong_user", "permission_denied", "expired",
                   "already_used", "stale_version", "unknown_action",
                   "unsupported_context", "invalid_transition"]
print(json.dumps(results))

Actual output from the local run:

["eligible", "wrong_user", "permission_denied", "expired", "already_used", "stale_version", "unknown_action", "unsupported_context", "invalid_transition"]

eligible means only that the displayed checks passed. The function does not write a record, consume a key, or perform a transaction. now and expires_at are illustrative numbers on one time scale. In production, use server time and a consistent expiry format. Validate input object shapes and expected types before calling the function.

If an AssertionError occurs, investigate which branch changed. Do not delete the assertion just to make the test pass. If the policy changes, update the expected results deliberately.

The test demonstrates individual rejection cases, but it does not cover every combination of conditions and is not a substitute for application tests. For example, it does not check a binding to a particular message, chat ID, or bot, because those details depend on the chosen action model. Add such checks to your tests if they are part of that model. Also test malformed types and missing fields at the handler boundary: the function explicitly assumes that input shapes have already been validated.

Before connecting the CRM

In a private test chat, press a valid button as its intended user. Only the allowed operation on the correct enquiry should be created.
Revoke the user's access, then press the old button. The enquiry must remain unchanged, and restricted details must not be disclosed.
Change the enquiry version or close it before the click. An old confirmation must not overwrite the newer state.
Test an expired action, an unknown key, and an unsupported context. Expect a refusal and an appropriate callback answer, not an unhandled exception.
Send two concurrent requests and repeat a completed action. Verify the database's atomic action claim and confirm there is no second business effect.
Simulate loss of the CRM response. Do not declare success or failure based on the timeout alone; recover the result through the durable operation.

Also test that two actions created for different versions of one enquiry cannot overwrite a newer state in sequence. Check that a repeated click on a used button returns an appropriate response without creating a second external request. For a concurrency test, use genuinely parallel handlers and the storage system that will run in the application: a sequential test of decide does not cover this.

Test the interface failure path as well. If the message containing the button is inaccessible, do not treat that as proof that the action succeeded or was cancelled. The server holds the business state; removing or updating a keyboard does not replace checking it. If the user can request a new confirmation, that confirmation must reflect the current terms and enquiry version.

These integration tests were not performed here. Decision reasons, internal operation IDs, and checked versions are usually sufficient for technical logs. Do not copy complete callbacks, personal data, or keys without a need. Removing the keyboard improves the interface but does not replace server-side rejection of stale actions. The system is ready when another user's or a stale click cannot change the enquiry, and a confirmed action cannot create a second effect.

This article was also published on other platforms. Original: Telegram Bot Inline Buttons: Check Permissions and Reject Stale Actions

Inline-кнопки Telegram-бота: проверка прав и устаревших действий [перекрёстная публикация]

ALEKSANDR MICHAILOVICH — Tue, 27 Oct 2026 03:11:38 +0000

Inline-кнопки Telegram-бота: проверка прав и устаревших действий

Не меняйте заявку в CRM только потому, что в callback_data пришла команда. Используйте это значение как ключ серверной записи действия. Перед изменением проверьте отправителя, его текущие права, срок действия кнопки, версию заявки и то, не было ли действие выполнено ранее. Кнопка, отправленная вчера, не даёт бессрочного разрешения менять сегодняшнюю заявку.

Это схема для разработчика собственного Telegram Bot API бота, который обрабатывает входящие обращения. Это не инструкция по настройке функции 24go.site. Рассматриваются обычные callback-кнопки в сообщениях личного чата. Для inline mode, игр и Web Apps нужны отдельные обработчики. К этому этапу сервер уже должен проверять подлинность доставки обновления и валидировать структуру JSON. Проверки внутри поддельного запроса не подтверждают личность пользователя.

Что действительно приходит при нажатии

В объекте CallbackQuery поле from обозначает отправителя нажатия. Для сообщения, отправленного ботом, предусмотрено поле message; для сообщения через inline mode используется inline_message_id. Нельзя рассчитывать, что любой callback содержит обычное доступное сообщение.

В документации отдельно сказано, что сообщение, из которого пришёл запрос, может не содержать кнопок с полученным data. Поэтому поиск этой строки в текущей клавиатуре не заменяет серверную проверку. Подпись «Подтвердить демо» тоже не даёт разрешения на запись.

У InlineKeyboardButton значение callback_data ограничено 1-64 байтами. В рабочей реализации удобно использовать короткий непредсказуемый идентификатор, а не телефон, роль менеджера или весь JSON заявки. Длину проверяют в байтах UTF-8, а не по числу символов. Сам идентификатор не заменяет проверку прав: даже известный действительный ключ должен работать только в разрешённом контексте.

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

Не используйте callback_data как место для хранения всей бизнес-команды. Помимо ограничения длины, это усложняет отзыв разрешения и создаёт риск раскрытия данных в логах или при ошибочной обработке. Серверная запись должна оставаться источником истины. Даже если идентификатор случайно угадан или скопирован, остальные проверки всё равно обязательны.

Храните смысл действия на сервере

При создании кнопки сохраните запись с ключом, внутренним ID заявки, разрешённым видом операции, Telegram ID предполагаемого пользователя, версией заявки, сроком действия и состоянием выполнения. Привяжите запись к нужному боту и, если необходимо, к чату и сообщению. Срок выбирает приложение: Telegram не задаёт описанный здесь бизнес-срок.

Проверяйте права по актуальным серверным данным, а не по роли, записанной в кнопке. Если сотрудник потерял доступ или заявка перешла в другую команду, старая кнопка не должна восстанавливать этот доступ. Для клиентского бота сначала установите связь между пользователем Telegram и конкретной заявкой. Совпадение username или знание номера заявки такую связь не подтверждает.

Проверка	Решение при отказе
Поддерживается ли контекст сообщения?	Не выполнять действие; предложить открыть актуальный диалог
Найден ли серверный ключ?	Не восстанавливать команду из произвольной строки
Совпадает ли отправитель с владельцем действия?	Не менять заявку и не раскрывать её данные
Сохранилось ли право доступа к заявке?	Отказать, даже если кнопка ещё видна
Истёк ли срок действия?	Предложить запросить новую кнопку
Действие уже выполнено?	Не выполнять повторно; показать известный результат, только если доступ разрешён
Подходят ли текущие версия и состояние заявки?	Загрузить запись заново и запросить подтверждение ещё раз

Для выбора тарифа или суммы храните предложение и его версию на сервере. Если условия изменились, покажите новые условия и запросите подтверждение, а не применяйте другую цену без уведомления. Эта схема не является готовым платёжным протоколом.

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

Если пользователь уполномочен, но запись действия истекла или версия заявки изменилась, не пытайтесь автоматически применить старую команду к новой версии. Загрузите актуальное состояние, сформируйте новое действие и покажите пользователю, что именно он подтверждает. Это особенно важно для операций, которые меняют ответственного, статус, сумму, согласие на встречу или условия предложения.

Срок действия и версия решают разные задачи. Срок ограничивает время, в течение которого можно использовать конкретную кнопку. Версия показывает, не изменился ли объект с момента формирования этого действия. Увеличение срока не устраняет проблему устаревшей версии, а новая версия не делает старый ключ безопасным для бесконечного использования.

Отделяйте ответ Telegram от результата записи

После нажатия клиент показывает индикатор загрузки, пока бот не вызовет answerCallbackQuery. Отвечайте и на отклонённые callback-запросы. Если операция занимает время, уместно нейтральное сообщение «Проверяем действие». Писать «Заявка изменена» следует только после подтверждения результата. Успешный ответ метода Telegram не подтверждает запись в CRM.

Проверку версии, захват действия и локальное изменение выполняйте атомарно в одной транзакции. Иначе два обработчика могут одновременно увидеть used: false. Приведённая ниже функция не защищает от такой гонки.

Локальная транзакция не охватывает запрос к удалённой CRM. Сохраните устойчивую операцию и используйте документированный механизм идемпотентности этой CRM либо сверьте результат после неоднозначного таймаута. Не помечайте действие окончательно выполненным, пока эффект не подтверждён. Граница между повторной доставкой и повторной обработкой подробнее рассмотрена в статье о повторных вебхуках и дублях CRM. Повторное нажатие и повторная доставка одного события имеют разные причины, но могут относиться к одной бизнес-операции.

Заранее определите, что означает каждый статус серверной записи: ожидает проверки, захвачена обработчиком, отправлена во внешнюю систему, подтверждена или требует сверки. Названия и модель хранения зависят от приложения; важно, чтобы таймаут не превращался автоматически в подтверждённый успех. Если внешний запрос завершился неясно, повторять операцию можно только с безопасным ключом идемпотентности либо после сверки результата с CRM.

Не держите блокировку базы во время долгого сетевого запроса без необходимости. Один из возможных подходов: в транзакции проверить актуальные права и версию, атомарно захватить действие и записать устойчивую задачу; затем обработать задачу отдельно и сохранить подтверждённый результат. Это общий план, а не готовая схема для любой базы и CRM. Границы транзакции и восстановления следует согласовать с используемым хранилищем.

Повторный callback после успешной операции не должен запускать новое изменение. Если доступ всё ещё подтверждён, можно вернуть уже известный результат. Если право доступа отозвано, не раскрывайте результат только потому, что тот же пользователь нажал ту же кнопку ранее. Проверка доступа нужна и для повторного чтения результата.

Локально проверьте таблицу отказов

Сохраните код как callback_policy_test.py и выполните python callback_policy_test.py без -O, который отключает assert. Нужен Python 3, дополнительные библиотеки не требуются. Это последовательная проверка решения на искусственных данных, а не бот, реализация хранилища или тест конкурентной обработки. DEMO_ONLY - публичная тестовая строка, а не пример рабочего секретного ключа.

import copy
import json


def decide(query, action, lead, now):
    # Preconditions: authenticated delivery and validated object shapes.
    message = query.get("message")
    if not message or message.get("chat", {}).get("type") != "private":
        return "unsupported_context"
    if not action or query.get("data") != action["token"]:
        return "unknown_action"
    sender = query["from"]["id"]
    if type(sender) is not int or sender != action["owner_id"]:
        return "wrong_user"
    if sender not in lead["allowed_users"]:
        return "permission_denied"
    if now >= action["expires_at"]:
        return "expired"
    if action["used"]:
        return "already_used"
    if lead["version"] != action["lead_version"]:
        return "stale_version"
    if lead["status"] != "new" or action["kind"] != "request_demo":
        return "invalid_transition"
    return "eligible"


query = {"from": {"id": 1001}, "data": "DEMO_ONLY",
         "message": {"chat": {"type": "private"}}}
action = {"token": "DEMO_ONLY", "owner_id": 1001, "expires_at": 200,
          "used": False, "lead_version": 3, "kind": "request_demo"}
lead = {"allowed_users": [1001], "version": 3, "status": "new"}
results = [decide(query, action, lead, 100)]
q = copy.deepcopy(query)
q["from"]["id"] = 2002
results.append(decide(q, action, lead, 100))
results.append(decide(query, action, {**lead, "allowed_users": []}, 100))
results.append(decide(query, action, lead, 200))
results.append(decide(query, {**action, "used": True}, lead, 100))
results.append(decide(query, action, {**lead, "version": 4}, 100))
results.append(decide(query, None, lead, 100))
results.append(decide({**query, "message": None}, action, lead, 100))
results.append(decide(query, action, {**lead, "status": "closed"}, 100))
assert results == ["eligible", "wrong_user", "permission_denied", "expired",
                   "already_used", "stale_version", "unknown_action",
                   "unsupported_context", "invalid_transition"]
print(json.dumps(results))

Фактический вывод локального запуска:

["eligible", "wrong_user", "permission_denied", "expired", "already_used", "stale_version", "unknown_action", "unsupported_context", "invalid_transition"]

eligible означает лишь, что пройдены показанные проверки. Функция ничего не записывает, не помечает ключ использованным и не выполняет транзакцию. now и expires_at в примере - условные числа на одной шкале времени. В рабочем коде используйте серверное время и согласованный формат срока. До вызова функции проверьте структуру входных объектов и ожидаемые типы.

При AssertionError выясните, какая ветка изменилась. Не удаляйте проверку, чтобы тест прошёл. Если политика изменилась, осознанно обновите ожидаемые результаты.

Тест демонстрирует отдельные отказы, но не проверяет все сочетания условий и не заменяет тесты приложения. Например, здесь нет проверки привязки к конкретному сообщению, чат-идентификатору или боту, потому что это зависит от выбранной схемы. Добавляйте такие условия в тесты, если они входят в вашу модель действия. Также отдельно проверяйте некорректные типы и отсутствующие поля на границе обработчика: функция явно предполагает, что структура входных объектов уже проверена.

Что проверить перед подключением CRM

В тестовом личном чате нажмите действительную кнопку от имени предполагаемого пользователя. Должна создаваться только разрешённая операция по нужной заявке.
Отзовите у пользователя доступ, затем нажмите старую кнопку. Заявка должна остаться без изменений; закрытые данные не должны раскрываться.
Измените версию заявки или закройте её до нажатия. Старое подтверждение не должно перезаписать новое состояние.
Проверьте истёкший срок, неизвестный ключ и неподдерживаемый контекст. Ожидайте отказ и корректный ответ на callback, а не необработанное исключение.
Отправьте два запроса одновременно и повторите уже завершённый. Проверьте атомарный захват действия в базе и отсутствие второго бизнес-эффекта.
Смоделируйте потерю ответа CRM. Не считайте операцию успешной или неуспешной только на основании таймаута; восстановите результат через устойчивую операцию.

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

Проверьте также путь отказа интерфейса. Если сообщение с кнопкой недоступно, не считайте это доказательством того, что действие было выполнено или отменено. Необходимое бизнес-состояние хранится на сервере; удаление или обновление клавиатуры не заменяет его проверку. Если пользователь может запросить новое подтверждение, оно должно отражать текущие условия и актуальную версию заявки.

Эти интеграционные проверки здесь не выполнялись. Для технических журналов обычно достаточно причины решения, внутренних ID операции и проверенной версии. Не копируйте полные callback-запросы, личные данные или ключи без необходимости. Удаление клавиатуры улучшает интерфейс, но не заменяет серверный отказ для устаревших действий. Готовность означает, что чужое или устаревшее нажатие не меняет заявку, а подтверждённое действие не создаёт второго эффекта.

Эта статья также опубликована на других платформах. Оригинал: Inline-кнопки Telegram-бота: проверка прав и устаревших действий

Telegram Bot Contacts: Avoid Saving Someone Else's Phone in Your CRM

ALEKSANDR MICHAILOVICH — Fri, 23 Oct 2026 03:08:39 +0000

Telegram Bot Contacts: Avoid Saving Someone Else's Phone in Your CRM

Do not save every incoming contact.phone_number as the sender's phone number. To link a contact automatically in a private chat, compare message.contact.user_id with message.from.id. If the contact ID is missing or different, leave the number unlinked and ask the user to share their own contact using a button.

This is a policy for your own Telegram Bot API handler, not instructions for configuring a 24go.site feature. It assumes that your server has already authenticated delivery and validated the update's structure. Matching IDs links the contact to the Telegram user in that event. It does not verify a phone number by SMS, establish identity, or grant permission to send marketing messages.

Ask for the right contact first

In KeyboardButton, request_contact: true means that pressing the button sends the user's phone number as a contact. This is available only in private chats. Use a regular reply keyboard, not an inline button.

For example, pass this object as reply_markup in your bot's existing sendMessage call:

{
  "keyboard": [[
    {"text": "Share my phone number", "request_contact": true}
  ]],
  "resize_keyboard": true,
  "one_time_keyboard": true
}

Explain the purpose in the message: “Share your phone number if you would like a sales representative to call about this enquiry. You can also continue the conversation here.” The button's presence does not mean the number has arrived. Process the incoming message, not the fact that you sent a keyboard.

A user can also send a contact manually. The Contact object's user_id is optional. Your handler therefore needs a missing-ID branch, even if every successful test with your button has returned one.

Decide before writing to the CRM

Compare the user ID in message.from.id, not a name, username, or phone string. User.id identifies a user or bot. It is not a phone number.

Input	Handler decision
Chat is not private	Do not run this linking procedure
Message has no contact	Continue the normal conversation; leave the phone unchanged
Sender ID or `contact.user_id` is missing	Leave the contact unlinked
Both IDs exist but differ	Do not save the contact as the sender's phone
IDs match and a number is present	Allow the next step under your storage policy

A missing ID is not evidence of deception. A mismatch is not a reason to accuse the user either: they may have shared a colleague's contact. Reply neutrally: “We could not link this contact to your Telegram profile. If you would like us to call you, please use the button to share your own contact.” Enquiries on someone else's behalf need a separate process, not a weaker check.

A match should not silently overwrite a previously confirmed CRM number. Retain the source, receipt time, sender ID, and check result. Define a separate rule for updating an existing phone number. Do not merge records for different people just because their phone strings match.

A local test without a bot or CRM

The code below checks only which branch is selected for artificial inputs. It does not receive HTTP requests, verify a webhook secret, normalize numbers, or store them. It needs Python 3 and no additional libraries. Save it as contact_policy_test.py and run python contact_policy_test.py without -O, which disables assert.

import copy
import json


def contact_status(message):
    if message.get("chat", {}).get("type") != "private":
        return "outside_private"
    contact = message.get("contact")
    if not isinstance(contact, dict):
        return "no_contact"
    sender_id = message.get("from", {}).get("id")
    contact_id = contact.get("user_id")
    if type(sender_id) is not int or type(contact_id) is not int:
        return "unlinked"
    if sender_id != contact_id:
        return "different_user"
    phone = contact.get("phone_number")
    if not isinstance(phone, str) or not phone.strip():
        return "unlinked"
    return "same_user"


base = {
    "chat": {"type": "private"},
    "from": {"id": 1001},
    "contact": {"user_id": 1001, "phone_number": "TEST_ONLY"},
}
cases = [copy.deepcopy(base) for _ in range(7)]
cases[1]["contact"]["user_id"] = 2002
del cases[2]["contact"]["user_id"]
del cases[3]["contact"]
cases[4]["chat"]["type"] = "group"
cases[5]["contact"]["phone_number"] = ""
cases[6]["contact"]["user_id"] = "1001"
results = [contact_status(case) for case in cases]
assert results == [
    "same_user", "different_user", "unlinked", "no_contact",
    "outside_private", "unlinked", "unlinked",
]
print(json.dumps(results))

Expected output:

["same_user", "different_user", "unlinked", "no_contact", "outside_private", "unlinked", "unlinked"]

TEST_ONLY is deliberately not a real phone number. same_user means only that the input passed the checks shown; it does not mean the string can be called. The final case rejects a string ID: the example expects numeric IDs from Bot API JSON. If your library converts types, define that boundary explicitly and test the conversion.

If you get an AssertionError, investigate which rule changed rather than removing the check. Validate the structure before calling this function: for example, chat and from must be objects of the expected shape. This is not a general parser for arbitrary JSON.

Check the real bot separately

Send the reply button in a private test chat, press it, and inspect the resulting from.id and contact.user_id. Do not publish the real phone number in the test log.
In a controlled test, send another test participant's contact with their permission. Expect automatic linking to be refused if the IDs differ; if the ID is missing, expect unlinked.
Send ordinary text after the contact. It should not erase the stored phone number. Declining to share a number should not interrupt the available Telegram conversation.
Check the inbound HTTP boundary. setWebhook supports secret_token and the X-Telegram-Bot-Api-Secret-Token header. Your handler must validate its configured secret before processing the event. Comparing IDs inside a forged request proves nothing by itself.
Redeliver the same event in your test environment. It should not create a second write operation. That is a separate webhook idempotency problem, not a property of contact checking.

The local example does not establish the results of these integration tests. Record the client, time, selected branch, and test CRM change separately. Technical logs generally need the result and internal record references, not full contacts or secrets copied into them unnecessarily.

Where this check stops

Request a phone number only for a purpose the user understands. Restrict access, set a retention period, and provide a way to correct or delete it. Linking a contact to a Telegram ID does not establish permission for advertising calls, verify legal identity, or guarantee that the number is currently reachable. Assess data-processing and messaging requirements separately for your use case.

Readiness means that a contact with an unknown or different user's ID does not become the sender's phone number, declining does not interrupt the conversation, and redelivery does not add an extra record. Connect the procedure to your production CRM only after these checks.

This article was also published on other platforms. Original on 24go.site: Telegram Bot Contacts: Avoid Saving Someone Else's Phone in Your CRM

Контакт в Telegram-боте: как не записать чужой телефон в CRM [перекрёстная публикация]

ALEKSANDR MICHAILOVICH — Fri, 23 Oct 2026 03:08:38 +0000

Контакт в Telegram-боте: как не записать чужой телефон в CRM

Не записывайте любой полученный contact.phone_number как телефон отправителя. Для автоматической привязки в личном чате сопоставьте message.contact.user_id и message.from.id. Если идентификатор контакта отсутствует или отличается, оставьте телефон непривязанным и попросите пользователя поделиться своим контактом через кнопку.

Это правило для собственного обработчика Telegram Bot API, а не инструкция по настройке функции 24go.site. Предполагается, что сервер уже проверил подлинность доставки и структуру обновления. Совпадение идентификаторов связывает контакт с Telegram-пользователем в полученном событии. Это не замена SMS-проверке, установлению личности или разрешению на маркетинговые сообщения.

Сначала запросите нужный контакт

В KeyboardButton поле request_contact: true означает, что при нажатии кнопки телефон пользователя отправляется как контакт. Эта возможность доступна только в личных чатах. Используйте обычную reply-клавиатуру, а не inline-кнопку.

Например, передайте такой объект как reply_markup в существующем вызове sendMessage вашего бота:

{
  "keyboard": [[
    {"text": "Поделиться своим телефоном", "request_contact": true}
  ]],
  "resize_keyboard": true,
  "one_time_keyboard": true
}

Объясните цель в тексте сообщения: «Поделитесь своим телефоном, если хотите, чтобы менеджер связался с вами по этой заявке. Можно продолжить разговор здесь». Само наличие кнопки не означает, что телефон уже получен. Обрабатывайте пришедшее сообщение, а не факт отправки клавиатуры.

Пользователь также может прислать контакт вручную. В объекте Contact поле user_id необязательно. Поэтому обработчику нужна ветка для отсутствующего ID, даже если успешный тест с вашей кнопкой всегда возвращал ID.

Решение перед записью в CRM

Сравнивайте ID пользователя из message.from.id, а не имя, username или строку телефона. User.id обозначает идентификатор пользователя или бота. Это не номер телефона.

Вход	Решение обработчика
Чат не личный	Не выполнять эту процедуру привязки
В сообщении нет контакта	Продолжить обычный диалог, не менять телефон
Нет ID отправителя или `contact.user_id`	Оставить контакт непривязанным
Оба ID есть, но различаются	Не записывать контакт как телефон отправителя
ID совпадают, номер присутствует	Разрешить следующий шаг согласно вашей политике хранения

Отсутствующий ID не доказывает обман. Несовпадение тоже не повод обвинять человека: он мог отправить контакт коллеги. Ответьте нейтрально: «Не удалось связать этот контакт с вашим Telegram-профилем. Если хотите, чтобы мы позвонили вам, воспользуйтесь кнопкой, чтобы отправить свой контакт». Для обращения от имени другого человека нужен отдельный процесс, а не ослабление проверки.

Совпадение не должно молча перезаписывать ранее подтверждённый номер в CRM. Сохраняйте источник, время получения, ID отправителя и результат проверки. Правило обновления существующего телефона определите отдельно. Не объединяйте записи разных людей только потому, что совпали строки телефонов.

Локальный тест без бота и CRM

Код ниже проверяет только выбор ветки на искусственных данных. Он не принимает HTTP-запросы, не проверяет секрет вебхука, не нормализует номера и не сохраняет их. Нужен Python 3, дополнительные библиотеки не требуются. Сохраните код в contact_policy_test.py и выполните python contact_policy_test.py без флага -O, который отключает assert.

import copy
import json


def contact_status(message):
    if message.get("chat", {}).get("type") != "private":
        return "outside_private"
    contact = message.get("contact")
    if not isinstance(contact, dict):
        return "no_contact"
    sender_id = message.get("from", {}).get("id")
    contact_id = contact.get("user_id")
    if type(sender_id) is not int or type(contact_id) is not int:
        return "unlinked"
    if sender_id != contact_id:
        return "different_user"
    phone = contact.get("phone_number")
    if not isinstance(phone, str) or not phone.strip():
        return "unlinked"
    return "same_user"


base = {
    "chat": {"type": "private"},
    "from": {"id": 1001},
    "contact": {"user_id": 1001, "phone_number": "TEST_ONLY"},
}
cases = [copy.deepcopy(base) for _ in range(7)]
cases[1]["contact"]["user_id"] = 2002
del cases[2]["contact"]["user_id"]
del cases[3]["contact"]
cases[4]["chat"]["type"] = "group"
cases[5]["contact"]["phone_number"] = ""
cases[6]["contact"]["user_id"] = "1001"
results = [contact_status(case) for case in cases]
assert results == [
    "same_user", "different_user", "unlinked", "no_contact",
    "outside_private", "unlinked", "unlinked",
]
print(json.dumps(results))

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

["same_user", "different_user", "unlinked", "no_contact", "outside_private", "unlinked", "unlinked"]

TEST_ONLY намеренно не является настоящим номером. Результат same_user означает только, что вход прошёл показанные проверки. Он не подтверждает, что по этой строке можно позвонить. В последнем случае отклоняется строковый ID: пример ожидает числовые ID из JSON Bot API. Если ваша библиотека преобразует типы, явно задайте правила такого преобразования на границе и протестируйте их.

При AssertionError выясните, какое правило изменилось, а не удаляйте проверку. Перед вызовом этой функции проверьте структуру: например, chat и from должны быть объектами ожидаемой формы. Это не универсальный парсер произвольного JSON.

Что отдельно проверить на настоящем боте

В тестовом личном чате отправьте reply-кнопку, нажмите её и проверьте полученные from.id и contact.user_id. Не публикуйте реальный телефон в журнале теста.
В контролируемой проверке отправьте контакт другого тестового участника с его разрешения. При несовпадении ID автоматическая привязка должна быть отклонена; при отсутствии ID ожидайте unlinked.
Отправьте обычный текст после контакта. Он не должен стирать сохранённый телефон. Отказ поделиться номером не должен прерывать доступный диалог в Telegram.
Проверьте входной HTTP-контур. setWebhook поддерживает secret_token и заголовок X-Telegram-Bot-Api-Secret-Token. Обработчик должен проверить настроенный секрет до обработки события. Сравнение ID внутри поддельного запроса само по себе ничего не удостоверяет.
Повторно доставьте то же событие в тестовой среде. Оно не должно создавать вторую операцию записи. Это отдельная задача идемпотентности вебхуков, а не свойство проверки контакта.

Локальный пример не подтверждает результаты этих интеграционных проверок. Отдельно зафиксируйте клиент, время, выбранную ветку и изменение в тестовой CRM. В технических логах обычно достаточно результата и внутренних ссылок на запись. Не переносите туда полные контакты и секреты без необходимости.

Где заканчивается эта проверка

Запрашивайте телефон только для цели, понятной пользователю. Ограничьте доступ к номеру, установите срок хранения и предусмотрите способ его исправления или удаления. Связь контакта с Telegram ID не доказывает право звонить с рекламой, не подтверждает личность и не гарантирует, что номер сейчас доступен. Требования к обработке данных и сообщениям отдельно оцените для своего сценария.

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

Эта статья также опубликована на других платформах. Оригинал на dev.to: Контакт в Telegram-боте: как не записать чужой телефон в CRM

Repeated Telegram Webhooks: Avoiding a Second CRM Lead

ALEKSANDR MICHAILOVICH — Thu, 22 Oct 2026 08:50:35 +0000

Repeated Telegram Webhooks: Avoiding a Second CRM Lead

If the same Telegram event arrives twice, your integration should not create a second CRM lead. A stable event identifier and a processing record help prevent that. But checking whether an ID has been seen is not enough: if the CRM creates a lead and its response is lost, your handler cannot tell whether it is safe to send another create request.

This is a design guide for developers connecting Telegram Bot API → their own handler → a CRM. It does not describe a verified built-in feature of 24go.site. It assumes your bot already receives the relevant enquiries legitimately, and that you have a database and a test CRM. The design does not grant permission to collect other people's contact details or send unsolicited messages.

Give events, contacts, and deals different identities

These objects need different keys and rules for handling repeats.

Object	What its key protects	Example key in your integration
Incoming event	Processing the same delivery twice	source + your tenant + bot + `update_id`
Contact	Linking multiple enquiries to one person	tenant + source + user identifier, when available
Deal	Separating a new enquiry from an existing conversation	internal enquiry ID under an agreed business rule

In the Telegram Bot API, update_id uniquely identifies an update. Telegram explicitly documents its use for ignoring repeated updates. The additional components above are a proposed isolation scheme for your system, not Telegram's key format.

Two different messages from one person are not duplicate deliveries of the same event. They might extend one deal or start different deals; agree on the rule with the process owner. Do not turn “one delivery, one processing action” into “one person, one deal forever.”

Receiver: persist first, acknowledge second

Idempotency means that repeating an operation does not produce an additional effect. Store incoming updates durably rather than relying only on process memory.

Authenticate the request and validate its expected structure. Telegram's setWebhook supports secret_token; when configured, Telegram sends it in X-Telegram-Bot-Api-Secret-Token. Check it before queuing work. Do not log the token's value.
Build the event key. Do not use request arrival time, which changes on redelivery.
Store the event and set its state to pending in one transaction. Put a unique constraint on the composite key. If jobs live in a separate table, write both records in the same transaction to avoid losing work between writes.
Return a successful HTTP response after the commit succeeds. If the key already exists, acknowledge delivery without creating a new job. An existing pending record must remain available to the worker.
If durable storage fails, do not acknowledge success. Your handler should not claim to have accepted an event it has not stored.

Hookdeck's idempotency guide describes unique constraints and processing history as idempotency strategies. The database constraint matters: separate “check whether it exists” and “insert” operations do not provide the same atomic protection against simultaneous requests.

Worker: a timeout does not mean creation failed

Before attempting creation, persist an operation_id that identifies the business operation. Keep it unchanged across worker retries. Prevent two workers from executing the same operation at once with atomic job claiming, an ownership deadline, and a recovery procedure for abandoned jobs.

Choose the next step based on capabilities verified in your CRM's own documentation:

Idempotent creation is supported. Reuse the same operation key on each retry within its documented validity period. Do not assume every CRM accepts an Idempotency-Key header.
A unique external ID and atomic upsert are supported. Map the operation to that ID. Here, upsert means creating or updating by key; an ordinary search followed by creation does not provide equivalent protection against a race.
Neither mechanism is available. After an ambiguous timeout, move the job to needs_reconciliation. Check the CRM using an external operation reference, request logs, or manual inspection. If you cannot establish the result, do not blindly submit another create request.

After confirmed success, store crm_id and mark the job done. If the process dies after creating the lead but before saving the result, recovery must use the same idempotency mechanism or reconciliation. A local event table alone does not guarantee exactly-once effects in a remote CRM.

Decide what repeated and new messages should do

Situation	Action
Same event key, `pending` record	Acknowledge delivery; continue the original job
Same event key, `done` record	Do not repeat the CRM action
Different `update_id`, same contact	Apply the rule for continuing or opening a deal
Timeout after sending a create request	Retry with a supported stable key or reconcile; do not generate a new random key
Late stage-change event	Check its version or whether the transition is valid rather than overwriting unconditionally

Do not transfer one provider's guarantees to another. For example, Stripe documents event retries and the absence of guaranteed delivery order. This illustrates why delivery contracts need checking; it is not the specification for your CRM or Telegram integration.

Test failure paths before enabling the integration

Use anonymized test enquiries and check more than the happy path:

Deliver the same key twice, then concurrently in two requests. Storage should contain one job, and the CRM effect should not be duplicated.
Stop the worker after pending is persisted. The event should still be available for processing after restart.
Simulate a CRM record being created while its response is lost. Recovery should use the original key or move the job to needs_reconciliation, not blindly create again.
Send a different message from the same test contact. Confirm that event deduplication does not discard it.
Test authentication failure and database failure. A forged request should not enter the queue, and an unsaved event should not receive a successful acknowledgement.

In the local SQLite check accompanying this article, inserting the same key twice sequentially left one row; inserting a different key left two. This checks a storage constraint using artificial data. It is not a CRM test, a concurrent HTTP test, or a test of the entire recovery design.

For operation, monitor the age of pending jobs, errors, and the number of jobs requiring needs_reconciliation. Retain the mapping event_key → operation_id → crm_id. Avoid placing full conversations and tokens in technical logs unnecessarily. Align key retention with actual redelivery periods and data requirements: after a key is deleted, an old event can look new again.

Readiness is not just seeing a test lead appear once. Confirm that retries do not add another effect, unfinished work can recover, and an ambiguous response does not turn into a duplicate deal.

This article was also published on other platforms. Original on 24go.site: Repeated Telegram Webhooks: Avoiding a Second CRM Lead

Повторный вебхук Telegram: как не создать второй лид в CRM [перекрёстная публикация]

ALEKSANDR MICHAILOVICH — Thu, 22 Oct 2026 08:50:34 +0000

Повторный вебхук Telegram: как не создать второй лид в CRM

Если одно событие Telegram доставлено дважды, CRM не должна создавать второй лид. Устойчивый идентификатор события и запись о его обработке помогают этого избежать. Но одной проверки «мы уже видели этот ID» недостаточно: если CRM создала лид, а ответ потерялся, обработчик не знает, безопасно ли повторять запрос.

Это руководство по проектированию интеграции Telegram Bot API → собственного обработчика → CRM. Оно не описывает проверенную встроенную функцию 24go.site. Предполагается, что бот уже законно получает нужные обращения, а у вас есть база данных и тестовая CRM. Эта схема не даёт права собирать чужие контактные данные или отправлять сообщения без соответствующих оснований.

Разделите идентификаторы событий, контактов и сделок

Для этих объектов нужны разные ключи и правила обработки повторов.

Объект	Что защищает его ключ	Пример ключа в вашей интеграции
Входящее событие	Повторную обработку одной доставки	источник + ваш tenant + бот + `update_id`
Контакт	Связь нескольких обращений с одним человеком	tenant + источник + идентификатор пользователя, если он доступен
Сделка	Разделение нового обращения и продолжения существующего диалога	внутренний ID обращения согласно согласованному бизнес-правилу

В Telegram Bot API update_id служит уникальным идентификатором обновления. Telegram прямо указывает, что он позволяет игнорировать повторные обновления. Дополнительные компоненты составного ключа выше предлагают изолировать записи в вашей системе; это не формат ключа Telegram.

Два разных сообщения одного человека не являются повторной доставкой одного события. Они могут относиться к одной сделке или начинать разные сделки. Это следует согласовать с владельцем процесса. Не превращайте правило «одна доставка, одна обработка» в правило «один человек, одна сделка навсегда».

Приёмник: сначала сохранить, затем подтвердить

Идемпотентность означает, что повтор операции не создаёт дополнительного эффекта. Входящие обновления нужно сохранять в постоянном хранилище, а не только в памяти процесса.

Проверьте подлинность запроса и ожидаемую структуру. В setWebhook предусмотрен параметр secret_token. Если он настроен, Telegram отправляет его в заголовке X-Telegram-Bot-Api-Secret-Token. Проверьте его до постановки задания в очередь. Не записывайте значение токена в журнал.
Сформируйте ключ события. Не используйте время получения запроса: при повторной доставке оно изменится.
В одной транзакции сохраните событие и установите ему состояние pending. Наложите уникальное ограничение на составной ключ. Если задания хранятся в отдельной таблице, записывайте событие и задание в той же транзакции, чтобы между записями не потерять работу.
После успешного commit верните успешный HTTP-ответ. Если ключ уже существует, подтвердите доставку, но не создавайте новое задание. Существующая запись pending должна оставаться доступной воркеру.
Если сохранить данные в постоянном хранилище не удалось, не отвечайте успехом. Обработчик не должен сообщать о приёме события, которого он не сохранил.

В руководстве Hookdeck по идемпотентности уникальные ограничения и история обработки описаны как стратегии защиты от повторов. Важна именно гарантия ограничения базы данных: отдельные операции «проверить наличие» и «вставить» не обеспечивают такую же атомарную защиту от одновременных запросов.

Воркер: таймаут не означает, что создание не удалось

До попытки создания сохраните постоянный operation_id, идентификатор этой бизнес-операции. Он должен оставаться неизменным при повторных запусках воркера. Не допускайте, чтобы два воркера одновременно выполняли одну операцию: используйте атомарный захват задания, срок владения и процедуру восстановления зависших заданий.

Выберите следующий шаг, исходя из возможностей конкретной CRM, подтверждённых её документацией:

Поддерживается идемпотентное создание. Повторно используйте тот же ключ операции в течение установленного срока его действия. Не предполагайте, что любая CRM принимает заголовок Idempotency-Key.
Поддерживаются уникальный внешний ID и атомарный upsert. Сопоставьте операцию с этим ID. Здесь upsert означает создание или обновление по ключу. Обычный поиск с последующим созданием не обеспечивает аналогичную защиту от гонки.
Нет ни одного из этих механизмов. После неоднозначного таймаута переведите задание в needs_reconciliation, то есть на сверку. Проверьте CRM по внешней ссылке на операцию, журналам запросов или вручную. Если результат установить не удалось, не отправляйте запрос на создание повторно вслепую.

После подтверждённого успеха сохраните crm_id и отметьте задание как done. Если процесс завершится после создания лида, но до сохранения результата, при восстановлении нужно использовать тот же механизм идемпотентности или выполнить сверку. Одна лишь локальная таблица событий не гарантирует выполнение операции ровно один раз в удалённой CRM.

Определите, что делать с повторными и новыми сообщениями

Ситуация	Действие
Тот же ключ события, запись `pending`	Подтвердить доставку и продолжить исходное задание
Тот же ключ события, запись `done`	Не повторять действие в CRM
Другой `update_id`, тот же контакт	Применить правило продолжения или открытия сделки
Таймаут после отправки запроса на создание	Повторить запрос с поддерживаемым постоянным ключом или выполнить сверку; не генерировать новый случайный ключ
Запоздавшее событие об изменении стадии	Проверить версию или допустимость перехода, а не перезаписывать стадию безусловно

Не переносите гарантии одного поставщика на другого. Например, Stripe описывает повторную доставку событий и отсутствие гарантированного порядка доставки. Это пример того, почему нужно проверять условия доставки, а не спецификация вашей CRM или Telegram-интеграции.

Проверьте сценарии отказа до включения интеграции

На обезличенных тестовых обращениях проверьте не только штатный сценарий:

Доставьте один и тот же ключ дважды, затем одновременно в двух запросах. В хранилище должно остаться одно задание, а эффект в CRM не должен дублироваться.
Остановите воркер после сохранения pending. После перезапуска событие должно оставаться доступным для обработки.
Смоделируйте создание записи в CRM с потерей ответа. При восстановлении нужно использовать исходный ключ или перевести задание в needs_reconciliation, а не повторять создание вслепую.
Отправьте другое сообщение от того же тестового контакта. Убедитесь, что дедупликация событий не отбрасывает его.
Проверьте отказ в авторизации и сбой базы данных. Поддельный запрос не должен попасть в очередь, а несохранённое событие не должно получить успешное подтверждение.

В локальной проверке SQLite к этой статье один ключ последовательно вставили дважды: в таблице осталась одна строка. Вставка другого ключа увеличила число строк до двух. Это проверка ограничения хранилища на искусственных данных, а не тест CRM, конкурентных HTTP-запросов или всей схемы восстановления.

Для эксплуатации отслеживайте возраст заданий pending, ошибки и количество заданий needs_reconciliation. Храните связь event_key → operation_id → crm_id. Не записывайте полные переписки и токены в технические журналы без необходимости. Срок хранения ключей согласуйте с фактическим периодом повторной доставки и требованиями к данным: после удаления ключа старое событие может снова выглядеть новым.

Готовность определяется не тем, что тестовый лид появился один раз. Нужно убедиться, что повторная доставка не создаёт дополнительный эффект, незавершённая работа восстанавливается, а неоднозначный ответ не приводит к дублирующей сделке.

Эта статья также опубликована на других платформах. Оригинал на dev.to: Повторный вебхук Telegram: как не создать второй лид в CRM