Первый бот
Здесь собран путь от создания бота до первого разговора: ваш сервис пишет в чат, сотрудник отвечает, а бот получает ответ и пишет в тред. Примеры кода написаны на TypeScript и Python, подробности каждого шага — по ссылкам.
Как это работает:
- Сервис отправляет сообщение методом POSTНовое сообщение с токеном бота
- Сотрудник отвечает, и Пачка присылает событие на адрес вашего обработчика: это исходящий вебхук
- Обработчик проверяет подпись запроса и отвечает в тред тем же методом
Для приёма событий нужен адрес, доступный из интернета. Пока обработчик работает на вашей машине, события получают через туннель или потоком, подробнее в разделе Разработка на своей машине.
Подготовьте бота
Создайте бота
В веб-версии или десктопном приложении Пачки откройте Интеграции > Боты и нажмите Создать бота. Задайте название, а ник можно оставить пустым: он соберётся из названия. Кнопка есть у тех, кому разрешено создавать интеграции, подробнее в разделе Кто может создавать токены. Другие способы и настройки — в разделе Создание бота.
Выпустите токен
На вкладке API в карточке бота нажмите Создать токен и выберите права из строки «Бот отвечает на сообщения и команды» в разделе Наборы прав под типовые задачи. Коду на этой странице из набора нужны права messages:create, threads:create и profile:read. Значение токена показывается один раз: скопируйте его до закрытия окна. Подробнее — в разделе Токены бота.
Добавьте бота в беседу
Создайте беседу для проверки и добавьте в неё бота в окне Добавление участников на вкладке Боты. События о сообщениях бот получает из чатов, где состоит, подробнее в разделе Доступы к чатам и сообщениям.
Узнайте идентификатор беседы
Откройте беседу в веб-приложении: идентификатор — число в адресе после /chats/, например 12345 в https://app.pachca.com/chats/12345. Другие способы — в разделе Где взять идентификаторы.
Отправьте сообщение
Метод POSTНовое сообщение принимает идентификатор чата в entity_id и текст в content. Подставьте идентификатор своей беседы вместо 12345, а токен бота передайте в переменной окружения PACHCA_BOT_TOKEN.
В ответе придёт объект сообщения в поле data. Сохраните его id: по нему вы узнаете, что сотрудник ответил именно на это сообщение, подробнее в разделе Ответы на сообщения сервиса. Если запрос вернул ошибку, код и причина разобраны в разделах Ошибки авторизации и Ошибки.
Включите исходящий вебхук
Укажите адрес обработчика
На вкладке Исходящий вебхук в карточке бота нажмите Включить, в поле Webhook URL укажите адрес обработчика, доступный из интернета, например https://bot.example.com/webhook, и подтвердите кнопкой Включить. Для разработки подойдёт адрес туннеля, подробнее в разделе Разработка на своей машине.
Выберите события
Отметьте Новые сообщения и выберите режим Любые сообщения: в режиме Начинающиеся с команд бот получает только сообщения, которые начинаются с его команд, а ответ сотрудника обычно без команды. Включите Игнорировать свои сообщения, чтобы бот не получал события о собственных ответах. Подробнее — в разделе Сообщения.
Скопируйте Signing secret
Секрет появится на вкладке после включения вебхука. Обработчик проверяет им подпись каждого запроса, передайте его в переменной окружения PACHCA_SIGNING_SECRET.
Вкладка «Исходящий вебхук» после включения: этой странице нужны «Новые сообщения», а «Нажатие кнопок» пригодится для кнопок и форм
Напишите обработчик
Обработчик принимает событие, проверяет подпись и время отправки и сразу отвечает 200: Пачка ждёт ответа 5 секунд, все сроки — в разделе Сроки ответа. Почему подпись считают от сырого тела запроса и как проверить IP-адрес отправителя, описано в разделе Безопасность.
После ответа обработчик пишет сотруднику туда, где тот написал:
- сообщение из беседы или канала — тредом под ним: метод POSTНовый тред открывает тред или возвращает уже открытый, а POSTНовое сообщение с
entity_type: "thread"пишет в него - сообщение из треда или личных сообщений — туда же, с теми же
entity_typeиentity_id
Подробнее — в разделе Куда отвечать. Свои сообщения обработчик пропускает по id бота из метода GETСвой профиль, так что бот не отвечает сам себе, даже если Игнорировать свои сообщения выключено.
Пример отвечает на каждое новое сообщение, поэтому проверяйте его в отдельной беседе. Когда отвечать в рабочих чатах, описано в разделе Когда отвечать.
TypeScript
Пример работает на Node.js 18 или новее и принимает события на порту 3000 по пути /webhook.
Python
Пример принимает события на порту 3000 по пути /webhook. Сообщение он отправляет в фоне через threading.Thread, чтобы ответить Пачке сразу.
Проверка
Запустите обработчик и ответьте в треде под сообщением, которое бот отправил в разделе Отправьте сообщение, или напишите в беседе: бот ответит в тред. Если ответа нет:
- Обработчик не получает запросов — проверьте, что адрес в Webhook URL заканчивается на
/webhook, бот состоит в беседе, отмечено Новые сообщения и выбран режим Любые сообщения - Обработчик отвечает
401— Signing secret не задан в переменной окружения или отличается от секрета на вкладке, или часы сервера расходятся с точным временем больше чем на минуту - Запрос к API отвечает
403с кодомinsufficient_scope— токену не хватает права из раздела Подготовьте бота, его добавляют в меню токена
Разработка на своей машине
Пачка отправляет события на публичный адрес http или https, подробнее в разделе Общие настройки. Пока обработчик работает на вашей машине, есть два способа:
- Туннель — ngrok, Cloudflare Tunnel или другой туннель выдаёт порту
3000временный публичный адрес: укажите его с путём/webhookв Webhook URL, и обработчик из примера заработает без изменений - Поток событий — бот сам подключается к Пачке и получает события по открытому соединению, а входящие запросы и проверка подписи ему не нужны
Как настроить оба способа и почему для разработки удобен отдельный бот, описано в разделе Разработка и запуск обработчика.
Для потока включите на вкладке Исходящий вебхук настройку Сохранять историю событий и добавьте токену права webhooks:events:read и webhooks:events:delete. События и режим выберите, как в разделе Включите исходящий вебхук. Эти настройки появляются на вкладке после включения вебхука, а боту без адреса их задают через API, подробнее в разделах Поллинг и Через API. Если адрес указан, но Пачка не может к нему подключиться, событие придёт в поток ещё раз при каждой повторной попытке доставки, подробнее в разделе История при работающем вебхуке.
Код ниже получает ссылку методом GETПоток событий, подключается к ней и передаёт каждое событие той же функции обработчика. Ссылка открывается без токена, поэтому храните её как секрет. Переменная PACHCA_SIGNING_SECRET потоку не нужна.
В bot.ts замените строку app.listen(3000) этим кодом и установите пакет командой npm install eventsource:
В bot.py замените блок if __name__ == "__main__": этим кодом и установите пакет командой pip install httpx-sse:
Этот код работает, пока действует ссылка, её срок приходит в поле expires_at. События, которые пришли до подключения, он не забирает. Как дочитывать историю и менять ссылку без потери событий, показано в разделе Пример подключения.
Что дальше
- Ответ на сообщение сервиса — как связать ответ сотрудника с заявкой или уведомлением, которое отправил бот, описано в разделе Ответы на сообщения сервиса
- Упоминания и команды — бот в рабочем чате отвечает, когда к нему обращаются, подробнее в разделах Когда отвечать и Команды
- Контекст разговора — историю треда и сообщение, к которому он открыт, бот читает методами из раздела Контекст разговора
- Повторы событий — одно событие изредка приходит дважды, ключ для отсева описан в разделе Идемпотентная обработка
- Кнопки и формы — бот с командой, кнопками и формой целиком собран в разделе Интерактивный бот
- Запуск в работу — что проверить перед тем, как указать адрес рабочего сервера, перечислено в разделе Чек-лист перед запуском в работу
- SDK — типизированный клиент API и типы событий есть в SDK для TypeScript, Python и других языков