Fonctions personnalisées IA - Documentation technique WAzion

1. Introduction

Les Fonctions Personnalisées permettent à l’IA de WAzion d’appeler vos API externes lors d’une conversation avec un client. Cela permet de consulter des informations en temps réel ou d’exécuter des actions automatiquement.

Comment ça fonctionne ?

1 Le client pose une question (par ex. : « Avez-vous le produit X en stock ? »)
2 L’IA détecte qu’elle a besoin d’informations externes
3 WAzion appelle ton API avec les paramètres nécessaires
4 Ton API répond avec les informations demandées
5 L’IA utilise ces informations pour répondre au client

Cas d’utilisation typique

• Consulter la disponibilité des produits/services
• Effectuer des réservations automatiques
• Consulter l’état des commandes
• Consulter les prix dynamiques
• Rechercher des informations sur les clients
• Vérifier les horaires disponibles

2. Structure JSON

Les fonctions sont définies comme un tableau JSON. Chaque fonction a un nom, une description et des paramètres incluant le point de terminaison à appeler.

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

Champs principaux

name: Identifiant unique de la fonction
description: Décris quand utiliser cette fonction
parameters: Définissez les paramètres et le point de terminaison

Objet de point de terminaison

url: URL complète du point de terminaison (HTTPS)
method: GET, POST, PUT, DELETE, PATCH
format: json ou form
auth: Configuration d’authentification

Important : La description de chaque fonction et paramètre est cruciale. L’IA utilise ces descriptions pour décider quand appeler chaque fonction.

3. Types d’Authentification

WAzion prend en charge 4 types d’authentification pour protéger vos points de terminaison :

Authentification d’en-tête (Recommandé)

Plus sûr

Envoie les identifiants comme en-têtes HTTP. Idéal pour les tokens Bearer ou les clés API.

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

Basic Auth

Authentification HTTP basique avec nom d’utilisateur et mot de passe (codés en Base64).

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

Query Auth

Envoie des identifiants en tant que paramètres dans l’URL. Moins sûr mais simple.

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

Body Auth

Incluez les informations d’identification dans le corps de la requête (uniquement 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

Sans authentification

Si ton endpoint ne nécessite pas d’authentification, il suffit d’omettre le champ “auth“ de l’objet endpoint.

4. Spécifications Techniques

Délai d’attente

Temps d’attente total	60s
Délai de connexion dépassé	10s

Tentatives répétées

Nombre maximum de tentatives	4
Stratégie	Recul exponentiel

Calendrier de nouvelles tentatives

Essai 1	Immédiat
Essai 2	2s
Essai 3	4s
Essai 4	8s

En-têtes HTTP envoyés

Header	Valeur
Content-Type	application/json
Accept	application/json
User-Agent	WAzion-Functions/1.0
+ En-têtes d’authentification	Selon la configuration

Codes HTTP qui déclenchent une nouvelle tentative

429 500 502 503 504

Codes sans nouvelle tentative

400 401 403 404

Exigences du point de terminaison

HTTPS obligatoire (certificat SSL valide)
{ “Respuesta“: “en formato JSON válido“ }
Content-Type: application/json dans la réponse
Réponse en moins de 60 secondes

Paramètre spécial : _phone

WAzion ajoute automatiquement le paramètre “_phone“ avec le téléphone du client au format E.164 (ex : +34612345678). Vous pouvez l’utiliser pour personnaliser la réponse ou enregistrer qui a fait la demande.

5. Exemples pratiques

Exemple 1 : Consulter la disponibilité

Permet à l’IA de vérifier si un produit 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"]
    }
  }
]

Exemple 2 : Créer une réservation

Permets à l’IA de créer des réservations automatiquement dans ton système.

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

Exemple 3 : Consulter l’état de la commande

Permet à l’IA de consulter l’état d’une commande en utilisant son numéro de référence.

[
  {
    "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. Exemple de code

Exemples de la manière d’implémenter les points de terminaison sur votre serveur :

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

Historique des modifications

Pas de modifications récentes dans cette documentation.

Articles connexes

Points de terminaison CRM →

Connecte WAzion avec ton CRM externe

Webhooks →

Reçoit des événements en temps réel