chazari-x/hmtpk_zammad_vk_bot

Zammad VK Bot

Zammad VK Bot - это интеграция между платформой обслуживания клиентов Zammad и социальной сетью VK (ВКонтакте), написанная на языке программирования Golang. Этот бот предназначен для упрощения взаимодействия пользователей с системой Zammad через VK, обеспечивая более удобный способ отправки запросов и получения поддержки.

Использование BoltDB

BoltDB используется в проекте для хранения связи между пользователями VK и их идентификаторами в системе Zammad. Более конкретно, BoltDB хранит пары данных, состоящие из идентификаторов пользователей VK и их соответствующих идентификаторов в системе Zammad.

Использование BoltDB для этой цели обеспечивает быстрый доступ к данным и надежное сохранение информации о связи между пользователями двух платформ. Это позволяет боту эффективно управлять коммуникацией между пользователями VK и системой Zammad.

Использование volumes

Для хранения данных внутри контейнера используется volumes. Конкретно, используется привязка volumes, чтобы сохранять данные базы данных BoltDB между запусками контейнера. В данном случае, папка ./db_data на хост-системе привязывается к папке /app/db_data внутри контейнера, что позволяет сохранять данные даже при перезапуске контейнера.

Права на папку ./db_data на хост-системе должны быть установлены таким образом, чтобы контейнер имел права на запись в эту папку. Обычно рекомендуется установить права на чтение, запись и выполнение для владельца папки, что можно сделать следующим образом:

chmod 777 ./db_data

Это позволит контейнеру свободно сохранять и обновлять данные в папке ./db_data на хост-системе.

Функциональные возможности

Бот Zammad VK имеет следующие функциональности:

Создание тикета

Бот может создать тикет в системе Zammad с добавленными заголовком, описанием, группой и ответственным.

Это позволяет пользователям отправлять запросы на поддержку через VK, а бот автоматически создает соответствующий тикет для дальнейшей обработки.

Уведомления об изменениях

С помощью триггеров и вебхуков Zammad VK Bot может отправлять уведомления об изменениях в тикетах.

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

Изменение тикета и ответ на тикет

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

Это обеспечивает удобный способ управления тикетами и взаимодействия с системой поддержки через платформу VK.

Задачи маршрутизации

Бот использует два основных маршрута для обработки запросов:

• /zammad/webhook: Этот маршрут используется для обработки вебхуков от Zammad. Когда происходит событие, например, изменение тикета, Zammad отправляет уведомление о событии на этот маршрут, и бот обрабатывает это уведомление соответствующим образом.

• /zammad/auth: Этот маршрут используется для аутентификации пользователей через OAuth с Zammad. Когда пользователь запрашивает аутентификацию через Zammad, бот направляет его на этот маршрут для прохождения процесса аутентификации.

Настройка Zammad

Авторизация пользователей в боте

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

Настройка клиента OAuth в Zammad (#system/api)

Войдите в административный интерфейс Zammad и перейдите в раздел Настройки -> Программный интерфейс приложения (API). Добавьте новое приложение (OAuth Authentication), предоставив необходимую информацию, такую как имя, URL перенаправления (env BOT_ZAMMAD_OAUTH_REDIRECT_URL) и т.д.

Замените в файле docker-compose.yml BOT_ZAMMAD_OAUTH_CLIENT_ID на AppID, а BOT_ZAMMAD_OAUTH_CLIENT_SECRET на Secret.

AppID и Secret можно получить нажав на Вид добавленного приложения (OAuth Authentication).

Zammad пользователь для VK Bot

Для корректной работы бота необходим специальный пользователь в системе Zammad с правами администратора.

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

Это гарантирует, что бот сможет эффективно создавать и обрабатывать тикеты без каких-либо ограничений по доступу к необходимым данным в системе Zammad.

Доступ по ключу к API Zammad /#profile/token_access

Создайте личный ключ доступа для приложения с указанными правами доступа:

• admin.api,
• admin.channel_chat,
• admin.channel_sms,
• admin.group,
• admin.object,
• admin.user,
• admin.webhook,
• chat.agent,
• ticket.agent

Веб-перехватчик (Webhook) /#manage/webhook

Вы можете использовать веб-перехватчики (webhooks) в Zammad для отправки данных о заявках, статьях и вложениях при каждом срабатывании триггера. Просто создайте и настройте веб-перехватчик (webhooks) с конечной точкой (endpoint) HTTP(S) и соответствующими параметрами безопасности, а затем настройте триггер для его выполнения.

Конечная точка (endpoint)

Укажите конечную точку (endpoint). Например:

https://example.ru:8181/zammad/webhook

Ключ подписи hmac sha1

Укажите your_webhook_secret_key, который указан в конфигурации docker-compose.yml.

Проверка уровня защищенных сокетов (ssl)

Включите проверку уровня защищенных сокетов (ssl), если конечная точка расположена на https, или выключите, если конечная точка расположена на http.

Триггеры /#manage/trigger

Создайте триггеры:

[
    {
        "Имя": "botChangeGroup",
        "Активировано": "Действие",
        "Выполнение действия": "Selective (default)",
        "Условия отбора объектов": {
            "Заявка.Группа": "Изменился"
        },
        "Применить изменения к объектам": {
            "Веб-перехватчик (Webhook)": "установленный webhook"
        }
    },
    {
        "Имя": "botChangeOwner",
        "Активировано": "Действие",
        "Выполнение действия": "Selective (default)",
        "Условия отбора объектов": {
            "Заявка.Владелец": "Изменился"
        },
        "Применить изменения к объектам": {
            "Веб-перехватчик (Webhook)": "установленный webhook"
        }
    },
    {
        "Имя": "botChangePriority",
        "Активировано": "Действие",
        "Выполнение действия": "Selective (default)",
        "Условия отбора объектов": {
            "Заявка.Приоритет": "Изменился"
        },
        "Применить изменения к объектам": {
            "Веб-перехватчик (Webhook)": "установленный webhook"
        }
    },
    {
        "Имя": "botChangeState",
        "Активировано": "Действие",
        "Выполнение действия": "Selective (default)",
        "Условия отбора объектов": {
            "Заявка.Состояние": "Изменился"
        },
        "Применить изменения к объектам": {
            "Веб-перехватчик (Webhook)": "установленный webhook"
        }
    },
    {
        "Имя": "botChangeTitle",
        "Активировано": "Действие",
        "Выполнение действия": "Selective (default)",
        "Условия отбора объектов": {
            "Заявка.Заголовок": "Изменился"
        },
        "Применить изменения к объектам": {
            "Веб-перехватчик (Webhook)": "установленный webhook"
        }
    },
    {
        "Имя": "botNewMessage",
        "Активировано": "Действие",
        "Выполнение действия": "Selective (default)",
        "Условия отбора объектов": {
            "Заявка.Действие": "is Обновление",
            "Статья.Отправитель": "is Агент"
        },
        "Применить изменения к объектам": {
            "Веб-перехватчик (Webhook)": "установленный webhook"
        }
    },
    {
        "Имя": "botNewTicket",
        "Активировано": "Действие",
        "Выполнение действия": "Selective (default)",
        "Условия отбора объектов": {
            "Статья.Действие": "is Создано",
            "Заявка.Действие": "не Обновлен"
        },
        "Применить изменения к объектам": {
            "Веб-перехватчик (Webhook)": "установленный webhook"
        }
    }
]

Запуск через Docker Compose

Для запуска Zammad VK Bot вы можете использовать Docker Compose. Ниже приведен пример файла docker-compose.yml, который вы можете использовать:

version: '3'
services:
  vk-bot:
    container_name: vk-bot
    image: chazari/zammad-vk-bot:latest
    environment:
      BOT_LOG_LEVEL: trace # уровень логирования
      BOT_VK_TOKEN: VK_TOKEN # токен для бота ВК
      BOT_VK_API_HREF: https://api.vk.com
      BOT_VK_CHAT_HREF: https://vk.com/im?sel=-0000 # ссылка на чат с ботом
      BOT_WEBHOOK_SECRET_KEY: WEBHOOK_SECRET_KEY # секретный ключ, установленный для webhook'а
      BOT_WEBHOOK_PORT: :8181 # порт, на котором запускается webhook и OAuth
      BOT_ZAMMAD_TOKEN: ZAMMAD_TOKEN # токен для системы Zammad
      BOT_ZAMMAD_HREF: https://zammad.ru/ # адрес Zammad
      BOT_ZAMMAD_OAUTH_CLIENT_ID: ZAMMAD_OAUTH_CLIENT_ID # AppID приложения (OAuth Authentication)
      BOT_ZAMMAD_OAUTH_CLIENT_SECRET: ZAMMAD_OAUTH_CLIENT_SECRET # Secret приложения (OAuth Authentication)
      BOT_ZAMMAD_OAUTH_REDIRECT_URL: https://example.ru:8181/zammad/auth # URL-АДРЕС ОБРАТНОГО ВЫЗОВА (CALLBACK URL) приложения (OAuth Authentication)
      BOT_ZAMMAD_OAUTH_AUTH_URL: https://zammad.ru/oauth/authorize # URL-адрес OAuth для запроса подтверждения выдачи прав
      BOT_ZAMMAD_OAUTH_TOKEN_URL: https://zammad.ru/oauth/token # URL-адрес OAuth для получения ключа доступа
    volumes:
      - ./db_data:/app/db_data
    restart: on-failure
    ports:
      - "8181:8181" # порт, на котором запускается webhook и OAuth
    command: ["/app/main", "vk-bot"]

После создания файла docker-compose.yml и замены параметров на свои, вы можете запустить Zammad VK Bot с помощью команды:

docker-compose up -d

Взаимодействие с ботом

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

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

Пример создания тикета

Для создания тикета достаточно просто написать сообщение с описанием вашей проблемы. Например:

Привет, не могу войти в систему. Помогите, пожалуйста!

Ограничения

Бот обязательно требует аутентификацию OAuth для взаимодействия с Zammad. Без неё бот не будет работать.

Необходима стабильная сетевая связь для взаимодействия с Zammad.

Для использования аутентификации OAuth с Zammad необходимо наличие HTTPS. Это означает, что если вы планируете использовать функциональности, требующие аутентификации OAuth с Zammad, ваше приложение должно быть развернуто на сервере с SSL-сертификатом.

Лицензия

Этот проект лицензирован под MIT License. См. файл LICENSE для получения дополнительной информации.