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

Аккаунт GoMsg с доступом к разделу «Боты», тестовый чат и собственный обработчик HTTPS webhook. Пример ниже рассчитан на разработчика: используются Node.js со встроенным fetch и пакет Express.

1. Создайте бота и сохраните токен

Откройте «Бизнес» → «Боты» и нажмите плюс или «Создать бота». При создании достаточно указать имя. В карточке затем настраиваются описание, аватар, видимость, webhook и команды.

Токен генерируется автоматически и позволяет управлять ботом. Храните его в переменной окружения GOMSG_BOT_TOKEN на сервере своего приложения. Не помещайте токен в HTML сайта или публичный репозиторий; при утечке перевыпустите его в карточке бота.

2. Проверьте API нужного сервера

В GOMSG_API_URL укажите адрес API выбранного сервера, например https://api.gomsg.pro для публичного сервера. Токен и чат должны принадлежать одному серверу. Пример запроса для bash/zsh:

curl "$GOMSG_API_URL/api/bots/$GOMSG_BOT_TOKEN/me"

Ответ содержит данные бота, в том числе его id. Сохраните этот идентификатор для проверки событий. Если API возвращает 401, проверьте токен и активность бота; не подставляйте сюда токен другого сервера.

3. Подключите webhook и тестовый чат

В карточке бота укажите HTTPS URL своего обработчика. Он должен быть доступен серверу GoMsg: адрес localhost вашего компьютера для удалённого сервера не подходит. Нажмите «Проверить webhook»: проверочное событие имеет type: "test".

Откройте диалог с ботом или добавьте его в группу, где у вас есть нужные права. Отправьте /help. В личном диалоге бот получает сообщения; в группе при включённом режиме приватности — команды, упоминания и ответы на сообщения бота. Получение всех сообщений группы настраивается отдельно.

Ниже сокращённый пример реального события. Сообщение находится внутри message, а не в корне JSON. Идентификаторы в примере условные; используйте реальные UUID из своего события.

{
  "type": "message",
  "trigger": "command",
  "chat_type": "group",
  "chat_name": "Demo team",
  "message": {
    "id": "MESSAGE_UUID",
    "chat_id": "CHAT_UUID",
    "sender_id": "USER_UUID",
    "sender_username": "demo_user",
    "content": "/help",
    "message_type": "text"
  },
  "bot": {"id": "BOT_UUID", "name": "HelpBot"}
}

4. Отправьте ответ через sendMessage

Возьмите chat_id из сообщения своего тестового чата. Замените CHAT_UUID на его UUID. Содержимое сообщения должно быть непустым:

curl -X POST "$GOMSG_API_URL/api/bots/$GOMSG_BOT_TOKEN/sendMessage" \
  -H 'Content-Type: application/json' \
  --data '{"chat_id":"CHAT_UUID","content":"Hello!","message_type":"text"}'

Для обычного текста используйте message_type: "text". Задачи и другие специальные карточки создаются через предназначенные для них функции; это не произвольный формат Bot API.

5. Обработайте команду на Node.js

Установите Express командой npm install express. Сохраните пример в bot.cjs. Настройте пять переменных окружения: адрес API, токен, GOMSG_BOT_ID, UUID тестового чата в GOMSG_CHAT_ID и случайный секрет в GOMSG_WEBHOOK_SECRET. В GoMsg укажите URL вида https://hooks.example.com/webhook/СЕКРЕТ.

const express = require("express");
const app = express();
app.use(express.json({ limit: "128kb" }));

const api = process.env.GOMSG_API_URL?.replace(/\/+$/, "");
const token = process.env.GOMSG_BOT_TOKEN;
const botId = process.env.GOMSG_BOT_ID;
const chatId = process.env.GOMSG_CHAT_ID;
const secret = process.env.GOMSG_WEBHOOK_SECRET;
if (!api || !token || !botId || !chatId || !secret) {
  throw new Error("Missing GoMsg environment variables");
}

app.post("/webhook/:secret", async (req, res) => {
  if (req.params.secret !== secret) return res.sendStatus(403);
  const event = req.body;
  if (event?.type === "test") return res.sendStatus(200);
  const msg = event?.message;
  if (event?.type !== "message" || event.bot?.id !== botId ||
      msg?.chat_id !== chatId || msg?.sender_id === botId ||
      typeof msg?.content !== "string" || msg.content.trim() !== "/help") {
    return res.sendStatus(204);
  }
  try {
    const reply = await fetch(
      `${api}/api/bots/${encodeURIComponent(token)}/sendMessage`,
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          chat_id: chatId,
          content: "Здравствуйте! Это ответ на команду /help.",
          message_type: "text"
        }),
        signal: AbortSignal.timeout(5000)
      }
    );
    if (!reply.ok) throw new Error(`GoMsg HTTP ${reply.status}`);
    res.sendStatus(200);
  } catch (error) {
    console.error(error.message);
    res.sendStatus(502);
  }
});

app.listen(3000, "127.0.0.1");

Запустите node bot.cjs и направьте HTTPS запросы своего домена на локальный порт 3000 через reverse proxy. Пример отвечает только на /help в одном разрешённом чате, отдельно обрабатывает проверочное событие и не отвечает самому себе.

Это начальный обработчик, а не готовый сервис. Не публикуйте секретный URL и скрывайте его в журналах. Заголовок X-GoMsg-Bot-Id сам по себе не является подписью запроса. Перед рабочим запуском добавьте защиту входящих запросов, учёт повторных событий по message.id и мониторинг ошибок; автоматические повторы доставки не гарантированы.

Другие методы и настройки

API поддерживает редактирование PATCH /api/bots/:token/messages/:message_id, добавление текста POST /api/bots/:token/messages/:message_id/append и удаление DELETE /api/bots/:token/messages/:message_id. Работайте со своими сообщениями и проверяйте ответ сервера. Список команд в карточке — подсказки; логику каждой команды вы пишете самостоятельно.

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

Частые вопросы

Бот создан, но не отвечает. Что проверить?

Проверьте активность бота, URL и доступность обработчика, затем отправьте /help в тестовый чат. Если проверка webhook проходит, а команды нет, проверьте формат вложенного message, доступ к чату и настройки приватности группы.

Бот и виджет сайта — это одно и то же?

Нет. Виджет подключает посетителя сайта к переписке с оператором. Для автоматических ответов нужна отдельно настроенная логика; бот не становится оператором каждого виджета автоматически.

Можно ли использовать свой сервер?

Да, адрес API в приложении должен соответствовать выбранному серверу. Доступность модуля и действующие правила определяет администратор этого сервера.