Logo di WAzion
CENTRO ASSISTENZA

Funzioni personalizzate AI

Consenti all’IA di WAzion di chiamare le tue API esterne durante le conversazioni per consultare informazioni o eseguire azioni in tempo reale.

1. Introduzione

Le Funzioni Personalizzate permettono all’IA di WAzion di chiamare le tue API esterne durante una conversazione con un cliente. Questo consente di consultare informazioni in tempo reale o di eseguire azioni automaticamente.

Come funziona?

  1. 1 Il cliente chiede qualcosa (es: “Avete disponibile il prodotto X?“)
  2. 2 L’IA rileva che ha bisogno di informazioni esterne
  3. 3 WAzion chiama la tua API con i parametri necessari
  4. 4 La tua API risponde con le informazioni richieste
  5. 5 L’IA usa quelle informazioni per rispondere al cliente

Casi d’uso tipici

  • • Verificare la disponibilità di prodotti/servizi
  • • Effettuare prenotazioni automatiche
  • • Consultare lo stato degli ordini
  • • Consultare prezzi dinamici
  • • Cercare informazioni sui clienti
  • • Verificare gli orari disponibili

2. Struttura JSON

Le funzioni sono definite come un array JSON. Ogni funzione ha un nome, una descrizione e parametri che includono l’endpoint da chiamare. 

[
  {
    "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"]
    }
  }
]

Campi principali

  • name: Identificatore univoco della funzione
  • description: Descrivi quando usare questa funzione
  • parameters: Definisce i parametri e l’endpoint

Oggetto endpoint

  • url: URL completa dell’endpoint (HTTPS)
  • method: GET, POST, PUT, DELETE, PATCH
  • format: json El tiempo es oro. form
  • auth: Configurazione di autenticazione

Importante: La descrizione di ciascuna funzione e parametro è cruciale. L’IA utilizza queste descrizioni per decidere quando chiamare ogni funzione.

3. Tipi di Autenticazione

WAzion supporta 4 tipi di autenticazione per proteggere i tuoi endpoint:

Header Auth (Consigliato)

Più sicuro

Invia le credenziali come header HTTP. Ideale per token Bearer o API Key.

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

Basic Auth

Autenticazione HTTP di base con nome utente e password (codificati in Base64).

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

Query Auth

Invia le credenziali come parametri nell’URL. Meno sicuro ma semplice.

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

Body Auth

Includi le credenziali nel corpo della richiesta (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

Senza autenticazione

Se il tuo endpoint non richiede autenticazione, semplicemente ometti il campo “auth“ dall’oggetto endpoint.

4. Specifiche Tecniche

Timeout

Timeout totale 60s
Timeout di connessione 10s

Ritenti

Numero massimo di tentativi 4
Strategia Backoff esponenziale

Calendario di ritentativi

Tentativo 1 Immediato
Tentativo 2 2s
Tentativo 3 4s
Tentativo 4 8s

Header HTTP inviati

Header Valore
Content-Type application/json
Accept application/json
User-Agent WAzion-Functions/1.0
+ Intestazioni di autenticazione Secondo configurazione

Codici HTTP che attivano il tentativo di nuovo

429 500 502 503 504

Codici senza ritentativo

400 401 403 404

Requisiti dell’endpoint

  • HTTPS obbligatorio (certificato SSL valido)
  • { “Respuesta“: “in formato JSON valido“ }
  • Content-Type: application/json nella risposta
  • Risposta in meno di 60 secondi

Parametro speciale: _phone

WAzion aggiunge automaticamente il parametro “_phone“ con il numero di telefono del cliente in formato E.164 (es: +34612345678). Puoi usarlo per personalizzare la risposta o per registrare chi ha effettuato la richiesta.

5. Esempi Pratici

Esempio 1: Consultare la disponibilità

Consente all’IA di verificare se un prodotto è disponibile in magazzino.

[
  {
    "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"]
    }
  }
]

Esempio 2: Creare una prenotazione

Permette all’IA di creare prenotazioni automaticamente nel tuo 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"]
    }
  }
]

Esempio 3: Consultare lo stato dell’ordine

Consente all’IA di consultare lo stato di un ordine utilizzando il suo numero di riferimento.

[
  {
    "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. Codice di esempio

Esempi di come implementare gli endpoint nel tuo server:

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' => 'No autorizado']);
    exit;
}

// Obtener parámetros
$producto = $_GET['producto'] ?? '';
$cantidad = intval($_GET['cantidad'] ?? 1);

// Consultar tu base de datos
$stock = consultarStockEnBD($producto);

// Responder
echo json_encode([
    'producto' => $producto,
    'disponible' => $stock >= $cantidad,
    'stock_actual' => $stock,
    'mensaje' => $stock >= $cantidad
        ? "Sí, tenemos $stock unidades disponibles"
        : "Lo sentimos, solo quedan $stock unidades"
]);
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: 'No autorizado' });
  }

  // Obtener parámetros
  const { producto, cantidad = 1 } = req.query;

  // Consultar tu base de datos
  const stock = consultarStockEnBD(producto);

  // Responder
  res.json({
    producto,
    disponible: stock >= cantidad,
    stock_actual: stock,
    mensaje: stock >= cantidad
      ? `Sí, tenemos ${stock} unidades disponibles`
      : `Lo sentimos, solo quedan ${stock} unidades`
  });
});
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': 'No autorizado'}), 401

    # Obtener parámetros
    producto = request.args.get('producto', '')
    cantidad = int(request.args.get('cantidad', 1))

    # Consultar tu base de datos
    stock = consultar_stock_en_bd(producto)

    # Responder
    return jsonify({
        'producto': producto,
        'disponible': stock >= cantidad,
        'stock_actual': stock,
        'mensaje': f'Sí, tenemos {stock} unidades disponibles'
            if stock >= cantidad
            else f'Lo sentimos, solo quedan {stock} unidades'
    })

Cronologia delle modifiche

Nessuna modifica recente in questa documentazione.

Articoli correlati

Endpoint CRM →

Collega WAzion al tuo CRM esterno

Webhooks →

Riceve eventi in tempo reale

Assistente WAzion

Informazioni commerciali e supporto tecnico

Ciao! Sono l’assistente di WAzion. Posso aiutarti con informazioni su prezzi e piani, dubbi tecnici, configurazione o qualsiasi domanda sul nostro prodotto. Come posso aiutarti?
Sviluppato con WAzion AI