Logo de WAzion
CENTRO DE AYUDA

Funciones Personalizadas IA

Permite que la IA de WAzion llame a tus APIs externas durante las conversaciones para consultar información o ejecutar acciones en tiempo real.

1. Introducción

Las Funciones Personalizadas permiten que la IA de WAzion llame a tus APIs externas durante una conversación con un cliente. Esto permite consultar información en tiempo real o ejecutar acciones automáticamente.

¿Cómo funciona?

  1. 1 El cliente pregunta algo (ej: “¿Tienen disponible el producto X?“)
  2. 2 La IA detecta que necesita información externa
  3. 3 WAzion llama a tu API con los parámetros necesarios
  4. 4 Tu API responde con la información solicitada
  5. 5 La IA usa esa información para responder al cliente

Casos de uso típicos

  • • Consultar disponibilidad de productos/servicios
  • • Realizar reservas automáticas
  • • Consultar estado de pedidos
  • • Consultar precios dinámicos
  • • Buscar información de clientes
  • • Verificar horarios disponibles

2. Estructura JSON

Las funciones se definen como un array JSON. Cada función tiene un nombre, descripción y parámetros que incluyen el endpoint a llamar. 

[
  {
    "name": "nombreDeLaFuncion",
    "description": "Descripción clara de qué hace esta función",
    "parameters": {
      "type": "object",
      "properties": {
        "parametro1": {
          "type": "string",
          "description": "Descripción del parámetro"
        },
        "parametro2": {
          "type": "number",
          "description": "Otro parámetro"
        },
        "endpoint": {
          "url": "https://tu-api.com/endpoint",
          "method": "GET",
          "format": "json",
          "auth": {
            "type": "header",
            "fields": {
              "Authorization": "Bearer tu-token-aqui"
            }
          }
        }
      },
      "required": ["parametro1"]
    }
  }
]

Campos principales

  • name: Identificador único de la función
  • description: Describe cuándo usar esta función
  • parameters: Define los parámetros y el endpoint

Objeto endpoint

  • url: URL completa del endpoint (HTTPS)
  • method: GET, POST, PUT, DELETE, PATCH
  • format: json o form
  • auth: Configuración de autenticación

Importante: La descripción de cada función y parámetro es crucial. La IA usa estas descripciones para decidir cuándo llamar a cada función.

3. Tipos de Autenticación

WAzion soporta 4 tipos de autenticación para proteger tus endpoints:

Header Auth (Recomendado)

Más seguro

Envía credenciales como headers HTTP. Ideal para tokens Bearer o API Keys.

"auth": {
  "type": "header",
  "fields": {
    "Authorization": "Bearer tu-token-secreto",
    "X-API-Key": "otra-clave-si-necesitas"
  }
}

Basic Auth

Autenticación HTTP básica con usuario y contraseña (codificados en Base64).

"auth": {
  "type": "basic",
  "fields": {
    "username": "tu-usuario",
    "password": "tu-contraseña"
  }
}

Query Auth

Envía credenciales como parámetros en la URL. Menos seguro pero simple.

"auth": {
  "type": "query",
  "fields": {
    "api_key": "tu-api-key",
    "secret": "tu-secret"
  }
}
// Resultado: ?api_key=tu-api-key&secret=tu-secret

Body Auth

Incluye credenciales en el body de la petición (solo POST/PUT/PATCH).

"auth": {
  "type": "body",
  "fields": {
    "api_key": "tu-api-key",
    "token": "tu-token"
  }
}
// Se añade al JSON del body junto con los parámetros

Sin autenticación

Si tu endpoint no requiere autenticación, simplemente omite el campo “auth“ del objeto endpoint.

4. Especificaciones Técnicas

Timeouts

Timeout total 60s
Connect timeout 10s

Reintentos

Máximo de intentos 4
Estrategia Backoff exponencial

Calendario de reintentos

Intento 1 Inmediato
Intento 2 2s
Intento 3 4s
Intento 4 8s

Headers HTTP enviados

Header Valor
Content-Type application/json
Accept application/json
User-Agent WAzion-Functions/1.0
+ Headers de autenticación Según configuración

Códigos HTTP que activan reintento

429 500 502 503 504

Códigos sin reintento

400 401 403 404

Requisitos del endpoint

  • HTTPS obligatorio (certificado SSL válido)
  • Respuesta en formato JSON válido
  • Content-Type: application/json en la respuesta
  • Respuesta en menos de 60 segundos

Parámetro reservado: phone

Si tu función declara un parámetro llamado “phone“, WAzion lo sobreescribirá automáticamente con el teléfono del cliente actual en formato E.164 (ej: +34612345678). Esto garantiza que siempre se use el teléfono correcto del cliente con quien se está conversando, independientemente del valor que envíe la IA. Úsalo para enviar notificaciones, registrar consultas o personalizar respuestas según el cliente.

5. Ejemplos Prácticos

Ejemplo 1: Consultar disponibilidad

Permite a la IA consultar si un producto está disponible en stock.

[
  {
    "name": "consultarDisponibilidad",
    "description": "Consulta si un producto específico está disponible en stock",
    "parameters": {
      "type": "object",
      "properties": {
        "producto": {
          "type": "string",
          "description": "Nombre o referencia del producto a consultar"
        },
        "cantidad": {
          "type": "number",
          "description": "Cantidad deseada (opcional, por defecto 1)"
        },
        "endpoint": {
          "url": "https://tu-tienda.com/api/stock",
          "method": "GET",
          "format": "json",
          "auth": {
            "type": "header",
            "fields": {
              "Authorization": "Bearer token-secreto-123"
            }
          }
        }
      },
      "required": ["producto"]
    }
  }
]

Ejemplo 2: Crear una reserva

Permite a la IA crear reservas automáticamente en tu sistema.

[
  {
    "name": "crearReserva",
    "description": "Crea una reserva para el cliente en la fecha y hora indicada",
    "parameters": {
      "type": "object",
      "properties": {
        "nombre_cliente": {
          "type": "string",
          "description": "Nombre completo del cliente"
        },
        "fecha": {
          "type": "string",
          "description": "Fecha de la reserva en formato YYYY-MM-DD"
        },
        "hora": {
          "type": "string",
          "description": "Hora de la reserva en formato HH:MM"
        },
        "servicio": {
          "type": "string",
          "description": "Tipo de servicio a reservar"
        },
        "endpoint": {
          "url": "https://tu-negocio.com/api/reservas",
          "method": "POST",
          "format": "json",
          "auth": {
            "type": "header",
            "fields": {
              "X-API-Key": "mi-api-key-secreta"
            }
          }
        }
      },
      "required": ["nombre_cliente", "fecha", "hora", "servicio"]
    }
  }
]

Ejemplo 3: Consultar estado de pedido

Permite a la IA consultar el estado de un pedido usando su número de referencia.

[
  {
    "name": "consultarPedido",
    "description": "Consulta el estado de envío de un pedido por su número",
    "parameters": {
      "type": "object",
      "properties": {
        "numero_pedido": {
          "type": "string",
          "description": "Número de pedido o referencia"
        },
        "endpoint": {
          "url": "https://tu-tienda.com/api/pedidos/estado",
          "method": "GET",
          "format": "json",
          "auth": {
            "type": "query",
            "fields": {
              "token": "mi-token-secreto"
            }
          }
        }
      },
      "required": ["numero_pedido"]
    }
  }
]

6. Código de Ejemplo

Ejemplos de cómo implementar los endpoints en tu servidor:

PHP 
<?php
// Endpoint: /api/stock

header('Content-Type: application/json');

// Verificar autenticación
$authHeader = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
if ($authHeader !== 'Bearer token-secreto-123') {
    http_response_code(401);
    echo json_encode(['error' => 'Unauthorized']);
    exit;
}

// Get parameters
$producto = $_GET['producto'] ?? '';
$cantidad = intval($_GET['cantidad'] ?? 1);

// Query your database
$stock = consultarStockEnBD($producto);

// Respond
echo json_encode([
    'producto' => $producto,
    'disponible' => $stock >= $cantidad,
    'stock_actual' => $stock,
    'mensaje' => $stock >= $cantidad
        ? "Yes, we have $stock units available"
        : "Sorry, only $stock units left"
]);
Node.js / Express 
// Endpoint: /api/stock

app.get('/api/stock', (req, res) => {
  // Verificar autenticación
  const authHeader = req.headers.authorization;
  if (authHeader !== 'Bearer token-secreto-123') {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  // Get parameters
  const { producto, cantidad = 1 } = req.query;

  // Query your database
  const stock = consultarStockEnBD(producto);

  // Respond
  res.json({
    producto,
    disponible: stock >= cantidad,
    stock_actual: stock,
    mensaje: stock >= cantidad
      ? `Yes, we have ${stock} units available`
      : `Sorry, only ${stock} units left`
  });
});
Python / Flask 
# Endpoint: /api/stock

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/api/stock', methods=['GET'])
def consultar_stock():
    # Verificar autenticación
    auth_header = request.headers.get('Authorization', '')
    if auth_header != 'Bearer token-secreto-123':
        return jsonify({'error': 'Unauthorized'}), 401

    # Get parameters
    producto = request.args.get('producto', '')
    cantidad = int(request.args.get('cantidad', 1))

    # Query your database
    stock = consultar_stock_en_bd(producto)

    # Respond
    return jsonify({
        'producto': producto,
        'disponible': stock >= cantidad,
        'stock_actual': stock,
        'mensaje': f'Yes, we have {stock} units available'
            if stock >= cantidad
            else f'Sorry, only {stock} units left'
    })

Historial de cambios

Sin cambios recientes en esta documentación.

Artículos relacionados

Endpoints CRM →

Conecta WAzion con tu CRM externo

Webhooks →

Recibe eventos en tiempo real

Asistente WAzion

Informacion comercial y soporte tecnico

Hola! Soy el asistente de WAzion. Puedo ayudarte con informacion sobre precios y planes, dudas tecnicas, configuracion, o cualquier pregunta sobre nuestro producto. Como puedo ayudarte?
Desarrollado con WAzion AI