Обліковий запис 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 потребують окремої реалізації та, за потреби, зовнішнього провайдера. Створення бота не додає цю логіку. Події коментарів у гілках також вмикаються окремим дозволом.
Поширені запитання
Бот створений, але не відповідає. Що перевірити?
Перевірте активність бота, доступність обробника й надішліть /help у тестовий чат. Якщо перевірка webhook проходить, а команди ні, перевірте вкладений формат message, доступ до чату та приватність групи.
Бот і віджет сайту — це те саме?
Ні. Віджет підключає відвідувача сайту до діалогу з оператором. Автоматичні відповіді потребують окремо налаштованої логіки; бот не стає оператором кожного віджета автоматично.
Чи можна використовувати свій сервер?
Так, адреса API має відповідати обраному серверу. Доступність модуля й чинні правила визначає адміністратор цього сервера.