+7 (999) 881-15-11

«Арете — сервер мессенджеров, Max edition»

Создание первого бота

Свой бот выводят на связь через карточку в 1С, токен Max, приём событий и минимальный обработчик. Установка расширения и заполнение справочников — отдельно, в руководстве по установке. Готовый учебный сценарий — в подключении демобота.

Перед началом

Нужны установленное расширение, действующая лицензия и инициализация подсистемы (методы Max, справочники роутинга, эмодзи, регламент «Очистка журнала»). Роль — АСМ — Администратор подсистемы. С сервера 1С должен уходить HTTPS к API Max.

Для первого запуска берите polling: 1С сама спрашивает события у Max, публиковать HTTP-сервис не нужно. Webhook оставьте на потом, когда будет постоянный HTTPS-адрес.

Бот в Max

В кабинете разработчика Max создайте бота и скопируйте токен. Документация API: dev.max.ru/docs-api. Токен храните только в регистре «АСМ — Токены», в код обработчика его не вшивайте.

Карточка бота в 1С

Справочник АСМ — Боты. Новый элемент:

  1. Наименование — как будете отличать бота в списках.
  2. Мессенджер — Max.
  3. Способ получения событий — опрос (polling).
  4. Флаг «Используется» включён.

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

Токен и «Кто я»

  1. Из карточки бота откройте Токены, добавьте запись, вставьте токен, включите «Используется».
  2. Команда «Кто я» в карточке бота вызывает метод API и показывает JSON.

Если в ответе имя и идентификатор бота — связь с Max есть, до обработчика ещё не дошли. Ошибка на этом шаге почти всегда токен, сеть или то, что бот в 1С не «используется».

Получение событий

Опрос (polling)

1С периодически запрашивает обновления. Позиция опроса хранится в регистре Max-маркер.

  1. В карточке бота заполните Опросы (polling): длительность long polling, таймаут соединения, лимит событий за запрос, сервер API.
  2. Откройте обработку Регламентные задания подсистемы, создайте задание вида «Опрос» для этого бота и запустите его.

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

Webhook

Max сам шлёт HTTP POST на опубликованный сервис АСМ_Вебхук (корневой URL asm_webhook, шаблон /{Ключ}). Нужны публикация HTTP-сервиса на веб-сервере 1С, запись в регистре Вебхуки (адрес, секрет, ключ) и регистрация webhook на стороне Max. Для первого бота это лишний контур — вернётесь, когда polling уже отвечает в чат.

Первый обработчик

Логика бота живёт не в расширении АСМ, а в обработчике — общем модуле, внутренней или внешней обработке, либо в файле, лежащем в хранилище записи регистра АСМ — Обработчики. Для первого бота проще внешняя обработка: правите файл — поведение меняется без обновления конфигурации.

В регистре укажите бота, расположение, имя (или путь к .epf), включите «Используется». Для внутренней обработки отметьте, модуль объекта это или модуль менеджера. «Режим разработки» включает отладочные возможности на время отладки.

Обработчик отдаёт подсистеме четыре точки входа. Ниже — минимальный комплект: ответ на старт диалога.

Сведения об обработчике
Имя и версия для подсистемы. Шаблоны и состояния можно не заполнять, пока они не нужны. 
Функция СведенияОбОбработчике() Экспорт

	Сведения = АСМ_Служебный.СведенияОбОбработчике();
	Сведения.Наименование = "Первый бот";
	Сведения.Версия = "1.0";
	Сведения.Информация = "Ответ на старт диалога";
	Возврат Сведения;

КонецФункции
Инициализация
Вызывается при подключении обработчика к боту: создаёт шаблоны и состояния из сведений, если они есть. 
Функция ИнициализацияОбработчика(Бот) Экспорт

	Сведения = СведенияОбОбработчике();
	АСМ_Служебный.СоздатьШаблоныОбработчика(Сведения);
	АСМ_Служебный.СоздатьСостоянияОбработчика(Сведения, Бот);
	Возврат Истина;

КонецФункции
Сборка роутера
Один роут: старт в Max или текст /start. Результат кэшируется на сеанс. 
Функция СобратьРоутер(Бот) Экспорт

	Роутер = АСМ_Роутинг.ИнициализироватьРоутер(Бот);
	АСМ_Роутинг.ДобавитьРоут(
		"СтартБота",
		Роутер,
		"ТипСобытия = 'bot_started' ИЛИ Текст = '/start'");
	Возврат Роутер;

КонецФункции
Разбор события
Процедура ОбработатьСобытие(Бот, Событие, Вход) Экспорт

	Роутер = АСМ_НастройкиПовтИсп.СобратьРоутер(Бот);
	СтартБота("СтартБота", Роутер, Бот, Событие, Вход);

КонецПроцедуры
Ответ
Процедура СтартБота(Ключ, Роутер, Бот, Событие, Вход)

	Если АСМ_Роутинг.Нет(Ключ, Роутер, Событие, Вход) Тогда Возврат; КонецЕсли;

	Параметры = Новый Структура("text", "Добро пожаловать!");
	АСМ_М.ОтправитьСообщение(Бот, Параметры, Вход);

КонецПроцедуры

Подробнее про ключи, Нет() и кэш — в руководстве по роутингу. После правки СобратьРоутер сбросьте кэш повтотно используемых значений или откройте новый сеанс.

Проверка

  1. Напишите боту в Max /start или откройте диалог заново (событие bot_started).
  2. Должно прийти «Добро пожаловать!».
  3. В Журнале — входящее событие и исходящая отправка.
  4. В справочниках Чаты и Пользователи появятся записи.

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

Что дальше

Частые ошибки