Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.nippy.la/llms.txt

Use this file to discover all available pages before exploring further.

​
Ejemplos de lo que puedes preguntarle a tu agente

  • “Crea una ruleta de bienvenida: 70% seguir participando, 20% descuento del 10%, 10% unos audífonos”
  • “¿Qué ruletas tengo activas ahorita?”
  • “Agrega un premio físico: 50 mochilas Nippy para usar en ruletas”
  • “Muéstrame la configuración completa de la ruleta de mayo”
  • “¿Qué items de premio tengo disponibles con stock?”
Con Roulettes armas campañas de gamificación sin tocar la consola. Le dices a tu agente qué premios quieres, con qué probabilidad, y él configura todo. Antes de crear cualquier cosa te muestra un preview para que revises — nada se guarda hasta que tú digas que sí.
Siempre llama list_roulette_items antes de proponer una ruleta, para saber qué items físicos están disponibles con stock.

​
Tools de lectura

​
roulettes_list_roulette_items

Lista los items de premio físico disponibles para este negocio. Llámala primero antes de proponer cualquier ruleta. Sin parámetros. Respuesta: cada item incluye _id, name, available_stock, y si está enabled_in_rewards. Solo los items con available_stock > 0 y enabled_in_rewards = true deben usarse como premios físicos en una ruleta. 
{
  "name": "roulettes_list_roulette_items",
  "arguments": {}
}

​
roulettes_get_roulette

Obtiene la configuración completa de una ruleta por su _id.
​
roulette_id
string
requerido
ID de la ruleta a consultar.
Respuesta: documento completo incluyendo gifts (con probabilidades, typeOfGift, item_id), typeOfRoulette, timers, términos, isActive y contadores (totalSpins). 
{
  "name": "roulettes_get_roulette",
  "arguments": {
    "roulette_id": "664f1a2b3c4d5e6f7a8b9c0d"
  }
}

​
roulettes_list_roulettes

Lista las ruletas existentes de este negocio. Sin parámetros. Respuesta incluye: _id, name, isActive, typeOfRoulette, contadores (totalSpins), createdAt. 
{
  "name": "roulettes_list_roulettes",
  "arguments": {}
}

​
Tools de escritura — Items

​
roulettes_propose_item

Genera un preview de un item de premio físico. No escribe a la base de datos. El country se hereda automáticamente del negocio.
​
name
string
requerido
Nombre del item.
​
available_stock
integer
requerido
Cantidad de stock disponible para premios.
​
description
string
predeterminado:"''"
Descripción del item.
​
currency
string
predeterminado:"'MXN'"
Moneda (código ISO 4217).
​
track_stock
boolean
predeterminado:"true"
Si se debe llevar control de inventario de este item.
​
enabled_in_rewards
boolean
predeterminado:"true"
Si el item está habilitado para ser usado como premio en ruletas.
{
  "name": "roulettes_propose_item",
  "arguments": {
    "name": "Audífonos Bluetooth",
    "available_stock": 50,
    "description": "Audífonos inalámbricos marca Nippy",
    "currency": "MXN",
    "track_stock": true,
    "enabled_in_rewards": true
  }
}

​
roulettes_create_item

Crea un nuevo item de premio físico. Mismos parámetros que propose_item.
Solo llama esta tool después de mostrar al usuario el preview de propose_item y recibir confirmación explícita.
Respuesta: {"_id": "...", "name": "Audífonos Bluetooth", "status": "created"}

​
Tools de escritura — Ruletas

​
roulettes_propose_roulette

Genera un preview de la configuración de una ruleta. No escribe a la base de datos.
​
name
string
requerido
Nombre de la ruleta.
​
gifts
array
requerido
Lista de objetos de premio. Cada gift debe contener:
  • value (string, requerido): nombre mostrado en la rueda
  • message (string, requerido): mensaje mostrado al ganar
  • probability (float, requerido): peso relativo (e.g. 80 = 80% de peso relativo entre todos los gifts)
  • typeOfGift (object, requerido): {"name": "...", "_id": "..."} — tipo de premio. El agente consulta automáticamente el catálogo de tipos disponibles.
  • emoji (string, opcional): emoji decorativo
  • quantity (int, opcional): unidades disponibles. Requerido para premios físicos
  • item_id (string, opcional): _id de list_roulette_items — solo para premios físicos. No confundir con typeOfGift._id
  • guaranteedForFirstTimers (bool, opcional)
  • winInterval (int, opcional)
  • fallback (string, opcional)
​
time_to_win
integer
requerido
Tiempo de animación al ganar (segundos).
​
time_to_lose
integer
requerido
Tiempo de animación al perder (segundos).
​
text_to_win
string
requerido
Texto mostrado cuando el usuario gana.
​
text_to_lose
string
requerido
Texto mostrado cuando el usuario pierde.
​
terms_and_conditions
string
requerido
Términos y condiciones de la ruleta.
​
roulette_type_id
integer
requerido
ID numérico del tipo de ruleta. Consulta nippy://roulettes/schema/gifts para opciones válidas.
​
roulette_type_name
string
requerido
Nombre del tipo de ruleta (e.g. "standard", "premium").
​
is_active
boolean
predeterminado:"false"
Si la ruleta se activa inmediatamente. Recomendado: false hasta que el usuario confirme.
​
time_unit
string
predeterminado:"'hours'"
Unidad de tiempo para la expiración: "hours", "days". Solo aplica si roulette_type_id lo soporta.
​
time_to_expire
integer
predeterminado:"24"
Tiempo hasta que expira la ruleta, en la unidad de time_unit.
​
max_wins
integer
predeterminado:"1"
Número máximo de premios que un usuario puede ganar en esta ruleta.
{
  "name": "roulettes_propose_roulette",
  "arguments": {
    "name": "Ruleta de Bienvenida Mayo 2026",
    "gifts": [
      {
        "value": "Audífonos Bluetooth",
        "message": "¡Ganaste unos Audífonos Bluetooth Nippy!",
        "probability": 10,
        "typeOfGift": {
          "name": "Fisico",
          "_id": "634f356e33e5c76785516a2d"
        },
        "emoji": "🎧",
        "quantity": 50,
        "item_id": "664f1a2b3c4d5e6f7a8b9c0d"
      },
      {
        "value": "10% descuento",
        "message": "¡Obtuviste 10% de descuento en tu próxima compra!",
        "probability": 30,
        "typeOfGift": {
          "name": "Porcentaje",
          "_id": "6342f530705c91dcbe8aba8b"
        },
        "emoji": "💰"
      },
      {
        "value": "Sigue participando",
        "message": "No ganaste esta vez. ¡Intenta de nuevo!",
        "probability": 60,
        "typeOfGift": {
          "name": "Perder",
          "_id": "634f356e33e5c76785516a2c"
        },
        "emoji": "😔"
      }
    ],
    "time_to_win": 5,
    "time_to_lose": 3,
    "text_to_win": "¡Felicidades!",
    "text_to_lose": "Sigue intentando",
    "terms_and_conditions": "Promoción válida del 1 al 31 de mayo de 2026. Aplican restricciones.",
    "roulette_type_id": 1,
    "roulette_type_name": "standard",
    "is_active": false,
    "time_to_expire": 24,
    "max_wins": 1
  }
}

​
roulettes_create_roulette

Crea una nueva ruleta para este negocio. Mismos parámetros que propose_roulette.
Solo llama esta tool después de mostrar al usuario el preview de propose_roulette y recibir confirmación explícita.
Respuesta: {"_id": "...", "name": "Ruleta de Bienvenida Mayo 2026", "status": "created"}
Referencias de esquemas para el agente:
URINombreDescripción
nippy://roulettes/schema/giftsroulettes_gift_typesCatálogo de valores typeOfGift y opciones de typeOfRoulette
nippy://roulettes/schema/fieldsroulettes_field_referenceCampos de documentos de ruleta e items
IDs del catálogo de typeOfGift:
Tipo_id
Porcentaje6342f530705c91dcbe8aba8b
Perder634f356e33e5c76785516a2c
Points68b86722b5a6eee84f241985

​
Notas importantes

  • Los typeOfGift._id deben venir del catálogo oficial — no inventes IDs.
  • El item_id de un premio físico va en el campo item_id del gift, no en typeOfGift._id.
  • Siempre incluye al menos un slot de tipo “Perder”.
  • El country de items y ruletas se hereda automáticamente del negocio.
  • Mantén is_active: false hasta que el usuario explícitamente pida activar la ruleta.