Saltar a contenido

¿Qué son los webhooks?

Un webhook permite que tu bot en VisualMaker reciba información desde otros servicios o sistemas. Piensa en los webhooks como "mensajeros" que traen datos a tu bot. Mientras que las peticiones HTTP permiten a tu bot pedir datos, los webhooks permiten recibirlos sin pedirlos.

Requisito previo

¿Cómo funcionan los webhooks?

Cuando un servicio externo quiere enviar información a tu bot, usa un webhook. Esto se hace a través de una solicitud HTTP al servidor de VisualMaker, que incluye ciertos datos y parámetros para que el bot pueda procesarlos.

  • Los webhook envían datos externos a tu bot.
  • La forma de recibir estos datos es a través de los botones y comandos de tu bot, usando la acción Recibir parámetros.
  • El servidor que recibe los webhooks es: https://visualmaker.net/webhook
  • Se pueden enviar peticiones de tipo GET o POST, usando formatos como JSON, params o data.

Llave webhook

Para usar los webhooks, necesitas tu llave webhook, que es única para cada bot.

  1. Ve a VisualMaker.
  2. Dirígete a 🖥 Bots → 📜 Mis bots.
  3. Selecciona el bot deseado y elige 🌐 Llave webhook.
  4. Haz clic en 👁 Mostrar llave 👁 para verla.

IMPORTANTE

Mantén tu llave webhook segura. Si alguien la obtiene, podría controlar tu bot.

Pasos para usar webhooks en tu bot

Para recibir un webhook en tu bot:

  1. Crea un comando o botón

    Crea y configura el botón o comando que será ejecutado al recibir el webhook. Este será el que reciba los datos enviados desde el servicio externo.

  2. Agrega la acción "Recibir parámetros"

    Ve al botón o comando que acabas de crear (el que va a recibir los datos externos) y agrega una acción de tipo Recibir parámetros, preferiblemente como la primera acción de todas.

  3. Configura el webhook en el servicio externo

    Indícale al servicio externo que enviará el webhook lo que debe enviar a tu bot via webhook. Incluye los datos a enviar de la siguiente forma:

    https://visualmaker.net/webhook?key=YOUR_WEBHOOK_KEY&run=/TU_COMANDO_O_BOTON&user_id=ID_DEL_USUARIO&param1=UN_PARAMETRO&param2=OTRO_PARAMETRO

    Solo debes reemplazar los datos que están en mayúsculas por tus propios datos.

  4. Recibe los datos en tu bot

    Recibe los datos en tu bot obteniéndolos mediante la acción de tipo Recibir parámetros que agregaste en el paso 2, a través de su ID, de la siguiente forma:

    {#IDAccionRecibirParametros.param1#}: Para recibir el parametro 1.
{#IDAccionRecibirParametros.param2#}: Para recibir el parametro 2.

    Repite este proceso para parámetros adicionales según sea necesario.

  5. Usa los datos recibidos en tu bot

    Utiliza los datos recibidos del webhook donde los necesites dentro de tu bot, puede ser para procesarlos, enviar mensajes o usarlos en acciones posteriores.

Parámetros para los webhooks

  • key: Tu llave webhook.
  • run: El botón o comando a ejecutar (por ejemplo, Balance o /mi_comando).
  • user_id: El ID de Telegram del usuario al cual se le ejecutará el botón o comando.

  • param(num): (opcional) Datos adicionales que el webhook enviará a tu bot, como nombres, montos o tipos de moneda.

    Más información

    • Reemplaza (num) por la posición del parámetro, empezando por 1.
    • Recíbelos con la acción Recibir parámetros, dentro del botón o comando establecido usando el parámetro run.
    • Si los parámetros son enviados como JSON, conservarán su tipo de dato correspondiente, en cambio, si son enviados mediante params o data, serán enviados en formato de texto (string), por lo que deberás convertirlos a su tipo de dato usando la función que corresponda.

Ejemplo práctico: Integrar un procesador de pagos externo

Imagina que quieres configurar tu bot para recibir notificaciones de un procesador de pagos externo cada vez que alguien realiza un depósito. Estos son los pasos:

Paso 1: Crea el comando

  1. Ve a tu bot y selecciona 🛠 Editar.
  2. Crea un nuevo comando pulsando en ✳️ Nuevo botón | comando.
  3. Nómbralo /pago_recibido.
  4. Hazlo invisible para los usuarios:
    • Regresa a las opciones del comando y pulsa Ocultar 👁.
    • Esto asegura que solo el webhook externo pueda ejecutarlo.

Paso 2: Agrega las acciones necesarias

  1. Ve al comando /pago_recibido y entra en su menú de acciones pulsando en Acciones 🌟.

  2. Añade estas tres acciones, una por una:

    1. Recibir parámetros del webhook

    2. Actualizar el balance del usuario

    • Agrega una acción de tipo Cambiar variable.
    • Entra a configurarla pulsando en Configurar 🛠:
      • Pulsa 💠 Seleccionar variable 💠 y escribe balance.
      • Escoge la opción 🔺 Incrementar 🔺.
      • Usa el ID que copiaste antes para definir la cantidad que se incrementará. Agrega .param1 al final, así: #ABC12.param1#
    • Activa la acción pulsando ✅ Activar.

    3. Notificar al usuario

    • Agrega una acción de tipo Enviar mensaje.

    • Entra a configurarla pulsando en Configurar 🛠:

      • Escribe un mensaje para el usuario, por ejemplo:

        Has recibido {#ABC12.param1#} {#ABC12.param2#}.

        Nota: Reemplaza ABC12 por el ID de la acción de Recibir parámetros.

    • Activa la acción (✅ Activar).

Paso 3: Configura el servicio de pagos

En el procesador de pagos externo, configura el webhook con la siguiente URL:

https://visualmaker.net/webhook?key=TU_LLAVE_WEBHOOK&run=/pago_recibido&user_id=id_del_usuario&param1=cantidad_depositada&param2=moneda_usada

Explicación de los parámetros:

  • key: Tu llave webhook.
  • run: Indica qué comando ejecutar al recibir el webhook (/pago_recibido).
  • user_id: El ID del usuario que realizó el pago.
  • param1: La cantidad depositada.
  • param2: La moneda usada (por ejemplo, USDT, TON, etc.).

Resultado esperado

Cada vez que alguien realice un pago:

  1. El procesador de pagos enviará los datos a tu bot a través del webhook.
  2. El bot ejecutará el comando /pago_recibido.
  3. Los datos enviados serán capturados por la acción Recibir parámetros.
  4. El balance del usuario se actualizará automáticamente con la cantidad recibida.
  5. El usuario recibirá un mensaje como este:
    Has recibido 3 TON.

Respuesta del servidor

Cuando VisualMaker recibe un webhook, responde con:

  • status: 200 si todo está bien. Otro número indica un error.

  • message: "ok" si fue exitoso, o un mensaje describiendo el error.

Ejemplo de respuesta: {"status": 200, "message": "ok"}

Consejos útiles

  • Los webhooks no pulsan botones o comandos: Ejecutan directamente las acciones que contengan. Si necesitas "pulsar" un botón o comando, combina el webhook con la acción Ejecutar botón.
  • Los webhooks ejecutan botones y comandos ocultos: Los webhook ejecutarán botones y comandos incluso si están ocultos.

Los webhooks son perfectos para integraciones avanzadas, como sistemas de pago, servicios de notificaciones, o cualquier situación donde quieras que un sistema externo interactúe con tu bot de forma automática.