What you need

A GoMsg account with access to Bots, a test chat and your own HTTPS webhook handler. The example below is for developers and uses Node.js with built-in fetch and the Express package.

1. Create the bot and keep its token

Open Business → Bots and click the plus button or Create bot. Creation only requires a name. Set the description, avatar, visibility, webhook and commands afterwards in the bot card.

The generated token controls your bot. Store it in the GOMSG_BOT_TOKEN environment variable on your application server. Keep it out of website HTML and public repositories. Regenerate it in the bot card if exposed.

2. Check the API for the selected server

Set GOMSG_API_URL to that server's API address, for example https://api.gomsg.pro for the public server. Your token and chat must belong to the same server. Example for bash/zsh:

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

The response contains the bot's details, including its id. Keep this ID to check incoming events. For a 401 response, check the token and whether the bot is active; a token from another server will not work.

3. Connect the webhook and a test chat

Set your handler's HTTPS URL in the bot card. It must be reachable from the GoMsg server; your computer's localhost address will not work for a remote server. Click Test webhook: this sends an event with type: "test".

Open a conversation with the bot, or add it to a group where you have permission. Send /help. Direct messages trigger events. In groups, privacy mode limits events to commands, mentions and replies to the bot; receiving all group messages is a separate setting.

This is a shortened message event. The message is nested under message, rather than at the JSON root. The example IDs are placeholders; use real UUIDs from your own event.

{
  "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. Reply with sendMessage

Take chat_id from a message in your test chat. Replace CHAT_UUID with that UUID. The content must not be empty:

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"}'

Use message_type: "text" for normal text. Tasks and other special cards are created through their dedicated functions, rather than by assigning an arbitrary Bot API message type.

5. Handle a command with Node.js

Install Express with npm install express and save the example as bot.cjs. Set five environment variables: the API address, token, GOMSG_BOT_ID, the test chat UUID in GOMSG_CHAT_ID and a random secret in GOMSG_WEBHOOK_SECRET. In GoMsg, use a webhook URL such as https://hooks.example.com/webhook/YOUR_SECRET.

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: "Hello! This is a reply to /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");

Run node bot.cjs and forward your domain's HTTPS requests to local port 3000 using a reverse proxy. The example only answers /help in one allowed chat, handles test events separately and does not reply to itself.

This is a starting handler, not a complete production service. Keep the secret URL private and redact it from logs. The X-GoMsg-Bot-Id header is not a request signature. Before production, protect incoming requests, deduplicate events by message.id and monitor errors; automatic delivery retries are not guaranteed.

Other methods and settings

The API supports editing with PATCH /api/bots/:token/messages/:message_id, appending text with POST /api/bots/:token/messages/:message_id/append, and deletion with DELETE /api/bots/:token/messages/:message_id. Operate on your bot's messages and check server responses. Commands listed in the bot card are hints; you implement their behavior.

AI, translation and CRM integration need separate application logic and, where applicable, an external provider. Creating a bot does not supply that logic. Thread comment events also require a separate permission.

Common questions

My bot does not reply. What should I check?

Check that it is active and that the handler URL is reachable, then send /help in the test chat. If the webhook test succeeds but commands do not, check the nested message format, chat access and group privacy settings.

Is a bot the same as a website widget?

No. A widget connects a visitor to an operator conversation. Automated answers need separately configured logic; a bot does not automatically become an operator for every widget.

Can I use my own server?

Yes. Set the API address to your chosen server. That server’s administrator controls module availability and applicable rules.