Аккаунт 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 в приложении должен соответствовать выбранному серверу. Доступность модуля и действующие правила определяет администратор этого сервера.