Qué necesitas

Una cuenta de GoMsg con acceso a Bots, un chat de prueba y un receptor HTTPS de webhook propio. El ejemplo está dirigido a desarrolladores y utiliza Node.js con fetch integrado y el paquete Express.

1. Crea el bot y guarda su token

Abre Negocios → Bots y pulsa el botón más o Crear bot. Para crearlo solo hace falta un nombre. La descripción, el avatar, la visibilidad, el webhook y los comandos se configuran después en su ficha.

El token generado permite controlar el bot. Guárdalo en la variable de entorno GOMSG_BOT_TOKEN del servidor de tu aplicación. No lo incluyas en el HTML del sitio ni en repositorios públicos. Si se filtra, regénéralo desde la ficha.

2. Comprueba la API del servidor elegido

Configura GOMSG_API_URL con la dirección de su API; por ejemplo, https://api.gomsg.pro para el servidor público. El token y el chat deben pertenecer al mismo servidor. Ejemplo para bash/zsh:

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

La respuesta contiene los datos del bot, incluido su id. Guarda este identificador para comprobar los eventos. Ante una respuesta 401, revisa el token y que el bot esté activo; un token de otro servidor no sirve.

3. Conecta el webhook y un chat de prueba

Indica la URL HTTPS de tu receptor en la ficha del bot. Debe ser accesible desde el servidor de GoMsg; localhost en tu equipo no es una dirección válida para un servidor remoto. Pulsa Probar webhook: el evento de prueba tiene type: "test".

Abre una conversación con el bot o añádelo a un grupo donde tengas permisos. Envía /help. Los mensajes directos generan eventos. En grupos, el modo de privacidad limita los eventos a comandos, menciones y respuestas al bot; recibir todos los mensajes se configura por separado.

Este es un evento de mensaje abreviado. El mensaje está dentro de message, no en la raíz del JSON. Los identificadores son ilustrativos: utiliza UUID reales de tu evento.

{
  "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. Responde con sendMessage

Obtén chat_id de un mensaje de tu chat de prueba. Sustituye CHAT_UUID por ese UUID. El contenido no puede estar vacío:

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

Usa message_type: "text" para texto normal. Las tareas y otras tarjetas especiales se crean mediante sus funciones específicas, no asignando un tipo arbitrario en la Bot API.

5. Procesa un comando con Node.js

Instala Express con npm install express y guarda el ejemplo en bot.cjs. Configura cinco variables de entorno: dirección de la API, token, GOMSG_BOT_ID, UUID del chat de prueba en GOMSG_CHAT_ID y un secreto aleatorio en GOMSG_WEBHOOK_SECRET. En GoMsg, usa una URL como https://hooks.example.com/webhook/TU_SECRETO.

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: "¡Hola! Esta es una respuesta a /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");

Ejecuta node bot.cjs y dirige las peticiones HTTPS de tu dominio al puerto local 3000 mediante un proxy inverso. El ejemplo solo responde a /help en un chat permitido, trata los eventos de prueba por separado y no se responde a sí mismo.

Es un receptor inicial, no un servicio completo para producción. Mantén la URL secreta fuera de publicaciones y ocúltala en los registros. La cabecera X-GoMsg-Bot-Id no es una firma de la petición. Antes de producción, protege las peticiones entrantes, elimina duplicados por message.id y supervisa errores; los reintentos automáticos de entrega no están garantizados.

Otros métodos y ajustes

La API permite editar con PATCH /api/bots/:token/messages/:message_id, añadir texto con POST /api/bots/:token/messages/:message_id/append y borrar con DELETE /api/bots/:token/messages/:message_id. Trabaja con los mensajes de tu bot y comprueba las respuestas del servidor. La lista de comandos de la ficha son sugerencias; tú implementas su comportamiento.

La IA, la traducción y las integraciones CRM necesitan lógica propia y, cuando corresponda, un proveedor externo. Crear el bot no incluye esa lógica. Los eventos de comentarios en hilos también requieren un permiso específico.

Preguntas frecuentes

Mi bot no responde. ¿Qué compruebo?

Comprueba que esté activo y que el receptor sea accesible, y envía /help en el chat de prueba. Si la prueba del webhook funciona pero los comandos no, revisa el formato message anidado, el acceso al chat y la privacidad del grupo.

¿Un bot es lo mismo que un widget web?

No. El widget conecta a un visitante con una conversación de operador. Las respuestas automáticas necesitan una lógica configurada por separado; el bot no se convierte automáticamente en operador de todos los widgets.

¿Puedo usar mi propio servidor?

Sí. Configura la dirección de la API del servidor elegido. Su administrador determina los módulos disponibles y las reglas aplicables.