# Что такое интеграция с Albato

Source: https://docs.botman.pro/a/64-chto-takoe-integratsiya-s-albato

[Albato](https://albato.ru/app-botman) — сервис-коннектор, который связывает BotMan с более чем 1000 сервисов без программирования: CRM, учётными системами (1С, МойСклад), Google Таблицами, мессенджерами, платёжными и рекламными системами.

Интеграция работает в обе стороны:

- **из BotMan в другие сервисы** — события бота (новый подписчик, входящее сообщение, добавленный тег, оплата) запускают связку в Albato;
- **из других сервисов в BotMan** — по событию во внешнем сервисе можно отправить подписчику сообщение, поставить тег, записать поле, запустить или остановить сценарий.

Что можно сделать:

- передавать новых подписчиков, заявки и оплаты в CRM, 1С или Google Таблицы — вместе с тегами и пользовательскими полями;
- по оплате или смене статуса во внешней системе отправлять сообщение или запускать сценарий в боте;
- синхронизировать теги, поля и статусы подписчиков;
- собирать уведомления и аналитику в одном месте.

Эта статья — общая инструкция и справочник. Пошаговые разборы конкретных связок собраны в разделе «Готовые связки» ниже.

## Что понадобится

| Что | Зачем | Где взять |
| --- | --- | --- |
| Платный тариф BotMan | Триггеры BotMan (события бота) работают только на платных тарифах. Действия в BotMan доступны на любом тарифе | Раздел [«Тарифы»](https://docs.botman.pro/a/148-tarify-botman-kakoy-plan-vybrat) в личном кабинете BotMan |
| Аккаунт в Albato | Связки собираются и работают на стороне Albato | [Регистрация в Albato](https://new.albato.ru/user/signup?lang=ru) |
| Тариф Albato | У Albato свои тарифы и лимит транзакций; оплачивается отдельно от BotMan. Есть пробный период | [Тарифы Albato](https://albato.ru/pricing) |
| Доступ ко второму сервису | Чтобы подключить CRM, 1С, таблицу и т.д. в Albato | Личный кабинет этого сервиса |

---

## **Как зарегистрироваться в Albato**

1. Перейдите на [страницу регистрации Albato](https://new.albato.ru/user/signup?lang=ru).
2. Выберите страну в окне «Выберите страну» и нажмите **«Подтвердить»**. От страны зависит, в каком регионе Albato будет хранить ваши данные.

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

3. Проверьте страну в строке над кнопками регистрации. Если она определилась неверно, нажмите **«изменить»** рядом с ней. Язык интерфейса можно переключить в правом верхнем углу.
4. Зарегистрируйтесь через мессенджеры или по email и паролю.
5. Отметьте согласие с условиями сервиса и политикой конфиденциальности и нажмите кнопку регистрации.

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

---

## Как подключить BotMan к Albato

Подключение строится на API-ключе BotMan: вы создаёте ключ в личном кабинете и вставляете его в Albato. Это делается один раз.

**Шаг 1️⃣. Получите API-ключ в BotMan**

1\. Войдите в личный кабинет BotMan.\
2\. Откройте раздел **Интеграции** — или сразу перейдите по [прямой ссылке](https://app.botman.pro/app/integration/extensions).\
3\. Нажмите **«Подключить API»** — будет создан персональный API-ключ.

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

4\. Скопируйте ключ.

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

API-ключ даёт доступ к данным вашего аккаунта — не передавайте его третьим лицам. Если ключ перевыпустить, старый перестанет работать: обновите его в подключении BotMan в Albato, иначе все связки остановятся.

**Шаг 2️⃣. Создайте подключение в Albato**

1\. В Albato создайте новую связку или откройте существующую\
2\. В верхнем меню откройте **Automations** и нажмите **Create new automation**. Чтобы изменить существующую связку, выберите её в списке на этой же странице.

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

3\. Откроется редактор связки. Нажмите **Add trigger**, если связку должно запускать событие в BotMan, или **Add action**, если BotMan должен выполнить действие.

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

4\. В списке приложений выберите **BotMan**.

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

5\. В поле **Choose an event** выберите событие (для триггера) или действие BotMan (рассказываем ниже про это).

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

6\. В блоке **Connect your BotMan account to Albato** откройте список **Choose BotMan connection to Albato** и нажмите **Add a connection**.

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

7\. В окне **Create a connection to BotMan** заполните два поля:

- **Name your connection** — понятное название подключения (по умолчанию My Account BotMan). Если у вас несколько аккаунтов BotMan, дайте им разные названия;
- **Open api token** — вставьте API-ключ из шага 1.

8\. Нажмите **Continue**.

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

Подключение можно создать и заранее, без связки, в разделе **Apps** верхнего меню. Кнопка **Create from template** на странице Automations создаёт связку из готового шаблона.

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

**Шаг 3️⃣. Проверьте подключение**

1\. Если ключ верный, появится сообщение **Connection successfully created**. Нажмите **Continue**.

2\. Подключение появится в поле **Connect your BotMan account to Albato** с ID вашего аккаунта BotMan (например, My Account BotMan ID 40083). Нажмите **Continue**.

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

3\. Для триггера Albato предложит проверку **Test your trigger**: **Test** получит пример данных из вашего аккаунта, **Skip testing** пропустит проверку. Пример данных нужен, чтобы подставлять поля в следующие шаги связки.

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

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

---

## Триггеры: какие события BotMan запускают связку

Триггеры BotMan работают только на платных тарифах. Запуская связку, Albato подписывается на события вашего аккаунта, а подписка на события доступна на платном тарифе BotMan.

| Триггер | Название в Albato | Когда срабатывает |
| --- | --- | --- |
| Новый подписчик | New subscriber | Пользователь впервые подписался на бота. Передаёт данные подписчика, теги и пользовательские поля |
| Входящее сообщение | Incoming message | Подписчик написал боту (особенности — ниже) |
| Изменение подписчика | Subscriber updated | У подписчика изменились теги, системные или пользовательские поля. Что именно изменилось — в поле «Изменённые поля» (Updated fields) |
| Добавление тега подписчику | Tag added | Подписчику назначен тег |
| Новая оплата | Payment received | Подписчик оплатил счёт через платёжную систему, подключённую в BotMan |

**Особенности триггера «Входящее сообщение» (Incoming message)**

Данные приходят в одинаковом виде для всех платформ:

- **тип сообщения** показывает платформу: msg\_in\_telegram, msg\_in\_vk и т.д.;
- **тип контента** — текст, картинка, видео, файл или голосовое;
- **текст сообщения** — текст или подпись к медиа.

Учтите при настройке:

- отредактированное сообщение приходит в связку повторно;
- во ВКонтакте каждое вложение приходит отдельным событием с тем же текстом;
- стикеры в Telegram событие не создают.

Каждый триггер передаёт в связку данные события (подписчик, канал, тег, платёж), которые можно подставлять во все следующие шаги. Во всех триггерах есть поле **«ID подписчика»** — передавайте его в действия BotMan, чтобы они нашли нужного подписчика.

**Пользовательские поля и теги.** В триггерах «Новый подписчик» и «Изменение подписчика», а также в действиях «Поиск подписчика» и «Получение подписчика по ID» пользовательские поля приходят отдельными полями — с названиями из BotMan и подходящими типами: число, дата, дата и время, да/нет, список. Теги приходят списком названий. Если нужного поля нет в списке переменных, нажмите **«Обновить»** в блоке «Пользовательские поля» шага связки — Albato подтянет актуальные поля аккаунта.

Открытый вопрос: перечислить платёжные системы, оплаты из которых попадают в триггер «Новая оплата».

---

## Действия: что можно сделать в BotMan

Большинству действий нужен **«ID подписчика»** — это ID подписчика в BotMan, а не ID пользователя в соцсети. Возьмите его из любого триггера BotMan или из действия «Поиск подписчика» (подробнее — в следующем разделе).

| Действие | Что делает |
| --- | --- |
| Отправка сообщения | Отправляет подписчику текст, вложение или и то и другое. Вложение — картинка, видео, файл или аудио по публичной ссылке http(s), до 50 МБ. Сообщение уходит в канал, из которого пришёл подписчик. Для отложенной отправки заполните «Отложить на» и «Единицу времени» (минуты, часы, дни) |
| Поиск подписчика | Находит подписчика по значению поля (телефон, email, имя пользователя, ID в соцсети, имя, фамилия) и возвращает его данные, теги, пользовательские поля и «ID подписчика». Значение должно совпадать точно |
| Получение подписчика по ID | Возвращает те же данные по «ID подписчика» |
| Изменение / сброс системного поля | Записывает или очищает имя, фамилию, телефон, email, заметку или UTM-метку |
| Изменение / сброс пользовательского поля | Записывает или очищает значение пользовательского поля из списка. Для поля-списка передайте код варианта, а не подпись. Поля с множественным выбором не заполняются |
| Изменение глобального поля | Записывает значение в глобальное поле — оно общее для всех подписчиков аккаунта |
| Запуск сценария | Запускает сценарий для подписчика. Сценарий должен быть из того же канала, что и подписчик (канал указан рядом с названием). «ID шага для старта» необязателен: без него сценарий начнётся с первого шага. Чтобы получить ID шага, откройте сценарий в конструкторе (в черновике или опубликованной версии), нажмите на три точки в верхней части шага и выберите «Скопировать ID шага». ID выглядит так: b23fe241-89d0-c501-b971-c6e12e290c82 |
| Остановка сценария | Останавливает сценарий у подписчика и отменяет запланированные шаги. Если сценарий не запущен, ничего не происходит |
| Запуск рассылки | Запускает рассылку из списка рассылок аккаунта по аудитории из её настроек |
| Добавление / удаление тега | Назначает или снимает тег из списка тегов аккаунта |
| Кастомный API-запрос | Вызывает любой метод API BotMan, если подходящего готового действия нет |

Сценарии каналов-эмуляторов через API не запускаются, а тестовые подписчики эмулятора не находятся поиском.

Для «Кастомного API-запроса» используйте методы API BotMan: обзор и примеры — в статье [Начало работы с API BotMan](https://docs.botman.pro/a/215-nachalo-raboty-s-api-botman), полный список методов — в [документации API (Swagger)](https://api.botman.pro/swagger-ui/index.html?operationsSorter=alpha&tagsSorter=alpha&configUrl=/v3/api-docs/swagger-config). Базовый URL — https://api.botman.pro, ключ передаётся в заголовке X-Api-Key.

---

## Как найти подписчика, если связка начинается во внешнем сервисе

Если триггер — событие в CRM, 1С или таблице, «ID подписчика» в нём нет. Сначала найдите подписчика в BotMan, потом выполняйте действие.

1. Триггер во внешнем сервисе (например, «Сделка перешла в этап» или «Новый документ»).
2. Действие **BotMan → Поиск подписчика**: поле поиска — телефон или email, значение — из триггера.
3. Действие BotMan (сообщение, тег, сценарий): в «ID подписчика» подставьте результат шага 2.

Что важно учесть:

- Значение должно совпадать с тем, что хранится в BotMan, символ в символ. Чаще всего поиск не срабатывает из-за разного формата телефон в системном поле BotMan хранится в международном формате с плюсом, например +79991234567. Если во внешнем сервисе номер записан иначе (7…, 8…, с пробелами или скобками), поиск его не найдёт — приведите номер к формату +7… инструментами Albato для обработки данных.
- Если подписчик может не найтись, добавьте после поиска фильтр, чтобы связка не падала с ошибкой на следующем шаге.

Подробнее — в статье «Как найти подписчика из внешнего сервиса» (готовится).

---

## Пример и готовые связки

**Пример: подписчик с тегом «Оплатил» — в Google Таблицу**

1. Триггер: **BotMan → Добавление тега подписчику**.
2. Фильтр: название тега равно «Оплатил».
3. Действие: **Google Sheets → Добавить строку**, в колонки подставьте имя, телефон, email и нужные поля из триггера.

**Готовые связки**

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

| Связка | Направление | Страница в Albato | Инструкция BotMan |
| --- | --- | --- | --- |
| 1С (BETA) | Бот ↔ 1С | [BotMan + 1С](https://albato.ru/integration-botman-1c) | Готовится |
| МойСклад | Бот ↔ учёт | [BotMan + МойСклад](https://albato.ru/integration-botman-moysklad) | Готовится |
| Tilda | Сайт → бот | [Tilda + BotMan](https://albato.ru/integration-tilda-botman) | Готовится |
| CallKeeper | Сервис → бот | [CallKeeper + BotMan](https://albato.ru/integration-callkeeper-botman) | Готовится |
| YCLIENTS | Бот ↔ запись | [YCLIENTS + BotMan](https://albato.ru/integration-yclients-botman) | Готовится |

Все связки BotMan в каталоге Albato: [albato.ru/app-botman](https://albato.ru/app-botman).

## Полезно знать

- Одно подключение (один API-ключ) обслуживает любое число связок.
- Триггеры срабатывают только у запущенной связки. В режиме теста Albato временно подписывается на события, чтобы получить пример данных.
- Данные триггера доступны для подстановки во все последующие шаги связки.
- Если поставить связку на паузу, Albato отпишется от событий BotMan; при повторном запуске подписка создастся заново. События, произошедшие во время паузы, в связку не попадут.
- Если связка не работает, сначала проверьте историю запусков в Albato: там видно, на каком шаге и с какой ошибкой она остановилась.

## Частые проблемы

| Ошибка | Что значит и что делать |
| --- | --- |
| Вебхуки доступны на платном тарифе | Связка с триггером BotMan не запускается на тарифе Free. Перейдите на платный тариф BotMan |
| Не удалось проверить тариф для вебхуков, попробуйте позже | Временный сбой проверки тарифа. Запустите связку ещё раз через пару минут |
| Ключ не принимается / связки перестали работать | Ключ скопирован не полностью или был перевыпущен. Скопируйте актуальный ключ в разделе «Интеграции» и обновите подключение в Albato |
| Subscriber with provided id was not found | Подписчик с таким ID не найден. Передайте «ID подписчика» из триггера BotMan или из «Поиска подписчика», а не ID в соцсети |
| Поиск подписчика ничего не находит | Значение не совпадает с BotMan символ в символ — чаще всего формат телефона. Приведите значение к формату BotMan |
| Flow belongs to another channel than the subscriber | Сценарий из другого канала. Выберите сценарий того канала, из которого пришёл подписчик |
| Subscriber has blocked the bot / Chat with the subscriber no longer exists | Подписчик заблокировал бота или чат удалён — сообщение доставить нельзя |
| Message needs text or an attachment | В сообщении нет ни текста, ни вложения. Заполните хотя бы одно |
| Attachment could not be downloaded from the link | BotMan не смог скачать файл. Ссылка должна быть публичной (http или https) и вести на файл до 50 МБ |
| Attachment needs a link to the file / Attachment type … is not supported | Выберите тип вложения из списка и укажите ссылку на файл |
| Shift time requires a value and a unit… | Для отложенной отправки заполните и «Отложить на», и «Единицу времени» |
| Field … cannot be changed via public API | Это системное поле нельзя изменить через API. Доступные поля — в списке действия «Изменение системного поля подписчика» |

Не нашли ответ? Напишите в поддержку BotMan и приложите ссылку на связку или скриншот ошибки из истории запусков Albato. Вопросы по работе самого Albato — в [поддержку Albato](https://help.albato.ru).