DEV Community: ALEKSANDR MICHAILOVICH

A Customer Edited a Telegram Message: Update the CRM Note Safely [cross-post]

ALEKSANDR MICHAILOVICH — Thu, 05 Nov 2026 17:47:03 +0000

When a customer edits a Telegram message, do not turn the correction into another lead or replace the entire CRM record. Find the original source record, compare meaningful data and update only fields owned by the integration. If the source link is missing, versions conflict or an operator has changed the target note, retain the correction for reconciliation. Request arrival time does not prove that its text is newer.

This guide is for a developer maintaining a custom Telegram Bot API integration with a CRM. It assumes authorized receipt of enquiries, durable storage and an isolated test environment. It proposes a design policy, not a verified 24go.site feature or a ready-made configuration for any particular CRM. The scope is ordinary message and edited_message updates. Channel posts, business messages, guest formats and deletion need separate contracts. No live credentials are needed for the local policy check.

A message correction is not a repeated delivery

In the Update object, edited_message represents a new version of a message known to the bot that was edited. The documentation warns that changes to fields unavailable to, or not actively used by, the bot may also trigger this update. Receiving one therefore does not by itself require changing a visible CRM note or qualifying the customer again.

Redelivery of an update and revision of a source message are different problems. An event deduplication key must not discard a different update merely because it concerns an existing message. Conversely, a new update with identical meaningful content does not need another note. Use the separate webhook idempotency design for repeated delivery and ambiguous record creation. This guide starts with the relationship between a source message and an already-linked CRM object.

Agree with the sales process owner on what a correction means. Changing “we need five licences” to “we need three” may amend an enquiry, but it does not independently authorize changing an approved deal amount. A spelling correction should not automatically send another email or reopen a task. Business effects belong to your agreed workflow, not to the name of a Telegram field.

Give the source message its own identity

Keep an event key separate from a message key. The event key needs your source context and update_id. For an ordinary message, a proposed application key combines tenant, bot, chat.id and message_id. Here, tenant identifies the organization within your system; it is not a Telegram field. The additional namespaces prevent two customers of an integration provider from sharing a source record accidentally.

The Message contract describes message_id as unique inside its chat. That number alone is insufficient for a whole database. A username, sender label or enquiry text is also unsuitable for locating the original note: these can change or coincide. If a source link is missing, do not select a vaguely similar deal by matching a few words and silently write the correction there.

Maintain an explicit mapping: source message key → internal source-record ID → target CRM note ID. Store the supported message shape, mapper version, accepted projection and delivery state alongside it. A projection is the selected data used to build your note, such as text with its associated entities or a caption with its own metadata. Define and version this application schema instead of assuming every field in an incoming object belongs in the CRM.

If an input's identity does not fit the supported ordinary-message scheme, stop automatic replacement. Special identifiers and newly introduced API formats are not supported merely because the JSON contains a familiar field name. Route them to separate handling. This design is not a universal decoder for every Telegram message format.

Compare source time and meaningful content separately

Message has an optional edit_date, the time the message was last edited in Unix time. It helps compare revisions of one supported source message, but it is not a complete revision history. Do not substitute the HTTP receipt time or job completion time. A slow worker can finish an older job after a newer one has completed.

The proposed conservative policy has distinct outcomes. If the selected projection equals the current one, there is no need to change the visible note. However, a later valid source edit time should still advance the boundary of versions already observed. Otherwise a subsequent late change may appear newer than an obsolete marker. Observation metadata and note content have different reasons to change.

If the projection differs and the source edit time is strictly later than the accepted boundary, it is a delivery candidate. If the time is earlier, do not replace the current projection. If the times are equal but the projections differ, record a conflict rather than choosing whichever request arrived last. This policy can require manual decisions, but avoids presenting an inferred order as a proven one. A missing or invalid edit time also requires reconciliation before an automatic replacement.

Retain update_id for deduplication and investigation, but do not describe it as an everlasting per-message revision counter. The Update documentation allows the next identifier to be chosen randomly after at least a week without new updates. Its documented sequencing role is useful, but does not replace your conflict-resolution and field-ownership contract. Do not invent an exact revision number that the source does not provide.

Decide who owns each CRM field

Before enabling automatic corrections, build an ownership table. For each target field, specify its owner, permitted action and how an operator's intervening change will be detected. A source-text note, deal stage and verified contact number should not inherit one blanket “last event wins” rule.

Target data	Proposed owner	Action on a message correction
Dedicated copy of the source enquiry	Integration, where exclusive ownership is established	Replace only that note after checking the source version
Note that operators may also edit	Shared ownership	Check the target version; on conflict, add a linked correction or review task
Deal stage and assignee	Agreed sales workflow	Do not change solely because edited_message arrived
Verified contact details	Separate verification process	Do not copy arbitrary revised text automatically
Technical processing history	Integration	Record the outcome and correction link under the retention policy

If the CRM supports a conditional write against a version, verify its actual contract and use it. Reading a note and then issuing an ordinary PATCH does not prevent an operator from changing it between those steps. Without confirmed conditional-write support, proposing an explicitly linked correction is safer than promising that replacement cannot lose work. Appending also needs a stable operation identity so retries do not add several identical corrections.

Do not turn the revision ledger into an uncontrolled archive. Define source retention and access separately under your lawful processing arrangements. Secretly copying all previous texts into logs does not become acceptable because it makes investigation easier. General telemetry usually needs internal identifiers, outcome codes and the adapter version rather than complete private enquiries.

Handle an edit whose original record is missing

An unknown original does not prove that the customer opened a new enquiry. The initial job might be delayed, its CRM mapping might not yet be saved, or the relevant message might predate your observation window. Persist the correction as waiting for a source link, and inspect the local job queue and mapping ledger. Do not create another lead by default.

Assign a deadline and an owner to this reconciliation. Once the original becomes available, process the retained correction under the same version rules rather than replaying its initial write command unchanged. If no link can be established, the operator should see an unresolved outcome, not a green synchronization status. Repeated missing-original cases may indicate routing or persistence defects.

Do not promise to reconstruct complete message history through this design. An edit exposes an observed version, not every change ever made. The absence of another update does not prove that a user made no correction. Likewise, an ordinary edited_message is not a deletion notification. Missing text in an unsupported message shape must not be converted into an instruction to erase the CRM note.

Apply the correction in explicit stages

Persist the update and its type through your existing authenticated receiver. Webhook authentication and acknowledgement after durable acceptance remain necessary, but are not redesigned here. The dispatcher must explicitly distinguish a new message from an edited one.
Resolve the source key and its target note mapping. Check the organization, bot and chat; do not trust a client-supplied ID for another organization's deal. If the source is unknown, create a reconciliation task without a remote replacement.
Build the supported body projection together with its associated metadata. An absent field in an unsupported shape does not mean an empty string. Compare meaningful link destinations too if they are part of the note, not only the displayed link labels.
Within one local transaction, decide against the currently accepted version and save an operation intent. Use an atomic claim or record-version check so two workers cannot independently accept incompatible decisions. A check held only in process memory is insufficient.
For a delivery candidate, apply field ownership and the CRM's verified capabilities. Recheck that the operation is not already stale locally immediately before the write, and use a documented conditional write when available. A local transaction cannot lock an operator out of the remote CRM note.
Read back the target record and compare the expected data. If a timeout leaves the result unknown, retain a reconciliation state; do not generate a new operation key or blindly repeat replacement. Link a confirmed outcome to the particular source version that produced it.

Exercise the policy before connecting a CRM

A reproducible local policy check needs only synthetic keys, texts and times. Implement a pure decision function with no network access. Inputs are whether the original is known, the accepted source time and projection, and the candidate time and projection. Outcomes must distinguish unchanged content, a stale input, a delivery candidate and reconciliation. Separately check advancement of the observation boundary when content matches: “do not write the note” is not the same as “forget this observation.”

Synthetic scenario	Expected decision
Known original, newer time and different text	Delivery candidate, not another lead
Older time and different text	Do not replace the accepted version
Equal time and different projections	Reconcile the conflict
Newer time, identical projection	No note write; advance the observation boundary
No mapping to the original	Wait for a link; do not create another lead
No valid edit time	Reconcile without automatic replacement

These cases check only the proposed decision policy on artificial inputs. Connector acceptance also needs competing jobs, a restart after a persisted operation intent, an operator's intervening edit and a lost CRM response. Separately test that a new caption does not reuse old entity metadata. A passing decision function establishes neither database atomicity nor conditional remote writes.

In an isolated integration environment, create one authorized enquiry and record its CRM note ID. Correct a spelling error, then change a meaningful condition. Verify that both corrections remain linked to the same source, no additional deal appears and business effects follow the approved policy. Have an operator edit the target note before another source correction; check the conflict outcome rather than merely inspecting the HTTP response.

Close the rollout with a precise statement of which decisions passed locally, which outcomes were confirmed by CRM readback and which remain under manual reconciliation. Track the age of unresolved corrections and conflict reasons. The operator needs the corrected enquiry without silently losing their own work. That is the acceptance result to establish before enabling automatic replacement.

Sources

Telegram Bot API: Update, edited_message, update_id behavior and event scope; checked on the editorial date.
Telegram Bot API: Message, message identity, edit_date, text and captions; checked on the editorial date.

This article was also published on other platforms. Original: A Customer Edited a Telegram Message: Update the CRM Note Safely

Клиент исправил сообщение Telegram: как обновить заметку в CRM [перекрёстная публикация]

ALEKSANDR MICHAILOVICH — Thu, 05 Nov 2026 16:43:17 +0000

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

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

Исправление сообщения не равно повтору доставки

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

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

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

Дайте исходному сообщению собственный ключ

Храните отдельно ключ события и ключ сообщения. Для события нужен ваш контекст источника и update_id; для обычного сообщения предложен составной ключ из tenant, бота, chat.id и message_id. Tenant здесь обозначает организацию внутри вашей системы, а не поле Telegram. Дополнительные компоненты не дают двум клиентам интегратора случайно разделить одну запись.

В описании Message message_id уникален внутри чата. Одного этого числа для всей базы недостаточно. Имя пользователя, подпись отправителя и текст обращения также не подходят для поиска исходной заметки: они могут совпадать или меняться. Не пытайтесь при отсутствии связи подобрать похожую сделку по нескольким словам и молча записать исправление туда.

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

Если идентичность входа не укладывается в поддерживаемую обычную схему, остановите автоматическую замену. Специальные идентификаторы и новые форматы API нельзя принимать только потому, что JSON содержит знакомое поле. Направьте такой вход на отдельную обработку. Эта инструкция не является универсальным декодером всех форматов Telegram.

Сравнивайте содержимое и время источника раздельно

У Message есть необязательное поле edit_date: время последнего редактирования в Unix time. Оно полезно для сравнения редакций одного поддерживаемого сообщения, но не является полной историей правок. Не подменяйте его временем приёма HTTP-запроса или окончания задания: медленный воркер может завершить старую работу после новой.

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

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

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

Выберите, кто владеет полями CRM

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

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

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

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

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

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

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

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

Применяйте исправление по этапам

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

Проверьте политику до подключения CRM

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

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

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

В тестовой среде сначала создайте одно разрешённое обращение и зафиксируйте ID его заметки. Исправьте текст без изменения смысла, затем измените существенное условие. Убедитесь, что сохраняется связь с тем же источником, не появляется новая сделка, а автоматические действия соответствуют утверждённой политике. После ручной правки менеджером повторите исправление и проверьте конфликт, а не только HTTP-ответ.

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

Источники

Telegram Bot API: Update: edited_message, особенности update_id и границы событий; проверено в редакционную дату.
Telegram Bot API: Message: идентичность сообщения, edit_date, текст и подписи; проверено в редакционную дату.

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

Telegram Message Entities: Keep Links and Emoji Intact in Your CRM [cross-post]

ALEKSANDR MICHAILOVICH — Thu, 05 Nov 2026 02:16:13 +0000

When a Telegram enquiry reaches a CRM with the wrong link or a clipped word after an emoji, inspect the text mapping before changing webhook delivery. Telegram's message entities identify ranges using UTF-16 code units. Those ranges belong to the original text or caption, not a cleaned copy. Preserve the source string with its entities, then produce a separate plain-text view and validated link records.

This guide is for the maintainer of a custom Telegram Bot API integration. It is a proposed design and local diagnostic, not a verified built-in 24go.site capability. It assumes the integration already receives messages legitimately. The local example needs Python, not a bot token or a CRM account. It does not test a production connector, render untrusted HTML or authorize collecting unrelated people's data.

Identify the source field before reading a range

The Message object has optional text and entities for text messages. Media captions use caption and caption_entities. An entity list describes its corresponding string. A photo with a caption is not a text message with a mysteriously empty body; choosing only text can discard a valid enquiry before formatting is even considered.

Treat the two pairs as distinct inputs to the same mapper. Record which pair was selected. If your supported message has neither field, record an explicit unsupported or no-text outcome rather than making an empty sales note look successful. Other message shapes require their own schema handling; this procedure is not a complete decoder for every current Bot API message type.

Do not substitute the text of a replied-to message, a forwarded source or a generated summary for the current message body. Those are different pieces of context. If the product needs them, store their role explicitly. Otherwise a manager may read an old quoted price as the customer's current request. Preserve the association between each body and the exact entity list that describes it.

Why an emoji can shift a link

An entity is a typed range inside a string. The MessageEntity contract defines both offset and length in UTF-16 code units. A Python string slice uses Unicode code-point positions instead. These coordinate systems agree for many ordinary characters but differ for characters represented by a UTF-16 surrogate pair, including the grinning face in the example below.

Use the synthetic text 😀 offer. The entity covering offer starts at UTF-16 offset 3 and has length 5. The emoji occupies two code units and the following space occupies one. In Python, directly slicing positions 3 through 8 returns ffer, not the requested word. A parser may return a plausible-looking fragment without raising an error, which makes a silent mapping defect more dangerous than an obvious failure.

Do not generalize this to “every emoji counts as two.” Some visible symbols use one code unit, while a displayed emoji sequence can contain several Unicode code points. What looks like one character to a reader is not a dependable offset unit. Use the documented encoding or a tested library helper; do not maintain a hand-written exception list of emoji.

Keep originals and derived representations separate

Store the accepted source string and its associated entity metadata together under the integration's access and retention rules. Derived fields can include a plain-text note, link records and an optional sanitized rich-text view. The original is the reference for mapping and incident reproduction, not a reason to retain every conversation forever.

Normalization is a separate transformation. Trimming leading spaces, replacing line breaks or applying Unicode normalization can change range coordinates or the text they select. Resolve and validate ranges against the unchanged source first. If a downstream view needs different text, calculate its own positions or omit positions from that view. Never attach the original offsets to a modified string and assume they remain valid.

For an update that changes a message, treat the new body and its new metadata as one version. Do not reuse the old entities with the new text. A customer may alter both the label and destination of a link. Updating only the visible note leaves stale link records even when the UTF-16 arithmetic is correct. Agree separately on whether the CRM should replace a note, append a revision or require review.

A link label is not necessarily its destination

A url entity identifies a URL appearing in the body. A text_link entity has a visible label in the text and a separate optional url field that provides the destination. Saving only the selected label loses the target. Presenting that target as though it were the label can hide what the user actually wrote. Keep both fields and the entity type when your workflow needs links.

Neither a Telegram entity nor a familiar-looking label makes a destination trustworthy. The label “company portal” can point somewhere unrelated. Do not fetch the target automatically while creating a CRM note: fetching untrusted addresses introduces a separate network-security boundary. If previews are required, use an independently reviewed service with destination checks, network restrictions and a clear data policy.

For a plain-text CRM, showing the label and a separately identified destination is often simpler than reconstructing Telegram formatting. For a rich-text CRM, escape ordinary text and build only supported markup through a safe renderer. Do not concatenate customer text into HTML or treat incoming formatting as permission to execute anything. A valid range confirms where an entity points, not whether its contents are safe.

Incoming information	Preserve	Avoid inferring
`url`	Selected source substring and entity type	That the address is safe to open
`text_link`	Label and separate destination	That the label describes the actual host
`text_mention`	Selected label and permitted user reference, if needed	That the label is a stable username
`bold` or `italic`	Original text; optional supported presentation	That formatting changes business priority
`code` or `pre`	Literal text and supported metadata	That a command should be executed
Unknown entity type	Source text plus an explicit unsupported-type decision	That deleting the whole message is necessary

A text_mention can contain a user object according to the API. That is not proof that the sender owns the mentioned account or consented to creating a contact for it. Identity verification and contact collection remain separate decisions. Keep the mapping scope narrow instead of promoting any formatted mention into a new CRM person.

Validate ranges before using them

Require integer coordinates within the UTF-16 representation of the selected source. Reject negative offsets, nonpositive lengths for this mapper, ranges past the end and boundaries that split a surrogate pair. Distinguish invalid metadata from a text encoding error. A replacement character inserted during recovery can conceal which input failed; an explicit review outcome is easier to diagnose.

The following code is a small extraction diagnostic, not a complete Telegram entity validator. It deliberately accepts only one string and one range. It checks exact integer types so Python booleans are not silently accepted as coordinates. Strict decoding rejects a boundary inside the emoji's surrogate pair. The tests are artificial and do not send any messages or follow any URLs.

def entity_text(text, offset, length):
    if not isinstance(text, str):
        raise ValueError("text must be a string")
    if type(offset) is not int or type(length) is not int:
        raise ValueError("coordinates must be integers")
    if offset < 0 or length <= 0:
        raise ValueError("invalid range")
    raw = text.encode("utf-16-le", errors="strict")
    start = offset * 2
    end = (offset + length) * 2
    if end > len(raw):
        raise ValueError("range outside text")
    try:
        return raw[start:end].decode("utf-16-le", errors="strict")
    except UnicodeDecodeError as exc:
        raise ValueError("range splits a surrogate pair") from exc

text = "😀 offer"
assert entity_text(text, 3, 5) == "offer"
assert text[3:8] == "ffer"
for offset, length in [(1, 1), (-1, 1), (3, 6), (True, 1)]:
    try:
        entity_text(text, offset, length)
    except ValueError:
        pass
    else:
        raise AssertionError("invalid range accepted")
print("UTF-16 extraction checks passed")

Save the block as a local Python file and run it in a disposable environment. The expected terminal line is UTF-16 extraction checks passed. An assertion failure or exception means this diagnostic did not pass; do not silently change its expected values. The article's accompanying research artifacts record the actual local execution. There was no production bot or CRM test during this check.

This function does not validate entity types, required type-specific fields, nesting rules, URL schemes or CRM permissions. A string containing an unpaired surrogate can fail during encoding before range decoding; route that error to the same explicit invalid-input handling in a real adapter. Do not advertise this short helper as a complete security boundary.

Use a staged mapping procedure

Select a supported message body and its matching entity list. Keep source identity, access scope and message version with the mapping job. Do not use a caption's ranges on a text message or combine entity lists from different versions.
Validate the body and metadata before producing derived fields. Resolve ranges in the documented coordinate system. Keep malformed inputs available only through the approved review process; avoid copying full enquiries into general application logs.
Produce the plain-text note without removing meaningful customer content. Resolve required links into separate records with labels and destinations. Apply a specific allowlist or review policy for supported entity kinds rather than assuming every new type has an equivalent CRM representation.
Construct the CRM payload through its documented API and escaping rules. If the target supports only plain text, send plain text. Do not enable a rich-text mode merely to make a single link clickable.
Read back the test record through the authorized CRM interface. Compare the complete note, link labels and targets against the intended representation. An HTTP success response cannot show whether the CRM removed markup or changed line breaks.
Record a mapping version and the observed outcome. Keep a rollback path for the adapter change, without sending duplicate notes or overwriting later operator edits. Retry behavior belongs to the operation's delivery design, not to the UTF-16 helper.

Use the separate webhook idempotency guide for repeated delivery and ambiguous CRM writes. Correct range extraction does not prevent a second note after an uncertain timeout. Conversely, deduplicating updates does not repair an incorrect link label in the first note.

Build acceptance cases around meaning

A useful regression set varies the position and kind of source content. Include plain ASCII text, Cyrillic text, an emoji before the entity, several entities in one message and a caption with a link. Add a label whose destination differs from its visible words. These are test fixtures, not real customer conversations or evidence that a deployed connector already passes.

For each case, write down the selected source field, exact source string, entity coordinates and expected extracted fragment. Then specify the intended CRM representation separately. A plain-text-only target may intentionally drop bold presentation while preserving every word. That is a supported conversion, not missing data, if the product owner approved it and the test records the decision.

Negative cases should include an out-of-range endpoint, a surrogate-splitting boundary, missing required destination metadata and an unsupported entity kind. Decide whether each produces a plain-text fallback, manual review or a failed mapping job. A fallback must not quietly imply that links were preserved when only labels survived. Keep the status visible to the operator who relies on the note.

Finally test edits: change the message body so the entity moves, and change a link destination while leaving the label unchanged. Verify that the new representation does not keep stale ranges or an old target. Compare the readback, not just the outgoing JSON. These are proposed integration acceptance tests; the local extraction diagnostic proves only its own artificial cases.

Close the incident at the boundary actually verified

A precise resolution might say: the mapper used Python indices for Telegram UTF-16 ranges; the new mapper passed the local extraction fixture, while CRM readback remains pending. That is more useful than declaring Telegram fixed or the sales pipeline healthy. If the source body was already changed before mapping, correct that ownership error as well as the arithmetic.

Monitor mapping failures by reason and adapter version, with only the minimum identifiers needed for investigation. Do not turn error telemetry into a second archive of private enquiries or link credentials. Before enabling production changes, assign responsibility for unsupported shapes and review access. The goal is a faithful, understandable CRM representation, not a promise to reproduce every Telegram presentation feature.

Sources

Telegram Bot API: Message, source fields and caption metadata, checked on the editorial date.
Telegram Bot API: MessageEntity, UTF-16 coordinates and type-specific fields, checked on the editorial date.

This article was also published on other platforms. Original: Telegram Message Entities: Keep Links and Emoji Intact in Your CRM

Текст Telegram в CRM: ссылки, эмодзи и смещения UTF-16 [перекрёстная публикация]

ALEKSANDR MICHAILOVICH — Thu, 05 Nov 2026 02:16:11 +0000

Если обращение из Telegram попало в CRM с неверной ссылкой или обрезанным словом после эмодзи, проверьте преобразование текста до изменения вебхука. Telegram описывает участки текста через смещения в кодовых единицах UTF-16. Диапазоны относятся к исходному тексту или подписи, а не к очищенной копии. Сохраняйте строку вместе с её разметкой, затем отдельно формируйте обычную заметку и проверенные записи о ссылках.

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

Сначала выберите исходное поле

В объекте Message предусмотрены необязательные text и entities для текстовых сообщений. Подпись к медиа использует caption и caption_entities. Каждый список описывает соответствующую строку. Фотография с подписью не является текстовым сообщением с неожиданно пустым телом: обработчик, который читает только text, может потерять обращение ещё до разбора форматирования.

Передавайте эти две пары в один преобразователь как разные варианты входа и записывайте, какая пара выбрана. Если у поддерживаемого сообщения нет ни одного поля, фиксируйте явный результат «нет текста» или «неподдерживаемый формат». Пустая заметка о продаже не должна выглядеть успешным переносом. Остальным видам сообщений нужен собственный разбор схемы; эта инструкция не является полным декодером всех нынешних типов Bot API.

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

Почему эмодзи сдвигает ссылку

Entity здесь означает типизированный участок строки: например, ссылку, упоминание или выделение. В контракте MessageEntity и offset, и length измеряются в кодовых единицах UTF-16. Срез строки Python использует позиции кодовых точек Unicode. Для многих обычных букв эти системы совпадают, но различаются для символов, представленных суррогатной парой UTF-16, включая улыбающееся лицо в примере.

Возьмём искусственную строку 😀 offer. Участок offer начинается со смещения UTF-16 3 и имеет длину 5. Эмодзи занимает две кодовые единицы, следующий пробел ещё одну. Обычный срез Python с позиции 3 до 8 вернёт ffer, а не нужное слово. Исключения может не быть: обработчик выдаст правдоподобный, но неправильный фрагмент.

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

Разделите исходник и представление в CRM

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

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

При обновлении сообщения рассматривайте новое тело и новые метаданные как одну версию. Не переносите старые entities на новый текст. Клиент может изменить и подпись ссылки, и её адрес. Если заменить только видимую заметку, отдельная запись о ссылке останется устаревшей даже при верном расчёте UTF-16. Отдельно согласуйте, должна ли CRM заменять заметку, добавлять редакцию или отправлять изменение на проверку.

Видимая подпись и адрес ссылки различаются

Entity типа url выделяет URL непосредственно в строке. У text_link в тексте находится видимая подпись, а отдельное необязательное поле url содержит адрес перехода. Если сохранить только выделенный фрагмент, адрес потеряется. Если показать адрес так, будто это исходная подпись, исчезнет различие между словами человека и целью перехода. Для процесса, которому нужны ссылки, сохраняйте оба значения и тип entity.

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

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

Входные данные	Что сохранить	Чего не следует заключать
`url`	Фрагмент исходной строки и тип	Что адрес безопасно открывать
`text_link`	Подпись и отдельный адрес	Что подпись описывает настоящий домен
`text_mention`	Подпись и допустимую ссылку на пользователя, если она нужна	Что подпись является постоянным username
`bold` или `italic`	Исходный текст и необязательное поддерживаемое оформление	Что выделение меняет приоритет заявки
`code` или `pre`	Буквальный текст и поддерживаемые метаданные	Что команду нужно выполнить
Неизвестный тип	Текст и явное решение о неподдерживаемом типе	Что всё сообщение обязательно удалять

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

Проверяйте диапазон перед извлечением

Проверяйте целочисленные координаты в пределах представления выбранной строки в UTF-16. Для этого преобразователя отклоняйте отрицательное смещение, неположительную длину, выход за конец и границу внутри суррогатной пары. Различайте некорректные метаданные и ошибку кодирования текста. Автоматический символ замены может скрыть, какой вход сломан; явный результат проверки проще расследовать.

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

def entity_text(text, offset, length):
    if not isinstance(text, str):
        raise ValueError("text must be a string")
    if type(offset) is not int or type(length) is not int:
        raise ValueError("coordinates must be integers")
    if offset < 0 or length <= 0:
        raise ValueError("invalid range")
    raw = text.encode("utf-16-le", errors="strict")
    start = offset * 2
    end = (offset + length) * 2
    if end > len(raw):
        raise ValueError("range outside text")
    try:
        return raw[start:end].decode("utf-16-le", errors="strict")
    except UnicodeDecodeError as exc:
        raise ValueError("range splits a surrogate pair") from exc

text = "😀 offer"
assert entity_text(text, 3, 5) == "offer"
assert text[3:8] == "ffer"
for offset, length in [(1, 1), (-1, 1), (3, 6), (True, 1)]:
    try:
        entity_text(text, offset, length)
    except ValueError:
        pass
    else:
        raise AssertionError("invalid range accepted")
print("UTF-16 extraction checks passed")

Сохраните блок в локальный файл Python и выполните в одноразовой среде. Ожидаемая строка терминала: UTF-16 extraction checks passed. Ошибка утверждения или исключение означают, что эта диагностика не пройдена; не меняйте ожидаемые значения молча. В исследовательских артефактах статьи сохранён фактический локальный запуск. Действующий бот и CRM в этой проверке не участвовали.

Функция не проверяет типы entities, обязательные поля отдельных типов, правила вложенности, схемы URL и разрешения CRM. Строка с непарным суррогатом может вызвать ошибку уже при кодировании, до декодирования диапазона. В настоящем адаптере направляйте такую ошибку в тот же явный процесс обработки некорректного входа. Короткий вспомогательный пример не является полной границей безопасности.

Порядок преобразования в интеграции

Выберите поддерживаемое тело сообщения и соответствующий список entities. Свяжите задание с источником, областью доступа и версией сообщения. Не применяйте диапазоны подписи к текстовому сообщению и не объединяйте списки разных версий.
Проверьте строку и метаданные до формирования производных полей. Извлекайте диапазоны в документированной системе координат. Некорректные входы должны быть доступны только через согласованный процесс разбора; не копируйте полные обращения в общие журналы приложения.
Сформируйте обычную заметку без удаления значимого клиентского текста. Нужные ссылки вынесите в отдельные записи с подписями и адресами. Задайте явный список поддерживаемых типов или правила проверки вместо предположения, что любой новый тип имеет аналог в CRM.
Подготовьте данные по документированному API и правилам экранирования конкретной CRM. Если цель поддерживает только обычный текст, отправляйте обычный текст. Не включайте форматированный режим ради одной кликабельной ссылки.
Перечитайте тестовую запись через разрешённый интерфейс CRM. Сравните полную заметку, подписи и адреса с задуманным представлением. Успешный HTTP-ответ не показывает, удалила ли CRM разметку или изменила переводы строк.
Запишите версию преобразователя и наблюдаемый результат. Подготовьте откат изменения адаптера без дублирующих заметок и перезаписи последующих правок оператора. Повторы относятся к устройству доставки операции, а не к функции извлечения UTF-16.

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

Проверяйте сохранение смысла

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

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

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

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

Завершайте расследование на проверенной границе

Точный результат может звучать так: преобразователь использовал индексы Python вместо смещений UTF-16; новая версия прошла локальный тест извлечения, но чтение результата CRM ещё предстоит. Это полезнее заявления, что Telegram исправлен или вся воронка работает. Если исходную строку меняли до разбора диапазонов, исправьте и порядок преобразований, а не только арифметику.

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

Источники

Telegram Bot API: Message: поля текста, подписи и их метаданные; проверено в редакционную дату.
Telegram Bot API: MessageEntity: координаты UTF-16 и поля отдельных типов; проверено в редакционную дату.

Эта статья также опубликована на других платформах. Оригинал: Текст Telegram в CRM: ссылки, эмодзи и смещения UTF-16

Telegram Bot Missing Events: Check allowed_updates Before Resetting Delivery [cross-post]

ALEKSANDR MICHAILOVICH — Tue, 03 Nov 2026 05:33:15 +0000

Telegram Bot Missing Events: Check allowed_updates Before Resetting Delivery

If your Telegram bot receives some events but misses another kind, check its update subscription and application routing before changing transport. allowed_updates selects update types; it does not grant access to a chat or prove that a CRM worker processed an event. Omitting the parameter preserves the previous setting. An empty list does not literally enable every update type.

This guide is for the maintainer of a custom Telegram Bot API integration that routes incoming enquiries to a CRM. You need authorized access to its configuration, sanitized diagnostics and a test environment. It does not describe a verified built-in 24go.site feature. The procedure below is a proposed operational test, not a claim that a live bot or CRM was tested while writing this article. No working token is needed to read the checklist.

First identify what is actually missing

“Messages stopped” can describe several different failures. A text message is normally represented by a message update; pressing an inline callback button produces callback_query; a channel post uses channel_post. Those are different fields on the Update object. A handler that only reads update.message will not process every event delivered in a valid update.

Write a specific incident statement: a human sent a new text message to the test bot in a private conversation at a known time, but the receiver did not persist a corresponding event. Compare that with “the event was persisted, but no lead appeared.” The second statement points beyond Telegram delivery. Record the event kind, chat type and last observed processing stage, not the complete conversation or a customer phone number.

Use a unique, non-sensitive marker for a controlled test. Keep it out of campaign automation and stop any downstream production sales action for the test identity through an approved test configuration. A successful diagnostic must not accidentally create a real follow-up sequence. If isolation cannot be established, stop before sending the test and have the integration owner arrange it.

There are separate gates between a user action and a lead

Think of the route as eligibility → subscription → transport → receiver → dispatcher → CRM worker. Eligibility means the bot may receive that kind of event in that chat. Subscription means the configured list permits its update type. Transport concerns webhook or polling delivery. The receiver validates and durably accepts the request. The dispatcher chooses an application handler. Finally, a worker performs a permitted business operation.

Changing one gate does not fix the others. Adding message to a subscription cannot grant visibility into arbitrary group conversations. Granting a bot more group permissions cannot make a dispatcher handle callback_query. Returning HTTP success does not show that an event reached durable storage. Seeing a persisted event does not establish that the CRM committed a new record.

The Bot FAQ describes privacy-mode rules for ordinary group messages, including commands addressed to a bot and replies. Use those rules only within their stated scope. The API changelog now also describes newer bot-to-bot and guest-mode capabilities, while older FAQ statements are broader. This guide deliberately uses a human sender and ordinary private messages for its baseline, not another bot, guest messages or a claim that all current bot communication modes behave identically.

What allowed_updates does, including the exceptions

The current setWebhook contract and getUpdates contract document three important cases:

Configuration input	Documented meaning	Diagnostic consequence
Parameter omitted	Reuse the previous setting	Redeploying without the field is not a reset
Explicit list such as `["message", "callback_query"]`	Subscribe to those update types	Other required types need an explicit decision
Empty list `[]`	All update types except `chat_member`, `message_reaction`, `message_reaction_count`	Do not describe this as an unrestricted subscription

There are further eligibility requirements for particular types. The Update documentation says chat_member requires the bot to be an administrator and the type to be explicitly requested. Reaction updates also have their own documented requirements. Do not add all possible types as a generic troubleshooting step: each additional event class needs a handler, access policy and data-retention decision.

For private chats, my_chat_member concerns the bot being blocked or unblocked. It is not the same event as a change to another member represented by chat_member. If your application expects one and subscribes to the other, a transport restart will not repair the mismatch. Match the required business signal to the exact update field before editing the subscription.

These settings do not retroactively change updates created before the configuration call. Telegram explicitly warns that unwanted updates may still arrive briefly. Your receiver must remain able to reject, ignore or safely store unsupported older events according to policy. A configuration response reporting success is not proof that every subsequent request immediately has only the new shape.

Inspect without switching delivery modes

For a webhook bot, have the authorized operator inspect getWebhookInfo through the existing safe administration tool. The method reports the webhook URL, pending-update count and optional error details and subscription information. Review the response before sharing it: the URL may reveal internal routing or sensitive path data. Never paste the bot token, full command URL or secret header into a support ticket.

A nonempty webhook URL establishes that a webhook is configured, not that its current receiver is healthy. A pending count is a point-in-time measure of updates awaiting delivery, not an application backlog metric. A zero count does not prove a user action was eligible, subscribed to, delivered and processed. Optional last-error fields describe an observed error, not the full history of every attempt or a guaranteed current outage.

If the URL is empty, first establish who owns polling and where its configuration is recorded. Do not launch a second polling consumer from your laptop as a diagnostic. The API documents that getUpdates does not work while an outgoing webhook is set. Polling also has acknowledgement behavior through offset; a casual test can interfere with the application's update handling. Transport switching is a separate planned operation, not a harmless way to inspect missing event types.

Compare three things: the intended subscription in deployment configuration, the request actually used by the current integration to register or poll, and observable state from the authorized management path. A framework can generate that request for you, so checking only a handwritten configuration file may miss the active behavior. Record configuration versions, not secret values.

Use observations to choose the next investigation

Observation in the isolated test	Next boundary to inspect	Avoid concluding
Private human message absent at ingress	Bot identity, subscription and transport evidence	That the CRM discarded it
Message arrives but callback does not	`callback_query` subscription and callback dispatch	That all Telegram delivery is broken
Private test works; ordinary group text does not	Group eligibility, privacy mode and intended interaction	That broader privileges are automatically necessary
Raw accepted update contains the expected field; handler does not run	Application router and supported update schema	That resetting the webhook will fix code
Handler runs; CRM result is missing	Worker receipt, business rules and CRM reconciliation	That Telegram lost the update
Older unwanted event appears after filter change	Creation time and documented transition behavior	That the new subscription is necessarily ignored

A sanitized ingress record should establish which top-level event field was present and whether durable acceptance succeeded. It need not retain every message body indefinitely. If your only observable signal is “no reply,” add narrow test diagnostics before changing permissions: reply sending is itself a separate operation and can fail even when receipt worked.

For the authentication boundary, use the separate webhook secret validation guide. For repeated accepted events and uncertain CRM writes, use the idempotency guide. Those controls remain necessary but answer different questions from an update-type subscription.

A controlled change and acceptance procedure

Record the intended business events and map each to an exact Update field. Identify an owner for every handler. Include existing required types when proposing the replacement list; do not silently remove working flows.
Save a sanitized baseline: transport owner, active configuration version, relevant subscription evidence and the stages currently observable. Keep private routing and credentials in their approved store, not the incident report.
Review the proposed change in the integration's normal deployment workflow. Registration parameters include more than the update list. Preserve approved endpoint, certificate and authentication settings rather than improvising a fresh command from a blog example.
Apply only the approved subscription change through that workflow. Do not set drop_pending_updates to clear an error: the documented purpose of that option is to drop pending updates, not repair routing.
Generate a new human private-message test and each additional required interaction in the isolated environment. Check the exact event field, durable receipt, selected handler and downstream test result separately.
Repeat a previously working event class as a regression test. A newly arriving callback is not a success if the change stopped message processing. Observe old queued events without treating their mere presence as a failed configuration.
Record results and either retain the configuration or roll back through the same approved path. A rollback is another configuration transition; it does not recover events already discarded or guarantee retroactive delivery of excluded events.

Define success before the change. For example, the private human message should produce an accepted message receipt, reach the intended test handler and yield the expected test record or explicit no-write decision. A callback test should produce a separate callback receipt and its own authorization result. No live timing or delivery guarantee is inferred from this proposed plan.

What the incident report should say

Close the incident with the narrowest supported finding: which event class was absent, which boundary failed, what configuration changed, and what fresh tests passed. Attach sanitized request metadata and configuration revision references. If only the subscription mismatch was corrected, say that; do not claim the entire sales funnel is healthy.

If evidence stops at ingress, leave downstream delivery unverified. If no authorized bot-management access exists, record that blocker instead of borrowing credentials or deleting the webhook. If group eligibility remains uncertain, keep the human private-message baseline separate from a future permission review. A quiet bot can be healthy in an inactive chat, and an active webhook can still feed a broken worker. Only a controlled observation across the relevant boundaries resolves the particular missing-event question.

This article was also published on other platforms. Original: Telegram Bot Missing Events: Check allowed_updates Before Resetting Delivery

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

ALEKSANDR MICHAILOVICH — Tue, 03 Nov 2026 05:33:14 +0000

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

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

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

Сначала уточните, чего именно нет

За словами «перестали приходить сообщения» могут стоять разные сбои. Обычное текстовое сообщение представлено обновлением message, нажатие inline-кнопки с callback — callback_query, публикация канала - channel_post. Это разные поля объекта Update. Если обработчик читает только update.message, он не обработает все события, которые сервер корректно доставил приложению.

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

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

Между действием человека и лидом несколько независимых границ

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

Изменение одной границы не исправляет остальные. Добавление message в список подписки не открывает произвольные групповые разговоры. Дополнительные права в группе не заставят диспетчер обрабатывать callback_query. Успешный HTTP-ответ не доказывает сохранение события. Сохранённое событие ещё не означает, что CRM зафиксировала новую запись.

В FAQ Telegram описаны правила privacy mode для обычных групповых сообщений, включая команды, адресованные боту, и ответы. Применяйте их в указанных границах. В актуальном журнале изменений API также описаны новые возможности общения между ботами и guest mode, тогда как старые формулировки FAQ шире. Поэтому исходный тест здесь - сообщение человека в обычном личном чате. Мы не используем другого бота, гостевые сообщения и не утверждаем, что все нынешние режимы общения работают одинаково.

Что означает allowed_updates и где исключения

В текущих контрактах setWebhook и getUpdates описаны три важных варианта:

Входная настройка	Документированный смысл	Следствие для диагностики
Параметр отсутствует	Используется предыдущая настройка	Повторный деплой без поля не сбрасывает фильтр
Явный список, например `["message", "callback_query"]`	Подписка на перечисленные типы	Остальные необходимые типы требуют отдельного решения
Пустой список `[]`	Все типы, кроме `chat_member`, `message_reaction`, `message_reaction_count`	Нельзя называть такой режим неограниченной подпиской

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

В личных чатах my_chat_member относится к блокировке или разблокировке бота пользователем. Это не то же самое, что изменение статуса другого участника через chat_member. Если программа ждёт одно событие, а подписана на другое, перезапуск транспорта не устраняет расхождение. До правки настройки сопоставьте нужный бизнес-сигнал с точным полем Update.

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

Посмотрите состояние, не переключая транспорт

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

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

Если URL пустой, сначала выясните, кто управляет polling и где записаны его настройки. Не запускайте второй потребитель обновлений на своём ноутбуке ради проверки. Документация говорит, что getUpdates не работает при установленном исходящем вебхуке. Кроме того, polling подтверждает обновления с помощью offset: случайный тест способен вмешаться в обработку приложения. Переключение транспорта — отдельное плановое изменение, а не безвредный просмотр пропавших типов событий.

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

Как выбрать следующую проверку по наблюдению

Наблюдение в изолированном тесте	Следующая граница проверки	Чего оно ещё не доказывает
Личное сообщение человека отсутствует на входе	Идентичность бота, подписка и транспорт	Что его отбросила CRM
Сообщение приходит, callback отсутствует	Подписка `callback_query` и диспетчер callback	Что вся доставка Telegram сломана
Личный тест работает, обычный групповой текст нет	Допустимость в группе, privacy mode и задуманный сценарий	Что обязательно нужны более широкие права
В принятом Update есть нужное поле, обработчик не запущен	Прикладной маршрутизатор и поддерживаемая схема	Что сброс вебхука исправит код
Обработчик запущен, результата CRM нет	Квитанция исполнителя, бизнес-правила и сверка CRM	Что Telegram потерял событие
После смены фильтра пришло старое ненужное событие	Время создания и документированный переход	Что новая подписка обязательно проигнорирована

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

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

Порядок управляемого изменения и приёмки

Запишите необходимые бизнес-события и сопоставьте каждое с точным полем Update. Назначьте ответственного за обработчик. В предложенный список включите уже необходимые типы: нельзя незаметно убрать работающий сценарий.
Сохраните обезличенное исходное состояние: владельца транспорта, версию активной конфигурации, доступные доказательства подписки и наблюдаемые этапы. Частные адреса и секреты оставьте в предусмотренном хранилище, а не в отчёте об инциденте.
Проверьте изменение в обычном процессе развёртывания интеграции. Параметры регистрации не ограничиваются списком событий. Сохраните согласованные endpoint, сертификат и аутентификацию, не собирайте новую команду по общему примеру из статьи.
Примените через этот процесс только согласованную правку подписки. Не включайте drop_pending_updates, чтобы убрать ошибку: документированное назначение параметра — удаление ожидающих обновлений, а не исправление маршрутизации.
В изолированной среде создайте новое личное сообщение человека и каждое дополнительное необходимое взаимодействие. Раздельно проверьте поле события, надёжную квитанцию приёмника, выбранный обработчик и тестовый результат следующего этапа.
Повторите ранее работавший тип события как регрессионный тест. Появление callback не является успехом, если после правки перестали обрабатываться сообщения. Наблюдайте старые события очереди, не считая само их присутствие признаком неисправной настройки.
Зафиксируйте результат и оставьте настройку либо откатите её тем же согласованным способом. Откат - ещё один переход конфигурации: он не возвращает уже удалённые события и не гарантирует ретроспективную доставку исключённых типов.

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

Что написать в отчёте об инциденте

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

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

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

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