Egyedi MI funkciók - Technikai dokumentáció WAzion

1. Bevezetés

A Testreszabott Funkciók lehetővé teszik, hogy a WAzion MI-je hívja a külső API-jaidat egy ügyféllel folytatott beszélgetés során. Ez lehetővé teszi valós idejű információk lekérését vagy automatikus műveletek végrehajtását.

Hogyan működik?

1 Az ügyfél kérdez valamit (pl.: “Elérhető az X termék?“)
2 Az MI érzékeli, hogy külső információra van szüksége
3 A WAzion meghívja az API-dat a szükséges paraméterekkel
4 Az API-ja a kért információval válaszol.
5 A MI ezeket az információkat használja fel a válaszadás során az ügyfélnek.

Tipikus felhasználási esetek

• Termékek/szolgáltatások elérhetőségének lekérdezése
• Automatikus foglalások végrehajtása
• Rendelések állapotának lekérdezése
• Dinamikus árak lekérdezése
• Ügyfélinformációk keresése
• Ellenőrizze az elérhető időpontokat

2. JSON struktúra

A funkciók JSON tömbként vannak definiálva. Minden funkciónak van egy neve, leírása és paraméterei, amelyek tartalmazzák a meghívandó végpontot.

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

Fő mezők

name: A funkció egyedi azonosítója
description: Írd le, mikor kell használni ezt a funkciót
parameters: Határozza meg a paramétereket és a végpontot

Végpont objektum

url: Az endpoint teljes URL-je (HTTPS)
method: GET, POST, PUT, DELETE, PATCH
format: json vagy form
auth: Hitelesítési beállítások

Fontos: Minden függvény és paraméter leírása kulcsfontosságú. Az MI ezeket a leírásokat használja annak eldöntésére, hogy mikor hívjon meg egy-egy függvényt.

3. Hitelesítési típusok

A WAzion négyféle hitelesítést támogat az endpointok védelme érdekében:

Fejléc hitelesítés (ajánlott)

Biztonságosabb

Hitelesítő adatokat HTTP fejlécben küld. Ideális Bearer tokenekhez vagy API kulcsokhoz.

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

Basic Auth

HTTP alapú alapszintű hitelesítés felhasználónévvel és jelszóval (Base64-ben kódolva).

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

Query Auth

Hitelesítő adatokat küld paraméterként az URL-ben. Kevésbé biztonságos, de egyszerű.

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

Body Auth

A hitelesítő adatokat a kérés törzsében kell megadni (csak POST/PUT/PATCH esetén).

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

Hitelesítés nélkül

Ha az endpointod nem igényel hitelesítést, egyszerűen hagyd ki az “auth“ mezőt az endpoint objektumból.

4. Műszaki specifikációk

Időtúllépések

Teljes időkorlát	60s
Kapcsolódási időtúllépés	10s

Újrapróbálkozások

Maximális kísérletek száma	4
Stratégia	Eksponenciális visszalépés

Újrapróbálkozási naptár

Kísérlet 1	Azonnali
Kísérlet 2	2s
Kísérlet 3	4s
Kísérlet 4	8s

Elküldött HTTP fejlécek

Header	Érték
Content-Type	application/json
Accept	application/json
User-Agent	WAzion-Functions/1.0
+ Hitelesítési fejlécelések	Beállítás szerint

HTTP-kódok, amelyek újrapróbálkozást váltanak ki

429 500 502 503 504

Kódok újrapróbálás nélkül

400 401 403 404

Az végpont követelményei

Kötelező HTTPS (érvényes SSL tanúsítvány)
{ “Respuesta“: “Érvényes JSON formátumban“ }
Content-Type: application/json a válaszban
Válasz kevesebb mint 60 másodperc alatt

Fenntartott paraméter: phone

Ha a funkciód deklarál egy “phone“ nevű paramétert, a WAzion automatikusan felülírja azt az aktuális ügyfél telefonszámával E.164 formátumban (pl.: +34612345678). Ez garantálja, hogy mindig az ügyfél helyes telefonszámát használják, akivel éppen beszélgetnek, függetlenül attól, hogy mit küld az IA. Használja ezt értesítések küldésére, lekérdezések rögzítésére vagy válaszok testreszabására az ügyfél szerint.

5. Gyakorlati példák

1. példa: Elérhetőség lekérdezése

Lehetővé teszi az MI számára, hogy lekérdezze, elérhető-e egy termék a raktáron.

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

2. példa: Foglalás készítése

Engedélyezd az MI számára, hogy automatikusan foglalásokat hozzon létre a rendszeredben.

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

3. példa: Rendelés állapotának lekérdezése

Lehetővé teszi a MI számára, hogy a rendelés állapotát a hivatkozási számával ellenőrizze.

[
  {
    "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. Példa Kód

Példák arra, hogyan valósítsd meg a végpontokat a szervereden:

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

Változási előzmények

Nincs a közelmúltban történt változás ebben a dokumentációban.

Kapcsolódó cikkek

CRM végpontok →

Csatlakoztasd a WAziont a külső CRM-edhez

Webhookok →

Valós idejű események fogadása