# Google Таблицы: блок «Поиск строки»

Source: https://docs.botman.pro/a/242-google-tablitsy-blok-poisk-stroki

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

Где может пригодиться «Поиск строки»

- Подставить имя или email пользователя, если он уже есть в базе, — не спрашивать повторно.
- Найти заявку по её номеру и вывести статус, дату, сумму или комментарий.
- Показать персональное предложение на основе данных из таблицы.
- Ограничить доступ к шагу, если пользователя нет в списке (например, участников вебинара).
- Отследить заказ по ID, указав дату, курьера, статус доставки.
- Запустить разную логику сценария в зависимости от значения в таблице (например, если статус = «VIP» → одно сообщение, если «Новый» — другое).
- Показать, кто из команды обрабатывает заявку, если менеджер указан в таблице.
- Подставить накопленную статистику (например, кол-во покупок, баллы, сумму заказов).
- Фильтровать клиентов для повторного маркетинга, сравнивая значения в таблице (например, кто был на акции — кто нет).
- Сделать связку с другими системами, если выгружаются данные вручную в таблицу из CRM, Google Forms или 1С.

---

**Где найти блок «Поиск строки» и как его добавить**

Чтобы использовать блок «Поиск строки» в сценарии, сначала его нужно добавить на канву конструктора. Для этого:

Перейдите в нужный сценарий **⟶** шаг с типом «Действие» **⟶** «Добавить блок» **⟶** выберите вкладку «Интеграции Google Таблицы» **⟶** «Поиск строки».

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

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/691f22d1c56b3db5e0ace6c2e65719b702a894baefac849a8463aaa434667ab7.png)

**❗Важно:** блок работает только при активной интеграции с Google

Для использования блока «Поиск строки» необходимо, чтобы Google-аккаунт был подключён через раздел «Интеграции».

Если интеграция не настроена, блок работать не будет: вы не сможете выбрать таблицу, настроить поиск или выполнить действия.

👉 Как подключить Google Таблицы — [см. инструкцию по интеграции](https://docs.botman.pro/a/228-integratsiya-s-google-tablitsami)

---

**Что нужно подготовить в Google Таблице перед настройкой блока**

Чтобы блок «Поиск строки» работал корректно, важно заранее правильно оформить структуру Google Таблицы. Ниже перечислены основные требования и рекомендации:

✅ 1. Заголовки в первой строке

- Первая строка таблицы (строка 1) должна содержать названия столбцов — например: Email, Телефон, ID, Имя, Статус.
- Именно эти заголовки вы будете выбирать при настройке блока и сопоставлении переменных.
- Если заголовков нет — блок не сможет корректно работать с таблицей.

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/74fbf892c76a605d29f170ee0f2758ae1dac6f88943832ad0b2172f0f48d61aa.png)

✅ 2. Используются только столбцы от A до Z

- При подключении таблицы BotMan запрашивает только первые 26 столбцов — от A до Z.
- Даже если в таблице есть более широкие столбцы (AA, AB и т. д.) — они не будут отображаться и не смогут участвовать в поиске.

**📌 Пояснение:**\
В Google Таблицах действительно существуют столбцы за пределами Z — например, AA, AB и далее.\
Они просто не отображаются, пока вы не начнёте в них вводить данные.

Однако в некоторых случаях эти столбцы могут появиться автоматически:

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

🔧 BotMan по техническим причинам обрабатывает только диапазон A1–Z1 — это ограничение со стороны API.\
Поэтому всё, что находится за пределами этих колонок, не будет подгружено при настройке блока.

✅ 3. Уникальные значения для поиска

- Рекомендуется использовать для поиска уникальные идентификаторы: Telegram ID, email, номер заявки.
- Если значение не уникально — будет выбрано первое совпадение.
- Если переменная пуста — поиск не выполнится.

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/063eb1124efa5362ef855a540cf08db204e2c755e54ae0e81ad811b326d741ed.png)

✅ 4. Доступ к таблице из подключённого аккаунта

Для корректной работы таблица должна быть доступна подключённому Google-аккаунту с правами «Редактор».

Возможны два варианта:

- таблица принадлежит аккаунту, подключённому в интеграции;
- таблица расшарена на этот аккаунт напрямую или по ссылке — обязательно с правами «Редактор».

🔒 Если у подключённого аккаунта есть только права:

- Читатель — блок не работает, данные не загружаются;
- Комментатор — также не работает;
- Редактор — ✅ всё работает корректно.

📌 При недостаточных правах блок не покажет ошибку, но данные не будут подгружаться или записываться — это может выглядеть как «тихий сбой».

✅ 5. Пустая таблица — это нормально, но учтите нюансы

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

📌 Рекомендация: для отладки и проверки работы блока удобно временно добавить 1–2 строки данных — чтобы убедиться, что всё работает правильно.

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

---

**Пошаговая настройка блока «Поиск строки»**

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

**Шаг 1: Вставьте ссылку на Google Таблицу**

В поле «Ссылка на таблицу» вставьте URL из адресной строки Google Таблиц.\
Пример: `https://docs.google.com/spreadsheets/d/1aBcD...`

После этого автоматически подгрузится список рабочих листов — они появятся в выпадающем списке ниже.

Обратите внимание:

- Таблица должна быть доступна из подключённого аккаунта, иначе листы не подгрузятся.
- В таблице должна быть хотя бы одна строка с заголовками (первая строка).
- Если вы не видите список листов — проверьте права доступа и правильность ссылки.

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/e16537c3f662dba5a37b633aa492a9dde4046066a7db9114bbddae07b4db6207.png)

**Шаг 2: Выберите рабочий лист**

После того как вы вставили ссылку на Google Таблицу, BotMan автоматически подгрузит список всех листов, которые есть в этом файле.

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

**❗Обратите внимание:**

- Если список не подгружается:\
  \- проверьте корректность ссылки;\
  \- убедитесь, что у подключённого аккаунта есть доступ к таблице;\
  \- проверьте, есть ли заголовки в первой строке на выбранном листе (A1–Z1).
- Если названия листов слишком длинные, они могут обрезаться визуально — но данные при этом подтягиваются корректно.

⚠️ Если выбранный лист не содержит заголовков, BotMan покажет предупреждение и не позволит продолжить настройку.

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/dd6515b0316a7e7e3dfc323069bcdc60f0248386f027aa3c3e6198ad16762a7b.png)

**Шаг 3: Укажите столбец для поиска**

После выбора листа появится возможность указать столбец, по которому будет происходить поиск нужной строки.

Этот столбец должен содержать уникальные значения — например:

- Telegram ID
- Email
- Номер телефона
- ID заявки
- Уникальный код

Важно:

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

Рекомендация:

Лучше всего использовать поле, которое гарантированно уникально для каждого пользователя — например, Telegram ID.\
Номер телефона может иметь разный формат (+7, 8, пробелы), что приведёт к ошибкам в сопоставлении.

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/b95257f5c3ea5ae412df029f32bc71e2243cdb23cdfd576fc22c9ed68e4710bf.png)

**Шаг 4: Укажите значение для поиска**

Теперь нужно указать, какое значение бот будет искать в выбранном столбце.\
Это значение подставляется из карточки подписчика — чаще всего это переменная, уже полученная в сценарии ранее (например, при подписке или вводе данных).

В поле «Искомое значение» доступны следующие источники:

- Системные переменные — Telegram ID, Email, Телефон, Имя, Статус активности и др.
- Пользовательские поля — Отображаются все созданные вами поля в разделе: Настройки → Пользовательские поля
- Глобальные переменные — Общие переменные, созданные в разделе: Настройки → Глобальные переменные
- Метки — Отображается весь список меток, созданных в вашей учётной записи (независимо от того, назначены ли они пользователю или нет)

Обратите внимание:

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

Рекомендуем:

Перед использованием блока «Поиск строки» добавьте шаг «Проверка поля» (блок Условие), чтобы убедиться, что переменная содержит значение. Это поможет избежать «тихих» сбоев, когда данные просто не подтягиваются.

Пример:

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

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/0bc0db99a8ff7b957e2d2e092f4ed7d25d53181a7bb36fdda718c043dfb63f95.png)

**Шаг 5: Укажите, какие данные из таблицы сохранить в переменные**

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

Для этого укажите:

- из какого столбца таблицы брать значение (слева),
- и в какую переменную платформы сохранить это значение (справа).

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

**Пример:** Столбец Имя из таблицы → переменная {{user\_name}}

Что произойдёт при выполнении блока:

- ✅ Если строка найдена — значения из указанных столбцов будут автоматически записаны в выбранные переменные.
- ❌ Если строка не найдена — переменные не будут заполнены, но бот продолжит сценарий без ошибок (переменные останутся пустыми или со старым значением).

Обратите внимание:

- Вы можете сопоставить любое количество столбцов — от одного до всех, доступных в таблице (в пределах A–Z).
- Название переменной нельзя ввести вручную — необходимо выбрать из выпадающего списка.

В списке отображаются:

- Системные переменные (например, Имя, Телефон) — только те, в которые разрешена запись. Технические системные переменные (например, Дата подписки, Статус пользователя, Telegram ID) нельзя перезаписывать — они доступны только для чтения.;
- Пользовательские поля, созданные вами;
- Глобальные переменные, добавленные в настройках.

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/150f03275fc3c8f245a2bb5b717d3205b990bb0dcaa6c8c850459aaed8c26fb6.png)

**✅ Финальный шаг: протестируйте сценарий**

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

Как это сделать:

1. В режиме редактирования сценария перейдите в верхнюю панель.
2. Нажмите кнопку «Тестировать».
3. Выберите режим:

- Тестировать — запускает сценарий с задержками, как увидит пользователь.
- Тестировать без задержек — ускоренный запуск без пауз и таймеров.

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/bab93f7a40235a28ad0669c0903bf5541e9e2b6d9207e49baf831b30b75d56aa.png)

Что проверить:

- Значение переменной (например, {{Имя}} или {{Email}}) — подставилось ли оно из таблицы?
- Если строка не найдена — ведёт ли сценарий себя корректно (нет ошибок, переходы работают)?
- Если переменная пуста — отрабатывает ли логика, которую вы предусмотрели (например, через блок «Проверка поля»)?
- Все нужные поля из таблицы попали в переменные?

💡 Советы:

- Для тестов удобно временно добавить в таблицу тестовую строку с заранее известными данными.
- Используйте блок «Проверка поля» для отладки: покажет, какое значение реально подставилось.
- Не забудьте после тестирования вернуть сценарий к нужному виду и нажать «Опубликовать».

Дополнительные причины, почему блок может не сработать (даже если всё настроено правильно)

---

Иногда поиск строки **не работает** не из-за ошибок в настройке блока, а по внешним причинам.\
Вот список возможных ситуаций:

**1️⃣ Интеграция была отключена**

Что происходит:

- Таблица и лист не подгружаются.
- Данные не ищутся, блок не выполняется.

Причина:

- Интеграция вручную отключена в разделе «Интеграции».
- Аккаунт вышел из системы Google или сменил доступ.

Что делать:

- Перейдите в раздел «Интеграции» и подключите Google-аккаунт заново.
- Убедитесь, что выбран нужный аккаунт.

**2️⃣ Были отозваны права доступа в Google**

Что происходит:

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

Причина:

- Пользователь отменил доступ BotMan в настройках Google.
- Доступ просрочился или был отозван системой безопасности Google.

Что делать:

- Переподключите интеграцию: нажмите «Отключить», затем снова «Подключить».
- Убедитесь, что выдали все необходимые права (особенно для работы с таблицами).

**3️⃣ Таблица была удалена или перемещена**

Что происходит:

- Ссылка на таблицу остаётся в блоке, но файл в Google Drive больше не существует.
- Блок не находит таблицу, не выполняет поиск.

Что делать:

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

**4️⃣ Изменился доступ к таблице**

Что происходит:

- Таблица была расшарена, но права были изменены на «Читатель» или «Комментатор».
- В результате: данных нет, но ошибок тоже нет.

Что делать:

- Проверьте в Google Таблицах, кто имеет доступ к таблице.
- Убедитесь, что у нужного аккаунта есть права «Редактор».

**5️⃣ Таблица принадлежит другому аккаунту**

Что происходит:

- Вы вставили ссылку на таблицу, которая не доступна подключённому аккаунту.

Что делать:

- Убедитесь, что таблица:\
  \- либо создана в подключённом аккаунте;\
  \- либо расшарена на него с правами «Редактор».

**6️⃣ Таблица изменилась после настройки блока**

Что происходит:

- Заголовки были переименованы или удалены.
- Столбец поиска больше не существует.

Что делать:

- Откройте блок и перепроверьте настройки:\
  \- Сопоставления переменных;\
  \- Столбец поиска;\
  \- Наличие нужных данных.

**💡 Как избежать "тихих сбоев":**

- Всегда используйте блок «Проверка поля» после поиска, чтобы убедиться, что данные действительно получены.
- Добавляйте тестовые строки в таблицу на этапе разработки.
- Храните резервную копию таблицы, если сценарий критичный.