Как связать клиента Telegram не по username, а по телефону

Для технической связи сохраняйте Telegram user.id. Телефон нужен для первоначального поиска клиента в CRM, а username оставьте отображаемым атрибутом.

Получив номер согласованным способом, нормализуйте его и вызовите crm.duplicate.findbycomm с type: 'PHONE', entity_type: 'CONTACT' и массивом values. В ответе проверьте число найденных контактов.

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

Сохраните подтверждённую пару Telegram ID ↔ CRM contact ID отдельно от username. При смене номера предусмотрите повторное подтверждение связи. Для выдачи персональных документов одного совпадения номера может быть недостаточно — это отдельная проверка доступа.