Интеграции — Каналы, CRM, Вебхуки

Источник: doc.nextbot.ru/functional/integrations

Обзор

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

Каналы связи (мессенджеры)

CRM-интеграции

Google Calendar

Возможности

• Создание событий
• Удаление событий
• Проверка занятости слотов
• Использование текущей даты для контекста

Подключение

1. Перейдите в Интеграции → Google Calendar.
2. Нажмите «Подключить» и выберите Google-аккаунт.
3. Предоставьте права доступа ("Выбрать всё").

Настройки

• Передача текущей даты: Рекомендуется включить, чтобы агент понимал "сегодня", "завтра" и корректно работал с датами.
• Выбор календарей: Отметьте календари, с которыми будет работать бот (чтение/запись).

Bitrix24

Возможности интеграции

• Автоматизация обработки: Централизованный сбор сообщений из всех каналов в Открытые линии.
• Управление лидами: Авто-создание лидов и сделок, заполнение полей.
• Режим "Второго пилота": Агент подсказывает ответы сотрудникам, но не отправляет их сам.
• Скрытый контекст: Передача данных из карточки CRM агенту (статус, сумма, номер договора) для персонализации.

Сценарий использования

1. Квалификация: Агент задает вопросы, выявляет потребность.
2. Сбор данных: Имя, телефон, детали заказа.
3. Действие в CRM: Создание лида, смена стадии сделки.
4. Передача: Если нужно, подключение оператора.

Особенности

• Отключение: Если подписка Premium заканчивается, интеграцию нужно отключить, иначе будут ошибки при отправке сообщений.
• Второстепенные агенты: Поддержка мульти-агентных сценариев.
• Отправка файлов: Если файл не поддерживается NextBot, он отправляется ссылкой.

Вебхуки (Webhooks)

Что такое вебхуки

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

Два способа подключения

1. Вебхук по правилам NextBot (без адаптера)

Используется, когда внешний сервис может отправлять данные в предопределённом JSON-формате.

URL эндпоинта:

https://app.nextbot.ru/api/webhooks/v1/{agent_hash}/{url_token}

Обязательные поля JSON:

Типы сообщений (message_type):

Пример запроса:

{
  "dialog_id": 10177062,
  "text": "Оплата получена",
  "message_type": "notification"
}

Ответ при успехе:

200 OK "Webhook received and queued for processing"

Отладка: Добавьте ?debug=true к URL для получения подробных логов.

2. Вебхук с обработкой через адаптер

Используется, когда внешний сервис отправляет данные в произвольном формате — нужен Python-скрипт для преобразования.

Схема работы:

Внешний сервис → POST-запрос (произвольный JSON)
    → Адаптер (Python) 
    → Формат NextBot 
    → Обработка в диалоге

Доступные данные в адаптере:

Что должен вернуть адаптер (result):

Пример адаптера: обработка платёжного вебхука:

request = args.get("request", {})

metadata = request.get("metadata", {})
dialog_id = metadata.get("dialog_id")
if not dialog_id:
    raise ValueError("dialog_id not found in metadata")

amount = request.get("amount", {})
amount_value = amount.get("value", "0")
currency = amount.get("currency", "RUB")

card_info = request.get("payment_method", {}).get("card", {})
last4 = card_info.get("last4", "****")

order_id = metadata.get("order_id", "—")

text = f"Оплата получена: {amount_value} {currency} (карта *{last4}). Заказ: {order_id}"

result = {
    "dialog_id": int(dialog_id),
    "text": text,
    "message_type": "output"
}

Возможности адаптера:

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

Прочие интеграции